Re: [docs] [PATCH v2 3/3] tools/build-docs-container: build in separate directory for each distro

["Antonin Godard" <antonin.godard@bootlin.com>]

On Thu Oct 9, 2025 at 12:24 PM CEST, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz@cherry.de>
>
> This allows to compare build output from different distros if necessary
> and make it easier to make sure we start building from a clean slate.
>
> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
>  documentation/tools/build-docs-container | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
> index 831d357fb..47320e182 100755
> --- a/documentation/tools/build-docs-container
> +++ b/documentation/tools/build-docs-container
> @@ -60,6 +60,7 @@ main ()
>    fi
>  
>    local image="$1"
> +  local orig_image=$image
>    shift
>  
>    OCI=$(which "$CONTAINERCMD")
> @@ -159,6 +160,7 @@ main ()
>      --volume="$DOCS_DIR:/docs:rw"
>      --workdir=/docs
>      --security-opt label=disable
> +    --env BUILDDIR="_build-$orig_image-$image_sha"

I think the idea is good for improving concurrency, however I think for
development it would be nice to keep _build the default. What about having
the following default behavior:

- Build in "_build-$orig_image-$image_sha"
- If "_build" does not exist _or_ is a symlink, create or replace a symlink to
  "_build-$orig_image-$image_sha" from the previous step, named "_build"

    _build -> _build-$orig_image-$image_sha"

- If "_build" exists and is a directory, leave it untouched as it may be
  originating from another "regular" build.

Then:

- `make clean` removes "_build" and "_build-$orig_image-$image_sha" (when
  "_build-$orig_image-$image_sha" exists and _build is a symlink to it)

- We could maybe also have a "cleanall" (or name alike) that removes all the
  _build* it finds, to clean everything up.

With this, additional runs with different SHAs will just stack next to this,
re-creating the symlink only when it is not a directory. This way, I know that
for any previous run of build-docs-container, I can open the "_build" symlink
to get the latest output. Of course I need to be careful when running concurrent
builds, but that is another use-case, a bit different from day-to-day
development IMO.

What do you think?

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com