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.
| 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.
Before you started you need to choose what version of Turris OS you want to
build. There are development versions in branches named hbk, hbl and hbd
(see workflow). Then there are tagged final releases. Those
are in format of for example v4.0.0 for Turris OS 4.0.0 or v4.1.2 for Turris
OS 4.1.2.
To get to appropriate version you have to run command like this:
git checkout hbk where in this case this takes you to development branch for
Turris OS fixup releases.
It is advised to build the latest release version as with that you are most likely
to get to the end. To get latest version you can do:
git checkout $(git tag | sort | tail -1).
Requirements
You need to have a GNU/Linux distribution to be able to compile Turris OS and packages.
To install all dependencies for Debian distribution you can use:
apt install ca-certificates git build-essential zlib1g-dev gawk libssl-dev subversion unzip libncurses-dev wget python file rsync gcc-multilib
For other distributions, we suggest to look at OpenWrt documentation.
Advanced usage
Building packages
To build a 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 can build packages 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.
Development and maintenance
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.
Releasing new version
When new version is released to Snails (see workflow for explanation) then new
commit with hashes has to be created and pushed. This commit have to be tagged
with appropriate version tag in format vVERSION where VERSION is released
version. To make this all simple and to correctly set always all configurations we
have script helpers/new_release.sh. Run this script after release from
turris-build project root directory and it is going to automatically detect,
commit and tag new version. You should review commit and tag it created for you
and then push it using git push --tags.
Script helpers/new_release.sh can generate various errors and warnings. It is
advised to run it even before release in verify mode to review possible problems
with release.
Forking new release
According to workflow new releases are forked from parent branch. During this process care should be taken to tweak defaults to appropriate values. Following list should be taken as a checklist for new release branch.
-
Set
PUBLISH_BRANCHindefaults.sh. Master branch should always be set tohbdand release branches should be set tohbs. -
Set branches in
feeds.conf. You should append string like this:;openwrt-18.06. This has to be done for all OpenWRT feeds as well for OpenWRT it self. URL used bycompile_pkgsis specified as first line infeeds.confand with exception of first column it has same format as feeds. Note that that line is intentionally commented out as that is not feed.
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.