Skip to content

Command line reference

Usage

tuxmake [OPTIONS] [VAR=VALUE...] [target ...]

Positional arguments

[@config | KEY=VALUE | target] ...

Configuration files to load, Make variables to use and targets to build. If no targets are specified, tuxmake will build config + kernel + xipkernel + modules + dtbs + dtbs-legacy + debugkernel + headers. Supported targets: kselftest, default, debugkernel, kernel, targz-pkg, modules, kselftest-merge, config, dtbs-legacy, xipkernel, dtbs, kselftest-bpf, cpupower, headers, perf.

Build input options

-C TREE, --directory TREE

Tree to build (default: .).

Output options

-o OUTPUT_DIR, --output-dir OUTPUT_DIR

Output directory for artifacts.

-b BUILD_DIR, --build-dir BUILD_DIR

Build directory. For incremental builds, specify the same directory on subsequential builds (default: temporary, clean directory).

Build output options

-a TARGET_ARCH, --target-arch TARGET_ARCH

Architecture to build the kernel for. Default: host architecture. Supported: sh, um, riscv, mips, sparc, x86_64, arm, openrisc, hexagon, powerpc, arc, s390, parisc, arm64, i386.

-k KCONFIG, --kconfig KCONFIG

kconfig to use. Named (defconfig etc), path to a local config file, or URL to config file (default: defconfig).

-K KCONFIG_ADD, --kconfig-add KCONFIG_ADD

Extra kconfig fragments, merged on top of the main kconfig from --kconfig. In tree configuration fragment (e.g. kvm_guest.config), path to local file, URL, CONFIG_*=[y|m|n], or # CONFIG_* is not set. Can be specified multiple times, and will be merged in the order given.

-I KERNEL_IMAGE, --kernel-image KERNEL_IMAGE

Kernel image to build, overriding the default image name for the target architecture.

Build environment options

-t TOOLCHAIN, --toolchain TOOLCHAIN

Toolchain to use in the build. Default: none (use whatever Linux uses by default). Supported: rustllvm, rustgcc, llvm, clang, rustclang, gcc; request specific versions by appending "-N" (e.g. gcc-10, clang-9).

-w WRAPPER, --wrapper WRAPPER

Compiler wrapper to use in the build. Default: none. Supported: sccache, ccache, none. When used with containers, either the wrapper binary must be available in the container image, OR you can pass --wrapper=/path/to/WRAPPER and WRAPPER will be bind mounted in /usr/local/bin inside the container (for this to work WRAPPER needs to be a static binary, or have its shared library dependencies available inside the container).

-e ENVIRONMENT, --environment ENVIRONMENT

Set environment variables for the build. Format: KEY=VALUE .

-j JOBS, --jobs JOBS

Number of concurrent jobs to run when building (default: 1).

-r RUNTIME, --runtime RUNTIME

Runtime to use for the builds. By default, builds are run natively on the build host. Supported: podman-local, podman, docker-local, null, docker.

--image-registry IMAGE_REGISTRY

Explicit image registry to use for container-based runtimes. Implies --runtime=docker if no runtime is explicit specified. (default: none, meaning to just use docker.io).

-i IMAGE, --image IMAGE

Image to build with, for container-based runtimes (docker, podman etc). {toolchain} and {arch} get replaced by the names of the toolchain and architecture selected for the build. Implies --runtime=docker if no runtime is explicit specified. (default: tuxmake-provided images).

--docker-image DOCKER_IMAGE

Alias for --image (deprecated).

-F, --fail-fast

Stop the build at the first failure (default: continue building even in the presence of failures, to find the maximum number of build errors)

-v, --verbose

Do a verbose build (default: silent build).

-q, --quiet

Quiet build: only errors messages, if any (default: no).

Informational options

-h, --help

Show program help.

-V, --version

show program's version number and exit

-A, --list-architectures

List supported architectures and exit.

-T, --list-toolchains

