Vivarium

Build OpenWrt packages using Docker and the OpenWrt SDK

Introduction

Vivarium is a way to compile packages for OpenWrt without having to
install the necessary build tools, using
Docker.

Vivarium includes a “builder” Dockerfile for a local Docker image, based
on the OpenWrt SDK Docker image. This local image will have the
OpenWrt SDK set up inside.

This also includes a Docker Compose file that holds all of the
configuration options. The Compose file also sets up a number of bind
mounts, allowing access to package source code from the Docker container
and access to build artifacts from the host machine.

Requirements

Docker and Docker Compose
will need to be installed.

Some familiarity with Docker and the OpenWrt
build system / SDK will be
necessary.

Vivarium has only been tested with Ubuntu Linux. Testing with other
platforms is welcome.

Getting started

Download the latest release and extract.

If you will be using Git to manage your package source code, then
you will want to download Vivarium without Git to avoid nesting Git
repositories.
Change the TAG build option in docker-compose.yml to select
which SDK image to use.

Other options can be customized in docker-compose.yml; see
Configuration.
Add any custom packages into the packages directory.

The packages directory will be added as a custom feed.
Build the local “builder” Docker image:
```
$ sudo docker-compose build
```

Set the appropriate ownership for subdirectories inside the sdk
directory:

$ sudo docker-compose run --rm --user root --entrypoint /vivarium/set-ownership.sh builder

Build packages by using docker-compose run, e.g.:
```
$ sudo docker-compose run --rm builder make package/slide-switch/compile V=s
```
If the build was successful, the compiled packages will be in the
sdk/bin directory.

If you are using an older version of Docker (<1.13.0) or Docker Compose
(<1.10.0), you will need to change version in docker-compose.yml
from "3" to "2". Vivarium has not been tested with these older
versions though; upgrading to the latest versions of Docker and Docker
Compose is recommended.

During each builder run, these SDK commands:

./scripts/feeds update -a
./scripts/feeds install -a
make defconfig

will be run before the command specified on the docker-compose run
command line.

Directory structure

builder: Files that define the local “builder” Docker image.
packages: Source code for custom packages (added manually).
sdk: Subdirectories in here are bind mounted into various places
within the SDK inside the builder container, to cache results and
allow build artifacts to be inspected from the host machine.
- sdk/bin: Compiled package files (*.ipk).
- sdk/build_dir: Where program source code is extracted and
  compiled.
- sdk/dl: Archives downloaded during package build.
- sdk/feeds: Where package feeds are checked out / cloned.
- sdk/logs: Build logs (if enabled) and feed error logs. During
  each builder run, the generated config file (.config) is also
  copied into here as config.
- sdk/package/feeds: Symbolic links to packages in sdk/feeds.
- sdk/staging_dir: Supporting files installed by host and target
  packages, for use when compiling other target packages.
- sdk/tmp: Temporary files.
Subdirectories with “special” functionality:
- sdk/overrides: Files placed here will be copied into the SDK
  directory in the builder container, allowing files to be
  overriden directly.
  
  Specifically, if there is a file named diffconfig in this
  directory, it will be copied to .config inside the builder
  container, which will then be expanded by make defconfig.

Configuration

All options can be found in the docker-compose.yml file.

Image build options

CONTAINER, TAG: Which SDK image to use.

SDK image tags are in the format:
```
<target>-<subtarget>-<branch|tag|version>
```
Available tags can be found at Docker Hub.

Run-time options

USE_GITHUB_FEEDS: Clone package feeds from GitHub instead of
git.openwrt.org (y or n).

Cloning from GitHub will likely be faster.
CONFIG_AUTOREMOVE, CONFIG_BUILD_LOG: Sets the corresponding SDK
config options (y or n).

Rebuild local Docker image

The local “builder” Docker image can be rebuilt to update or change the
SDK used:

$ sudo docker-compose build

Cleaning up

The SDK clean targets (make clean, make dirclean) are not aware of the Docker bind mounts and so will not work
correctly.

Included are scripts that emulate these SDK commands:

$ sudo docker-compose run --rm --entrypoint /vivarium/clean.sh builder

Available scripts:

/vivarium/clean.sh: Clears sdk/bin, sdk/build_dir, and sdk/staging_dir
/vivarium/dirclean.sh: Clears all subdirectories in sdk

License

Vivarium is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.

Vivarium is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Vivarium. If not, see https://www.gnu.org/licenses.