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.
If your user does not have permissions to access the Docker daemon:
to always use Docker for building, set
BUILD_IN_DOCKER=1 (and if necessary
DOCKER="sudo docker") in the environment:
Currently only build related targets are ran in the docker container, the exact list is under
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.:
docker.ink.mk the origin of a variable listed in
DOCKER_ENV_VARS is checked and if the origin is
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.:
Your application Makefile can also extend
DOCKER_ENVIRONMENT_CMDLINE can be used to add variables directly to the environment but will need to be prefixed with
-e (see option-summary).
Command line arguments are variables that are passed after
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:
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
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
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.