List supported toolchains and exit. Combine with --runtime to list toolchains supported by that particular runtime.

-R, --list-runtimes

List supported runtimes and exit.

-p, --print-support-matrix

Print support matrix (architectures x toolchains). Combine with --runtime to list support matrix for that particular runtime.

--check-environment

Instead of running the build, just check if the build environment has the necessary tools for it. The check is run on the exact environment (e.g. container image) that the rest of the options would select cause to be selected.

-c {always,never,auto}, --color {always,never,auto}

Control use of colored output. always and never do what you expect; auto (the default) outputs colors when stdout is a tty.

Hooks

--pre-build-hook COMMAND

Execute COMMAND before the build, if the build is valid and will be executed. Can be specified multiple times. The command is executed with the Linux source tree as working directory. If any pre build hook fails, the build it NOT executed, and tuxmake exits with a non-zero exit code.

--post-build-hook COMMAND

Execute COMMAND after the build is finished, if the build is successful. Can be specified multiple times. The command is executed with the Linux source tree as working directory. If any post build hook fails, tuxmake exits with a non-zero exit code.

--results-hook COMMAND

Execute COMMAND after the build is finished, if the build is successful, and after any post build hooks given by --post-build-hook, if none of them failed. Can be specified multiple times. The command is executed with the build output directory (i.e. where all the artifacts are) as working directory. If any results hook fails, tuxmake exits with a non-zero exit code.

Debugging options

-d, --debug

Provides extra output on stderr for debugging tuxmake itself. This output will not appear in the build log.

-s, --shell

Opens a shell in the runtime after the build, regardless of its result, for debugging.

Configuration files

Configuration files can be passed as positional arguments that start with @. Absolute filenames are read as is, and relative ones are assumed to be relative to ${XDG_CONFIG_HOME}/tuxmake (where ${XDG_CONFIG_HOME} defaults to ${HOME}/.config).

The configuration files must contain command line options, for example::

$ cat ~/.config/tuxmake/default
--wrapper=ccache
--runtime=podman

Whitespace is ignored in general, so your option can be one per line, or all in one line. Any option values containing spaces and other shell metacharacters must be properly quoted and escaped, as if you were writing them in shell script::

--environment=KBUILD_BUILD_TIMESTAMP='Tue May 26 16:16:14 2020 -0500'

Lines starting with an # are comments and are ignored. No inline comments are supported, only full lines.

When a configuration file reference is found in the command line, the file will be read, and the command line options in it will be inserted in the command line in the same position as the configuration file reference. So, any options given before the configuration file reference can potentially be overridden by the ones in the configuration file, and any options after the configuration file reference can override the ones set in it.

If ${XDG_CONFIG_HOME}/tuxmake/default exists, it is always loaded as if it was the first argument in the command line.

Note: configuration files are only supported in the tuxmake command line. The Python API always requires any options to be specified explicitly.

Environment variables

  • TUXMAKE: defines default options for tuxmake. Those options can be overridden in the command line.
  • TUXMAKE_DOCKER_RUN: defines extra options for docker run calls made by the docker runtime.
  • TUXMAKE_PODMAN_RUN: defines extra options for podman run calls made by the podman runtime.
  • TUXMAKE_IMAGE: defines the image to use with the selected container runtime (docker, podman etc). The same substitutions described in --image apply.
  • TUXMAKE_IMAGE_REGISTRY: defines an container image registry to get any container image from. This string, and a slash character ("/"), gets prepended to the image name, regardless of it being provided via $TUXMAKE_IMAGE, --image, or determined automatically by tuxmake.
  • TUXMAKE_IMAGE_TAG: defines an container image tag to use. If used, a colon character (":") and this string gets appended to the image name that was informed with $TUXMAKE_IMAGE, --image, or determined automatically by tuxmake.

Files

  • ${XDG_CONFIG_HOME}/tuxmake/default (~/.config/tuxmake/default): default configuration file.