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. [TIP] *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 if you want to build * stable release of OpenWrt (Turris OS 4.x), you need to checkout for `v4.0` branch * master release of OpenWrt (Turris OS 5.x), you need to checkout for `master` branch. To use specific stable release you have to checkout that specific tag. Please see all available tags in repository. 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 -- For other distributions, we suggest to look at https://openwrt.org/docs/guide-developer/build-system/install-buildsystem[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> -- <2> ~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_BRANCH` in `defaults.sh`. Master branch should always be set to `hbd` and release branches should be set to `hbs`. . 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 by `compile_pkgs` is specified as first line in `feeds.conf` and 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.