sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget'/translations/zh_CN/dev-tools/containermodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/zh_TW/dev-tools/containermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/it_IT/dev-tools/containermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ja_JP/dev-tools/containermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ko_KR/dev-tools/containermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/pt_BR/dev-tools/containermodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/sp_SP/dev-tools/containermodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h%SPDX-License-Identifier: GPL-2.0-onlyh]h%SPDX-License-Identifier: GPL-2.0-only}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhA/var/lib/git/docbuild/linux/Documentation/dev-tools/container.rsthKubh)}(h#Copyright (C) 2025 Guillaume Tuckerh]h#Copyright (C) 2025 Guillaume Tucker}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubhsection)}(hhh](htitle)}(hContainerized Buildsh]hContainerized Builds}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXThe ``container`` tool can be used to run any command in the kernel source tree from within a container. Doing so facilitates reproducing builds across various platforms, for example when a test bot has reported an issue which requires a specific version of a compiler or an external test suite. While this can already be done by users who are familiar with containers, having a dedicated tool in the kernel tree lowers the barrier to entry by solving common problems once and for all (e.g. user ID management). It also makes it easier to share an exact command line leading to a particular result. The main use case is likely to be kernel builds but virtually anything can be run: KUnit, checkpatch etc. provided a suitable image is available.h](hThe }(hhhhhNhNubhliteral)}(h ``container``h]h container}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubhX tool can be used to run any command in the kernel source tree from within a container. Doing so facilitates reproducing builds across various platforms, for example when a test bot has reported an issue which requires a specific version of a compiler or an external test suite. While this can already be done by users who are familiar with containers, having a dedicated tool in the kernel tree lowers the barrier to entry by solving common problems once and for all (e.g. user ID management). It also makes it easier to share an exact command line leading to a particular result. The main use case is likely to be kernel builds but virtually anything can be run: KUnit, checkpatch etc. provided a suitable image is available.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hOptionsh]hOptions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hCommand line syntax::h]hCommand line syntax:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh literal_block)}(h-scripts/container -i IMAGE [OPTION]... CMD...h]h-scripts/container -i IMAGE [OPTION]... CMD...}hj0sbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(hAvailable options:h]hAvailable options:}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h!``-c, --config-file CONFIG_FILE``h]h)}(hjNh]h-c, --config-file CONFIG_FILE}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjLubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh block_quote)}(h}Path to the config file. If not specified, the default is to look for ``.container.toml`` in the current working directory. h]h)}(h|Path to the config file. If not specified, the default is to look for ``.container.toml`` in the current working directory.h](hGPath to the config file. If not specified, the default is to look for }(hjihhhNhNubh)}(h``.container.toml``h]h.container.toml}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjiubh" in the current working directory.}(hjihhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjeubah}(h]h ]h"]h$]h&]uh1jchhhKhjhhubh)}(h``-e, --env-file ENV_FILE``h]h)}(hjh]h-e, --env-file ENV_FILE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhK"hjhhubjd)}(h6Path to an environment file to load in the container. h]h)}(h5Path to an environment file to load in the container.h]h5Path to an environment file to load in the container.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK$hjubah}(h]h ]h"]h$]h&]uh1jchhhK$hjhhubh)}(h``-g, --gid GID``h]h)}(hjh]h -g, --gid GID}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhK&hjhhubjd)}(h&Group ID to use inside the container. h]h)}(h%Group ID to use inside the container.h]h%Group ID to use inside the container.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjubah}(h]h ]h"]h$]h&]uh1jchhhK(hjhhubh)}(h``-i, --image IMAGE``h]h)}(hjh]h-i, --image IMAGE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubjd)}(h!Container image name (required). h]h)}(h Container image name (required).h]h Container image name (required).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK,hjubah}(h]h ]h"]h$]h&]uh1jchhhK,hjhhubh)}(h'``-p, --config-profile CONFIG_PROFILE``h]h)}(hjh]h#-p, --config-profile CONFIG_PROFILE}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhK.hjhhubjd)}(hnProfile section to use in the config file. This will override any values defined in the ``DEFAULT`` section. h]h)}(hmProfile section to use in the config file. This will override any values defined in the ``DEFAULT`` section.h](hYProfile section to use in the config file. This will override any values defined in the }(hj7hhhNhNubh)}(h ``DEFAULT``h]hDEFAULT}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj7ubh section.}(hj7hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK0hj3ubah}(h]h ]h"]h$]h&]uh1jchhhK0hjhhubh)}(h``-r, --runtime RUNTIME``h]h)}(hj_h]h-r, --runtime RUNTIME}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhj]ubah}(h]h ]h"]h$]h&]uh1hhhhK3hjhhubjd)}(hContainer runtime name. Supported runtimes: ``podman``, ``docker``. If not specified, the first one found on the system will be used i.e. Podman if present, otherwise Docker. h](h)}(hDContainer runtime name. Supported runtimes: ``podman``, ``docker``.h](h-Container runtime name. Supported runtimes: }(hjxhhhNhNubh)}(h ``podman``h]hpodman}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjxubh, }(hjxhhhNhNubh)}(h ``docker``h]hdocker}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjxubh.}(hjxhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK5hjtubh)}(hjIf not specified, the first one found on the system will be used i.e. Podman if present, otherwise Docker.h]hjIf not specified, the first one found on the system will be used i.e. Podman if present, otherwise Docker.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hjtubeh}(h]h ]h"]h$]h&]uh1jchhhK5hjhhubh)}(h``-s, --shell``h]h)}(hjh]h -s, --shell}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhhhK:hjhhubjd)}(h+Run the container in an interactive shell. h]h)}(h*Run the container in an interactive shell.h]h*Run the container in an interactive shell.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjd)}(hUser ID to use inside the container. If the ``-g`` option is not specified and no group ID is defined in the configuration file, the user ID will also be set as the group ID. h](h)}(h$User ID to use inside the container.h]h$User ID to use inside the container.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjubh)}(hIf the ``-g`` option is not specified and no group ID is defined in the configuration file, the user ID will also be set as the group ID.h](hIf the }(hjhhhNhNubh)}(h``-g``h]h-g}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh| option is not specified and no group ID is defined in the configuration file, the user ID will also be set as the group ID.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKBhjubeh}(h]h ]h"]h$]h&]uh1jchhhK@hjhhubh)}(h``-v, --verbose``h]h)}(hj>h]h -v, --verbose}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj<ubah}(h]h ]h"]h$]h&]uh1hhhhKEhjhhubjd)}(hEnable verbose output. h]h)}(hEnable verbose output.h]hEnable verbose output.}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKGhjSubah}(h]h ]h"]h$]h&]uh1jchhhKGhjhhubh)}(h``-h, --help``h]h)}(hjmh]h -h, --help}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjkubah}(h]h ]h"]h$]h&]uh1hhhhKIhjhhubjd)}(h!Show the help message and exit. h]h)}(hShow the help message and exit.h]hShow the help message and exit.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKKhjubah}(h]h ]h"]h$]h&]uh1jchhhKKhjhhubeh}(h]optionsah ]h"]optionsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hUsageh]hUsage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKOubh)}(hXIt's entirely up to the user to choose which image to use and the ``CMD`` arguments are passed directly as an arbitrary command line to run in the container. The tool will take care of mounting the source tree as the current working directory and adjust the user and group ID as needed.h](hDIt’s entirely up to the user to choose which image to use and the }(hjhhhNhNubh)}(h``CMD``h]hCMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh arguments are passed directly as an arbitrary command line to run in the container. The tool will take care of mounting the source tree as the current working directory and adjust the user and group ID as needed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKQhjhhubh)}(hXThe container image which would typically include a compiler toolchain is provided by the user and selected via the ``-i`` option. The container runtime can be selected with the ``-r`` option, which can be either ``podman`` or ``docker``. If none is specified, the first one found on the system will be used while giving priority to Podman. Support for other runtimes may be added later depending on their popularity among users.h](htThe container image which would typically include a compiler toolchain is provided by the user and selected via the }(hjhhhNhNubh)}(h``-i``h]h-i}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh9 option. The container runtime can be selected with the }(hjhhhNhNubh)}(h``-r``h]h-r}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh option, which can be either }(hjhhhNhNubh)}(h ``podman``h]hpodman}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh or }(hjhhhNhNubh)}(h ``docker``h]hdocker}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh. If none is specified, the first one found on the system will be used while giving priority to Podman. Support for other runtimes may be added later depending on their popularity among users.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKVhjhhubh)}(hX`By default, commands are run non-interactively. The user can abort a running container with SIGINT (Ctrl-C). To run commands interactively with a TTY, the ``--shell`` or ``-s`` option can be used. Signals will then be received by the shell directly rather than the parent ``container`` process. To exit an interactive shell, use Ctrl-D or ``exit``.h](hBy default, commands are run non-interactively. The user can abort a running container with SIGINT (Ctrl-C). To run commands interactively with a TTY, the }(hj)hhhNhNubh)}(h ``--shell``h]h--shell}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)ubh or }(hj)hhhNhNubh)}(h``-s``h]h-s}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)ubha option can be used. Signals will then be received by the shell directly rather than the parent }(hj)hhhNhNubh)}(h ``container``h]h container}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)ubh7 process. To exit an interactive shell, use Ctrl-D or }(hj)hhhNhNubh)}(h``exit``h]hexit}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhj)ubh.}(hj)hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK]hjhhubh)}(hA :ref:`configuration file` may be used to facilitate running containers for various use cases. It also removes the burden of repeatedly providing the same options on the command line.h](hA }(hjhhhNhNubh)}(h&:ref:`configuration file`h]hinline)}(hjh]hconfiguration file}(hjhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]refdocdev-tools/container refdomainjreftyperef refexplicitrefwarn reftarget config_fileuh1hhhhKchjubh may be used to facilitate running containers for various use cases. It also removes the burden of repeatedly providing the same options on the command line.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKchjhhubhnote)}(hQThe only host requirement aside from a container runtime is Python 3.11 or later.h]h)}(hQThe only host requirement aside from a container runtime is Python 3.11 or later.h]hQThe only host requirement aside from a container runtime is Python 3.11 or later.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKihjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hXOut-of-tree builds are not fully supported yet. The ``O=`` option can however already be used with a relative path inside the source tree to keep separate build outputs. A workaround to build outside the tree is to use ``mount --bind``, see the examples section further down.h]h)}(hXOut-of-tree builds are not fully supported yet. The ``O=`` option can however already be used with a relative path inside the source tree to keep separate build outputs. A workaround to build outside the tree is to use ``mount --bind``, see the examples section further down.h](h5Out-of-tree builds are not fully supported yet. The }(hjhhhNhNubh)}(h``O=``h]hO=}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh option can however already be used with a relative path inside the source tree to keep separate build outputs. A workaround to build outside the tree is to use }(hjhhhNhNubh)}(h``mount --bind``h]h mount --bind}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh(, see the examples section further down.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKnhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]usageah ]h"]usageah$]h&]uh1hhhhhhhhKOubh)}(hhh](h)}(hEnvironment Variablesh]hEnvironment Variables}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKuubh)}(hX[Environment variables are not propagated to the container so they have to be either defined in the image itself or via the ``-e`` option using an environment file. In some cases it makes more sense to have them defined in the Containerfile used to create the image. For example, a Clang-only compiler toolchain image may have ``LLVM=1`` defined.h](h{Environment variables are not propagated to the container so they have to be either defined in the image itself or via the }(hj%hhhNhNubh)}(h``-e``h]h-e}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj%ubh option using an environment file. In some cases it makes more sense to have them defined in the Containerfile used to create the image. For example, a Clang-only compiler toolchain image may have }(hj%hhhNhNubh)}(h ``LLVM=1``h]hLLVM=1}(hj?hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj%ubh defined.}(hj%hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKwhjhhubh)}(hThe local environment file is more useful for user-specific variables added during development. It is passed as-is to the container runtime so its format may vary. Typically, it will look like the output of ``env``. For example::h](hThe local environment file is more useful for user-specific variables added during development. It is passed as-is to the container runtime so its format may vary. Typically, it will look like the output of }(hjWhhhNhNubh)}(h``env``h]henv}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjWubh. For example:}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK}hjhhubj/)}(h4INSTALL_MOD_STRIP=1 SOME_RANDOM_TEXT=One upon a timeh]h4INSTALL_MOD_STRIP=1 SOME_RANDOM_TEXT=One upon a time}hjwsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(hPlease also note that ``make`` options can still be passed on the command line, so while this can't be done since the first argument needs to be the executable::h](hPlease also note that }(hjhhhNhNubh)}(h``make``h]hmake}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh options can still be passed on the command line, so while this can’t be done since the first argument needs to be the executable:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(hKscripts/container -i docker.io/tuxmake/korg-clang LLVM=1 make # won't workh]hKscripts/container -i docker.io/tuxmake/korg-clang LLVM=1 make # won't work}hjsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(hthis will work::h]hthis will work:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(h=scripts/container -i docker.io/tuxmake/korg-clang make LLVM=1h]h=scripts/container -i docker.io/tuxmake/korg-clang make LLVM=1}hjsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubeh}(h]environment-variablesah ]h"]environment variablesah$]h&]uh1hhhhhhhhKuubh)}(hhh](h)}(hUser IDsh]hUser IDs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXThis is an area where the behaviour will vary slightly depending on the container runtime. The goal is to run commands as the user invoking the tool. With Podman, a namespace is created to map the current user ID to a different one in the container (1000 by default). With Docker, while this is also possible with recent versions it requires a special feature to be enabled in the daemon so it's not used here for simplicity. Instead, the container is run with the current user ID directly. In both cases, this will provide the same file permissions for the kernel source tree mounted as a volume. The only difference is that when using Docker without a namespace, the user ID may not be the same as the default one set in the image.h]hXThis is an area where the behaviour will vary slightly depending on the container runtime. The goal is to run commands as the user invoking the tool. With Podman, a namespace is created to map the current user ID to a different one in the container (1000 by default). With Docker, while this is also possible with recent versions it requires a special feature to be enabled in the daemon so it’s not used here for simplicity. Instead, the container is run with the current user ID directly. In both cases, this will provide the same file permissions for the kernel source tree mounted as a volume. The only difference is that when using Docker without a namespace, the user ID may not be the same as the default one set in the image.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXSay, we're using an image which sets up a default user with ID 1000 and the current user calling the ``container`` tool has ID 1234. The kernel source tree was checked out by this same user so the files belong to user 1234. With Podman, the container will be running as user ID 1000 with a mapping to ID 1234 so that the files from the mounted volume appear to belong to ID 1000 inside the container. With Docker and no namespace, the container will be running with user ID 1234 which can access the files in the volume but not in the user 1000 home directory. This shouldn't be an issue when running commands only in the kernel tree but it is worth highlighting here as it might matter for special corner cases.h](hgSay, we’re using an image which sets up a default user with ID 1000 and the current user calling the }(hjhhhNhNubh)}(h ``container``h]h container}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhX\ tool has ID 1234. The kernel source tree was checked out by this same user so the files belong to user 1234. With Podman, the container will be running as user ID 1000 with a mapping to ID 1234 so that the files from the mounted volume appear to belong to ID 1000 inside the container. With Docker and no namespace, the container will be running with user ID 1234 which can access the files in the volume but not in the user 1000 home directory. This shouldn’t be an issue when running commands only in the kernel tree but it is worth highlighting here as it might matter for special corner cases.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hGroup IDs (GID) follow the same logic as user IDs (UID). When specifying a UID via the ``--uid`` option or in the configuration file, the GID takes the same value as the UID by default. A specific GID can be set via ``--gid`` or the configuration file.h](hXGroup IDs (GID) follow the same logic as user IDs (UID). When specifying a UID via the }(hjhhhNhNubh)}(h ``--uid``h]h--uid}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhy option or in the configuration file, the GID takes the same value as the UID by default. A specific GID can be set via }(hjhhhNhNubh)}(h ``--gid``h]h--gid}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh or the configuration file.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hX0Podman's `Docker compatibility `__ mode to run ``docker`` commands on top of a Podman backend is more complex and not fully supported yet. As such, Podman will take priority if both runtimes are available on the system.h]h)}(hX0Podman's `Docker compatibility `__ mode to run ``docker`` commands on top of a Podman backend is more complex and not fully supported yet. As such, Podman will take priority if both runtimes are available on the system.h](h Podman’s }(hjLhhhNhNubh reference)}(hm`Docker compatibility `__h]hDocker compatibility}(hjVhhhNhNubah}(h]h ]h"]h$]h&]nameDocker compatibilityrefuriRhttps://podman-desktop.io/docs/migrating-from-docker/managing-docker-compatibilityuh1jThjLubh mode to run }(hjLhhhNhNubh)}(h ``docker``h]hdocker}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjLubh commands on top of a Podman backend is more complex and not fully supported yet. As such, Podman will take priority if both runtimes are available on the system.}(hjLhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjHubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]user-idsah ]h"]user idsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hExamplesh]hExamples}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hThe TuxMake project provides a variety of prebuilt container images available on `Docker Hub `__. Here's the shortest example to build a kernel using a TuxMake Clang image::h](hQThe TuxMake project provides a variety of prebuilt container images available on }(hjhhhNhNubjU)}(h1`Docker Hub `__h]h Docker Hub}(hjhhhNhNubah}(h]h ]h"]h$]h&]name Docker Hubjf https://hub.docker.com/u/tuxmakeuh1jThjubhO. Here’s the shortest example to build a kernel using a TuxMake Clang image:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(hscripts/container -i docker.io/tuxmake/korg-clang -- make LLVM=1 defconfig scripts/container -i docker.io/tuxmake/korg-clang -- make LLVM=1 -j$(nproc)h]hscripts/container -i docker.io/tuxmake/korg-clang -- make LLVM=1 defconfig scripts/container -i docker.io/tuxmake/korg-clang -- make LLVM=1 -j$(nproc)}hjsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubj)}(hX6When running a command with options within the container, it should be separated with a double dash ``--`` to not confuse them with the ``container`` tool options. Plain commands with no options don't strictly require the double dashes e.g.:: scripts/container -i docker.io/tuxmake/korg-clang make mrproperh](h)}(hWhen running a command with options within the container, it should be separated with a double dash ``--`` to not confuse them with the ``container`` tool options. Plain commands with no options don't strictly require the double dashes e.g.::h](hdWhen running a command with options within the container, it should be separated with a double dash }(hjhhhNhNubh)}(h``--``h]h--}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh to not confuse them with the }(hjhhhNhNubh)}(h ``container``h]h container}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh_ tool options. Plain commands with no options don’t strictly require the double dashes e.g.:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubj/)}(h?scripts/container -i docker.io/tuxmake/korg-clang make mrproperh]h?scripts/container -i docker.io/tuxmake/korg-clang make mrproper}hj sbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhNubh)}(hOTo run ``checkpatch.pl`` in a ``patches`` directory with a generic Perl image::h](hTo run }(hjhhhNhNubh)}(h``checkpatch.pl``h]h checkpatch.pl}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh in a }(hjhhhNhNubh)}(h ``patches``h]hpatches}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh% directory with a generic Perl image:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(hEscripts/container -i perl:slim-trixie scripts/checkpatch.pl patches/*h]hEscripts/container -i perl:slim-trixie scripts/checkpatch.pl patches/*}hjPsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(hXAs an alternative to the TuxMake images, the examples below refer to ``kernel.org`` images which are based on the `kernel.org compiler toolchains `__. These aren't (yet) officially available in any public registry but users can build their own locally instead using this `experimental repository `__ by running ``make PREFIX=kernel.org/``.h](hEAs an alternative to the TuxMake images, the examples below refer to }(hj^hhhNhNubh)}(h``kernel.org``h]h kernel.org}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ubh images which are based on the }(hj^hhhNhNubjU)}(hO`kernel.org compiler toolchains `__h]hkernel.org compiler toolchains}(hjxhhhNhNubah}(h]h ]h"]h$]h&]namekernel.org compiler toolchainsjf*https://mirrors.edge.kernel.org/pub/tools/uh1jThj^ubh}. These aren’t (yet) officially available in any public registry but users can build their own locally instead using this }(hj^hhhNhNubjU)}(hH`experimental repository `__h]hexperimental repository}(hjhhhNhNubah}(h]h ]h"]h$]h&]nameexperimental repositoryjf*https://gitlab.com/gtucker/korg-containersuh1jThj^ubh by running }(hj^hhhNhNubh)}(h``make PREFIX=kernel.org/``h]hmake PREFIX=kernel.org/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ubh.}(hj^hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h'To build just ``bzImage`` using Clang::h](hTo build just }(hjhhhNhNubh)}(h ``bzImage``h]hbzImage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh using Clang:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(h@scripts/container -i kernel.org/clang -- make bzImage -j$(nproc)h]h@scripts/container -i kernel.org/clang -- make bzImage -j$(nproc)}hjsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(h.Same with GCC 15 as a particular version tag::h]h-Same with GCC 15 as a particular version tag:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(hAscripts/container -i kernel.org/gcc:15 -- make bzImage -j$(nproc)h]hAscripts/container -i kernel.org/gcc:15 -- make bzImage -j$(nproc)}hjsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(hxFor an out-of-tree build, a trick is to bind-mount the destination directory to a relative path inside the source tree::h]hwFor an out-of-tree build, a trick is to bind-mount the destination directory to a relative path inside the source tree:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(hXmkdir -p $HOME/tmp/my-kernel-build mkdir -p build sudo mount --bind $HOME/tmp/my-kernel-build build scripts/container -i kernel.org/gcc -- make mrproper scripts/container -i kernel.org/gcc -- make O=build defconfig scripts/container -i kernel.org/gcc -- make O=build -j$(nproc)h]hXmkdir -p $HOME/tmp/my-kernel-build mkdir -p build sudo mount --bind $HOME/tmp/my-kernel-build build scripts/container -i kernel.org/gcc -- make mrproper scripts/container -i kernel.org/gcc -- make O=build defconfig scripts/container -i kernel.org/gcc -- make O=build -j$(nproc)}hjsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(h>To run KUnit in an interactive shell and get the full output::h]h=To run KUnit in an interactive shell and get the full output:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(hscripts/container -s -i kernel.org/gcc:kunit -- \ tools/testing/kunit/kunit.py \ run \ --arch=x86_64 \ --cross_compile=x86_64-linux-h]hscripts/container -s -i kernel.org/gcc:kunit -- \ tools/testing/kunit/kunit.py \ run \ --arch=x86_64 \ --cross_compile=x86_64-linux-}hj.sbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(h$To just start an interactive shell::h]h#To just start an interactive shell:}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(h)scripts/container -si kernel.org/gcc bashh]h)scripts/container -si kernel.org/gcc bash}hjJsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubh)}(hTo build the HTML documentation, which requires the ``kdocs`` image built with ``make PREFIX=kernel.org/ extra`` as it's not a compiler toolchain::h](h4To build the HTML documentation, which requires the }(hjXhhhNhNubh)}(h ``kdocs``h]hkdocs}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjXubh image built with }(hjXhhhNhNubh)}(h!``make PREFIX=kernel.org/ extra``h]hmake PREFIX=kernel.org/ extra}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjXubh$ as it’s not a compiler toolchain:}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj/)}(h3scripts/container -i kernel.org/kdocs make htmldocsh]h3scripts/container -i kernel.org/kdocs make htmldocs}hjsbah}(h]h ]h"]h$]h&]hhuh1j.hhhKhjhhubhtarget)}(h.. _config_file:h]h}(h]h ]h"]h$]h&]refid config-fileuh1jhKhjhhhhubeh}(h]examplesah ]h"]examplesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hConfiguration Fileh]hConfiguration File}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXBBy default, the tool will look for a configuration file named ``.container.toml`` in the current working directory. If not found, it will be silently ignored as it's not required. Alternatively, any other path can be specified with the ``-c`` option in which case the file needs to be present or an error will be raised.h](h>By default, the tool will look for a configuration file named }(hjhhhNhNubh)}(h``.container.toml``h]h.container.toml}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh in the current working directory. If not found, it will be silently ignored as it’s not required. Alternatively, any other path can be specified with the }(hjhhhNhNubh)}(h``-c``h]h-c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubhN option in which case the file needs to be present or an error will be raised.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXlIts data follows the standard TOML format and is made up of different sections with ``DEFAULT`` as the default one. Other sections may be used to define alternative profiles under arbitrary names which can be selected by the ``-p`` option. Command line options take precedence over configuration values, and profile sections take precedence over the default one.h](hTIts data follows the standard TOML format and is made up of different sections with }(hjhhhNhNubh)}(h ``DEFAULT``h]hDEFAULT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh as the default one. Other sections may be used to define alternative profiles under arbitrary names which can be selected by the }(hjhhhNhNubh)}(h``-p``h]h-p}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh option. Command line options take precedence over configuration values, and profile sections take precedence over the default one.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(h&Supported options in each section are:h]h&Supported options in each section are:}(hj# hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubh)}(h ``env_file``h]h)}(hj3 h]henv_file}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj1 ubah}(h]h ]h"]h$]h&]uh1hhhhM hjhhubjd)}(hdPath to an environment file to load in the container, equivalent to the ``-e`` command line option. h]h)}(hcPath to an environment file to load in the container, equivalent to the ``-e`` command line option.h](hHPath to an environment file to load in the container, equivalent to the }(hjL hhhNhNubh)}(h``-e``h]h-e}(hjT hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjL ubh command line option.}(hjL hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hjH ubah}(h]h ]h"]h$]h&]uh1jchhhM hjhhubh)}(h ``image``h]h)}(hjt h]himage}(hjv hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjr ubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubjd)}(hRName of the container image to use, equivalent to the ``-i`` command line option. h]h)}(hQName of the container image to use, equivalent to the ``-i`` command line option.h](h6Name of the container image to use, equivalent to the }(hj hhhNhNubh)}(h``-i``h]h-i}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh command line option.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jchhhMhjhhubh)}(h ``runtime``h]h)}(hj h]hruntime}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubjd)}(hMName of the container runtime, equivalent to the ``-r`` command line option. h]h)}(hLName of the container runtime, equivalent to the ``-r`` command line option.h](h1Name of the container runtime, equivalent to the }(hj hhhNhNubh)}(h``-r``h]h-r}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh command line option.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1jchhhMhjhhubh)}(h``uid`` / ``gid`` (integers)h](h)}(h``uid``h]huid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh / }(hj hhhNhNubh)}(h``gid``h]hgid}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh (integers)}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubjd)}(hUser and group ID numbers to use inside the container, equivalents to the ``-u`` and ``-g`` command line options respectively. h]h)}(h~User and group ID numbers to use inside the container, equivalents to the ``-u`` and ``-g`` command line options respectively.h](hJUser and group ID numbers to use inside the container, equivalents to the }(hj& hhhNhNubh)}(h``-u``h]h-u}(hj. hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj& ubh and }(hj& hhhNhNubh)}(h``-g``h]h-g}(hj@ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj& ubh# command line options respectively.}(hj& hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj" ubah}(h]h ]h"]h$]h&]uh1jchhhMhjhhubh)}(h?Here's a sample configuration with an extra ``clang`` profile::h](h.Here’s a sample configuration with an extra }(hj^ hhhNhNubh)}(h ``clang``h]hclang}(hjf hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj^ ubh profile:}(hj^ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj/)}(hu[DEFAULT] runtime = "podman" image = "tuxmake/korg-gcc" [clang] image = "tuxmake/korg-clang" env_file = ".clang.env"h]hu[DEFAULT] runtime = "podman" image = "tuxmake/korg-gcc" [clang] image = "tuxmake/korg-clang" env_file = ".clang.env"}hj~ sbah}(h]h ]h"]h$]h&]hhuh1j.hhhM!hjhhubh)}(hCIt mentions a ``.clang.env`` file which simply contains this flag::h](hIt mentions a }(hj hhhNhNubh)}(h``.clang.env``h]h .clang.env}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj ubh& file which simply contains this flag:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM)hjhhubj/)}(hLLVM=1h]hLLVM=1}hj sbah}(h]h ]h"]h$]h&]hhuh1j.hhhM+hjhhubh)}(h;Let's take a look again at this example mentioned earlier::h]h