Re: [PATCH 2/2] Documentation: dev-tools: cover registry option in container.rst

[Guillaume Tucker]

On 11/10/2026 10:54 pm, Guillaume Tucker wrote:
> Add the corresponding documentation entry for the new --registry
> command line option and TOML configuration file.  Update the examples
> accordingly to show how this can be used to override a registry name
> already defined within a default image name.

Sashiko wrote:

> Does the patch contain these examples?
>
> The commit message mentions showing how to override a registry name
> already defined within a default image name, but the examples added
> in the patch only show overriding the registry setting in the
> configuration file, not an embedded registry within an image
> string.

By 'default' I meant an image name that would be used without
specifying it on the command line with the -i option.  That's not the
same as the [DEFAULT] section in the TOML file.  But it's true it
could be clarified by mentioning an image name from a profile section
instead, so I'll reword this in the v2.

> Signed-off-by: Guillaume Tucker <gtucker@xxxxxxxxxx>
> ---
>   Documentation/dev-tools/container.rst | 33 +++++++++++++++++++++++----
>   1 file changed, 29 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/dev-tools/container.rst b/Documentation/dev-tools/container.rst
> index 5dde95f6b222..3f2ba1fcf3bf 100644
> --- a/Documentation/dev-tools/container.rst
> +++ b/Documentation/dev-tools/container.rst
> @@ -48,6 +48,13 @@ Available options:
>       Profile section to use in the config file.  This will override any values
>       defined in the ``DEFAULT`` section.
>   
> +``-R, --registry REGISTRY``
> +
> +    Container registry name.
> +
> +    Any registry already included in the image name will be replaced or removed
> +    when using this option with no value.
> +
>   ``-r, --runtime RUNTIME``
>   
>       Container runtime name.  Supported runtimes: ``podman``, ``docker``.
> @@ -274,6 +281,15 @@ Supported options in each section are:
>       Name of the container image to use, equivalent to the ``-i`` command line
>       option.
>   
> +``registry``
> +
> +    Name of the container image registry to use, equivalent to the ``-R``
> +    command line option.  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.
> @@ -288,6 +304,7 @@ Here's a sample configuration with an extra ``clang`` profile::
>   
>     [DEFAULT]
>     runtime = "podman"
> +  registry = "docker.io"
>     image = "tuxmake/korg-gcc"
>   
>     [clang]
> @@ -306,10 +323,18 @@ Using the configuration file, it can now be simplified into this::
>   
>     scripts/container -p clang -- make defconfig
>   
> -Then to override the default user, the ``-u`` option can still be used::
> +Then to override the default runtime, the ``-r`` option can still be used::
> +
> +  scripts/container -p clang -r docker -- make defconfig
> +
> +Likewise, to override the registry name::
> +
> +  scripts/container -p clang -R my.registry.com -- make defconfig
> +
> +Or to not use any registry at all but only a local image::
>   
> -  scripts/container -p clang -u0 -- make defconfig
> +  scripts/container -p clang -R -- make defconfig
>   
> -This also illustrates how values take precedence over each other: the runtime
> +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 user ID from the command line ``-u`` option.
> +and the runtime from the command line ``-r`` option.

Sashiko wrote:

> Does this explanation still match the example directly above it?
>
> The text explains that the registry is loaded from the DEFAULT
> section and the runtime from the command line -r option. However,
> the immediately preceding example is "scripts/container -p clang -R
> -- make defconfig", where the registry is explicitly cleared and
> there is no -r option used.

I see the issue, registry and runtime were swapped in the sentence.
This would be correct:

    This also illustrates how values take precedence over each other:
    the runtime is loaded from the ``DEFAULT`` section, the image
    from the ``clang`` section and the registry removed via the
    command line ``-R`` option.

I'll fix this in the v2 as well.


There were a couple of other comments already addressed in the first
patch about using hostnames rather than domain names, so nothing
further to add here about them.

And if anyone is wondering why it's useful to be able to override the
registry, a typical use case is when making modified images locally
before pushing them to a registry or when pulling images from a
development registry instead.  Say, in the TOML file a user can set
some standard images to be pulled from a public registry.  Then when
building a variant of an image, the user can just use the -R option
to pick it up instead of editing the file or duplicating profile
entries.  Validating the image names seems useful and it's a small
extra to be able to override the registry part once it's all parsed
into objects.  So it seems worth the extra few lines of code.

Guillaume