diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index 2f9b862cc9..07d72ae92e 100644 --- a/doc/doxygen/riot.doxyfile +++ b/doc/doxygen/riot.doxyfile @@ -764,6 +764,7 @@ INPUT = ../../doc.txt \ src/porting-boards.md \ src/driver-guide.md \ src/getting-started.md \ + src/build-in-docker.md \ ../../tests/README.md \ src/build-system-basics.md \ src/kconfig/kconfig.md \ diff --git a/doc/doxygen/src/build-in-docker.md b/doc/doxygen/src/build-in-docker.md new file mode 100644 index 0000000000..d194e5649e --- /dev/null +++ b/doc/doxygen/src/build-in-docker.md @@ -0,0 +1,125 @@ +# Build In Docker {#build-in-docker} + +Some parts of RIOT's build process can be performed inside a Docker container, +which comes with the necessary compilers and toolchains and is fully managed by +the build system. It can be enabled by passing `BUILD_IN_DOCKER=1` to make. + +```shell +$ BUILD_IN_DOCKER=1 make +``` + +If your user does not have permissions to access the Docker daemon: + +```shell +$ BUILD_IN_DOCKER=1 DOCKER="sudo docker" make +``` + +to always use Docker for building, set `BUILD_IN_DOCKER=1` (and if necessary +`DOCKER="sudo docker"`) in the environment: + +```console +$ export BUILD_IN_DOCKER=1 +``` + +## Targets ran in Docker: DOCKER_MAKECMDGOALS_POSSIBLE + +Currently only build related targets are ran in the docker container, the exact +list is under `DOCKER_MAKECMDGOALS_POSSIBLE` variable. + +## Environment Variables: DOCKER_ENV_VARS + +When building in docker one might want for the command ran in docker to inherit +variables that might have been set in the command line. e.g.: + +```shell +BOARD=samr21-xpro USEMODULE=xtimer make -C examples/hello-world +``` + +In `docker.ink.mk` the origin of a variable listed in `DOCKER_ENV_VARS` is checked +and if the origin is `environment` or `command` (for make command-line argument) +then those variables will be passed to the docker container. + +You can also set in `DOCKER_ENV_VARS` in the environment to add variables to the +list, e.g.: + +```shell +DOCKER_ENV_VARS=BEER_TYPE BEER_TYPE="imperial stout" BUILD_IN_DOCKER=1 make -C examples/hello-world/ +docker run --rm -t -u "$(id -u)" \ + ... + -e 'BEER_TYPE=imperial stout' \ + -w '/data/riotbuild/riotbase/examples/hello-world/' \ + 'riot/riotbuild:latest' make +``` + +Your application Makefile can also extend `DOCKER_ENV_VARS`. + +### Directly Define Environment Variables: DOCKER_ENVIRONMENT_CMDLINE + +`DOCKER_ENVIRONMENT_CMDLINE` can be used to add variables directly to the environment +but will need to be prefixed with `-e` (see [option-summary]). + +e.g.: + +``` +DOCKER_ENVIRONMENT_CMDLINE='-e BEER_TYPE="imperial stout"' BUILD_IN_DOCKER=1 make -C examples/hello-world/ +docker run --rm -t -u "$(id -u)" \ + ... + -e 'BEER_TYPE=imperial stout' \ + -w '/data/riotbuild/riotbase/examples/hello-world/' \ + 'riot/riotbuild:latest' make +``` + +## Command Line Variables: DOCKER_OVERRIDE_CMDLINE + +Command line arguments are variables that are passed after `make` e.g. +`make target FOO=bar`, but different to environment variables a variable defined +through the command line will take precedence over all assignments of `FOO` within +the makefile (same effect as adding `-e` for environment variables, see +[option-summary] for more details. + +To pass variables overriding the command-line to docker `DOCKER_OVERRIDE_CMDLINE` +may be used: + +```shell +DOCKER_OVERRIDE_CMDLINE="BEER_TYPE='imperial stout'" BUILD_IN_DOCKER=1 make -C examples/hello-world/ RIOT_CI_BUILD=1 +Launching build container using image "riot/riotbuild:latest". +sudo docker run --rm -t -u "$(id -u)" \ + ... + -w '/data/riotbuild/riotbase/examples/hello-world/' \ + 'riot/riotbuild:latest' make BEER_TYPE='imperial stout' 'RIOT_CI_BUILD=1' +``` + +### Redefined or Overridden Variables: DOCKER_ENV_VARS_ALWAYS + +There is a corner case for the handling of `DOCKER_ENV_VARS`. If a variable is +redefined (`+=`, `=`, `:=`) or overridden then the origin of the variable will be changed +to `file` and there is no way of detecting in Make how it was set. + +If this happens after `docker.ink.mk` this is not an issue, but for all variables +susceptible to be defined in the application `Makefile` this is indeed the case. + +A subset of these variables, namely variables relating to dependency resolution +are therefore unconditionally passed to docker. The complete list can be found +under `DOCKER_ENV_VARS_ALWAYS`. + +#### CFLAGS + +CFLAGS are not automatically passed to docker because they might contain spaces, +'"' or other characters that will require escaping. The solution is to pass it with +`DOCKER_ENVIRONMENT_CMDLINE` and escape every character as required. + +e.g: if wanting to override STRING_WITH_SPACES + +``` +# normal build +CFLAGS=-DSTRING_WITH_SPACES='\"with space\" make +# in docker +DOCKER_ENVIRONMENT_CMDLINE='-e CFLAGS=-DSTRING_WITH_SPACES=\'\\\"with\ space\\\"\'' \ + BUILD_IN_DOCKER=1 make +``` + +Alternatively, it is often easier to define the CFLAGS in the Makefile which gets +evaluated inside the Docker image again), conditional on a less complex environment +variable that gets added to `DOCKER_ENV_VARS` in the Makefile. + +[option-summary]: https://www.gnu.org/software/make/manual/html_node/Options-Summary.html diff --git a/doc/doxygen/src/getting-started.md b/doc/doxygen/src/getting-started.md index a0914866c6..b3c70f0040 100644 --- a/doc/doxygen/src/getting-started.md +++ b/doc/doxygen/src/getting-started.md @@ -353,6 +353,8 @@ Troubleshooting {#docker-troubleshooting} On some Ubuntu versions a make with `BUILD_IN_DOCKER=1` can't resolve the host name of for example github.com. To fix this add the file `/etc/docker/daemon.json` with the address of your DNS Server. +For more details see @ref build-in-docker. + Generating compile_commands.json e.g. for code completion in IDEs ================================================================= diff --git a/doc/doxygen/src/mainpage.md b/doc/doxygen/src/mainpage.md index 543b40cae3..172a8b8edf 100644 --- a/doc/doxygen/src/mainpage.md +++ b/doc/doxygen/src/mainpage.md @@ -237,6 +237,7 @@ Further information {#further-information} - @ref porting-boards - @ref creating-modules - @ref advanced-build-system-tricks + - @ref build-in-docker