Nerves

v1.3.2

Nerves

Nerves v1.3.2 Nerves.Artifact.BuildRunners.Docker View Source

Produce an artifact for a package using Docker.

The Nerves Docker artifact build_runner will use docker to create the artifact for the package. The output in Mix will be limited to the headlines from the process and the full build log can be found in the file build.log located root of the package path.

Images

Docker containers will be created based off the image that is loaded. By default, containers will use the default image nervesproject/nerves_system_br:latest. Sometimes additional host tools are required to build a package. Therefore, packages can provide their own images by specifying it in the package config under :build_runner_config. the file is specified as a tuple {"path/to/Dockerfile", tag_name}.

Example:

build_runner_config: [

docker: {"Dockerfile", "my_system:0.1.0"}

]

Volumes and Cache

Nerves will mount several volumes to the container for use in building the artifact.

Mounted from the host:

  • /nerves/env/<package.name> - The package being built.
  • /nerves/env/platform - The package platform package.
  • /nerves/host/artifacts - The host artifact directory.

Nerves will also mount the host NERVES_DL_DIR to save downloaded assets the build platform requires for producing the artifact. This is mounted at /nerves/dl. This volume can significantly reduce build times but has potential for corruption. If you suspect that your build is failing due to a faulty downloaded cached data, you can manually mount the offending container and remove the file from this location or delete the entire directory.

Nerves uses a docker volume to attach the build files. The volume name is defined as the package name and a unique id that is stored at ARTIFACT_DIR/.docker_id. The build directory is mounted to the container at /nerves/build and is configured as the current working directory.

Cleanup

Periodically, you may want to destroy all unused volumes to clean up. Please refer to the Docker documentation for more information on how to do this.

When the build_runner is finished, the artifact is decompressed on the host at the packages defined artifact directory.

Link to this section Summary

Functions

archive(pkg, toolchain, opts)

Callback implementation for Nerves.Artifact.BuildRunner.archive/3

build(pkg, toolchain, opts)

Create an artifact for the package

clean(pkg)

Callback implementation for Nerves.Artifact.BuildRunner.clean/1

parse_docker_version(vsn)
system_shell(pkg)

Connect to a system configuration shell in a Docker container

Link to this section Functions

Link to this function archive(pkg, toolchain, opts) View Source 
archive(Nerves.Package.t(), Nerves.Package.t(), term()) :: :ok

Callback implementation for Nerves.Artifact.BuildRunner.archive/3.

Link to this function build(pkg, toolchain, opts) View Source 
build(Nerves.Package.t(), Nerves.Package.t(), term()) :: :ok

Create an artifact for the package

Opts: make_args: - Extra arguments to be passed to make.

For example:

You can configure the number of parallel jobs that buildroot can use for execution. This is useful for situations where you may have a machine with a lot of CPUs but not enough ram.

# mix.exs
defp nerves_package do
  [
    # ...
    build_runner_opts: [make_args: ["PARALLEL_JOBS=8"]],
  ]
end
Link to this function parse_docker_version(vsn) View Source
Link to this function system_shell(pkg) View Source 
system_shell(Nerves.Package.t()) :: :ok

Connect to a system configuration shell in a Docker container