Update the container.rst documentation page with a new section for the TOML configuration file, its associated command line options and an intro paragraph.
Provide a sample config using the TuxMake images with an example to show how to simplify the command line syntax. Bump the requirement from Python 3.10 to 3.11 which is when tomllib was introduced. Also, Python 3.10 is about to reach its end of life. Signed-off-by: Guillaume Tucker <[email protected]> --- Documentation/dev-tools/container.rst | 98 ++++++++++++++++++++++++++- 1 file changed, 95 insertions(+), 3 deletions(-) diff --git a/Documentation/dev-tools/container.rst b/Documentation/dev-tools/container.rst index 452415b64662..5847637e0396 100644 --- a/Documentation/dev-tools/container.rst +++ b/Documentation/dev-tools/container.rst @@ -26,6 +26,11 @@ Command line syntax:: Available options: +``-c, --config-file CONFIG_FILE`` + + Path to the config file. If not specified, the default is to look for + ``.container.toml`` in the current working directory. + ``-e, --env-file ENV_FILE`` Path to an environment file to load in the container. @@ -38,6 +43,11 @@ Available options: Container image name (required). +``-p, --config-profile CONFIG_PROFILE`` + + Profile section to use in the config file. This will override any values + defined in the ``DEFAULT`` section. + ``-r, --runtime RUNTIME`` Container runtime name. Supported runtimes: ``docker``, ``podman``. @@ -53,8 +63,8 @@ Available options: User id to use inside the container. - If the ``-g`` option is not specified, the user id will also be used for - the group id. + If the ``-g`` option is not specified, the user id will also be set as the + group id. ``-v, --verbose`` @@ -86,9 +96,13 @@ container with SIGINT (Ctrl-C). To run commands interactively with a TTY, the shell directly rather than the parent ``container`` process. To exit an interactive shell, use Ctrl-D or ``exit``. +A :ref:`configuration file<config_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. + .. note:: - The only host requirement aside from a container runtime is Python 3.10 or + The only host requirement aside from a container runtime is Python 3.11 or later. .. note:: @@ -225,3 +239,81 @@ To build the HTML documentation, which requires the ``kdocs`` image built with ``make PREFIX=kernel.org/ extra`` as it's not a compiler toolchain:: scripts/container -i kernel.org/kdocs make htmldocs + +.. _config_file: + +Configuration File +================== + +By default, the tool will look for configuration a 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. + +Its 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. + +Supported options in each section are: + +``env_file`` + + Path to an environment file to load in the container, equivalent to the + ``-e`` command line option. + +``image`` + + Name of the container image to use, equivalent to the ``-i`` command line + option. + +``registry`` + + Name of the container image registry to use. This will be used as a prefix + before the image name with a ``/`` separator. + + For example, a ``docker.io`` registry and a ``myuser/myimage`` image will + result in ``docker.io/myuser/myimage`` as the full image path. + +``runtime`` + + Name of the container runtime, equivalent to the ``-r`` command line option. + +``uid`` / ``gid`` (integers) + + User and group id numbers to use inside the container, equivalents to the + ``-u`` and ``-g`` command line options respectively. + + +Here's a sample configuration with an extra ``clang`` profile:: + + [DEFAULT] + runtime = "podman" + registry = "docker.io" + image = "tuxmake/korg-gcc" + + [clang] + image = "tuxmake/korg-clang" + env_file = ".clang.env" + +It mentions a ``.clang.env`` file which simply contains this flag:: + + LLVM=1 + +Let's take a look again at this example mentioned earlier:: + + scripts/container -i docker.io/tuxmake/korg-clang -- make LLVM=1 defconfig + +Using the configuration file, it can now be simplified into this:: + + scripts/container -p clang -- make defconfig + +Then to override the default runtime, the ``-r`` option can still be used:: + + scripts/container -p clang -r docker -- make defconfig + +This also illustrates how values take precedence over each other: the registry +is loaded from the ``DEFAULT`` section, the image from the ``clang`` section +and the runtime from the command line ``-r`` option. -- 2.47.3
