README.asciidoc

Simple Turris OS building script

Getting started

Create an empty directory you want to build Turris OS in, enter that directory and from it call compile_pkgs script. In most basic use-case, this should be enough. Be aware - it will delete all previous content of the current directory. You can repeat individual steps of the compilation separately, check with the following command compile_pkgs --help for a list of available commands, generic options, and their brief descriptions.

Advanced usage

Configuration

Default config for OpenWRT is put in configs directory either in directory common or in a directory named after the target board. Files in those directories get merged (common ones first) and will form the final .config file. Some parts of compile_pkgs might modify it further.

Release notes

There is a NEWS file in this directory that contains the version number and after it lines with new features in the release. This file is used to generate turris-version package. compile_pkgs script reads it, finds the newest version and from notes underneath it creates the package with release notes.

Patching

If you need to patch OpenWRT or any of the feeds, put a git formatted patch into the respective subdirectory of patches directory. In patches directory, there is openwrt directory and directory for each feed we are patching. Inside those directories, patches are also divided into subdirectories like to-upstream, wip or hack to somehow distinguish between the quality of patches.

Rebasing patches

Sometimes patches no longer apply cleanly and need to be rebased. The most simple way to do that, given that we have everything in git, is the following:

find . -name '*.rej' -delete                # Clean all existing reject files
git am --reject .../patches/.../xyz.patch   # Try hard to apply patch
find . -name '*.rej'                        # List all failed chunks

After those commands, we’ll get our git tree in partially merged state and with few .rej files containing failed chunks. Actually, compile_pkgs script by default cleans up checkout directory and applies patches with git am --reject so if the build fails, checkout ends up in the state similar to what can be achieved by those commands. Files with .rej extension needs to be merged manually and afterward, we need to call git add on newly patched files. Once all conflicts are resolved, git am --continue will create real commit that we were trying to add using git am. Now all that is left is to export it using git format-patch -1 and overwrite patch stored in it of build repository.

Building a single package

To build only one package you have to first prepare build directory. That can be achieved by running in target directory.

compile_pkgs prepare_tools -t board (1)

1	-t means -target, so only valid values are turris, omnia, mox.

Be aware it removes previous content of current directory!

Once, you have compiled required tools, you need enter build directory and then run make menuconfig, select the package you want to compile and save it. Then you can build it using this command:

make package/name/compile (2)

1	name is package name, which you want to compile.

You can also clean single package just by replacing compile with clean.

The resulting package is placed in directory bin/packages/_ARCH/_REPO

;; ARCH is target architecture specific string. ;; REPO is the name of package’s source repository.

Occasionally, you can meet cases, where you need to run make package/name/compile with parameters -j1 V=s or -j1 V=sc to be able to see, what went wrong.