[PATCH 1/8] tools/build-docs-container: guarantee the image to run matches the just-built image

Antonin Godard
2025-12-22T12:28:21Z

From: Quentin Schulz <quentin.schulz@cherry.de>

We aren't that interested in tags actually, the only thing it brings is
a belief that we are going to run exactly what we just built. The issue
is that this is incorrect.

Indeed, one could simply run the script in parallel for the same image.
Script runtime A will build the image A and tag it X, Script runtime B
will build the image B and tag it X, Script runtime B will run the tag X
(image B), Script runtime A will run the tag X (image B). Note that this
problem exists whether we are building from the same tree concurrently
or from different yocto-docs trees concurrently.
One way to fix this could be to introduce random numbers in the tag so
that it's always unique, but we would be flooding the system with
useless tags.

Instead, we can use the sha of the generated image and run that sha
directly. If it's the same across rebuilds, it'll stay the same. If it's
different, the sha will be different and thus we are safe from
concurrent use.

The only downside is that we cannot infer from the image sha the
underlying distro we're testing.

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
documentation/tools/build-docs-container | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container
index 23c3dfe33..2f31295ed 100755
--- a/documentation/tools/build-docs-container
+++ b/documentation/tools/build-docs-container
@@ -80,10 +80,6 @@ main ()

OCI=$(which "$CONTAINERCMD")

- # docker build doesn't accept 2 colons, so "sanitize" the name
- local sanitized_dockername
- sanitized_dockername=$(echo "$image" | tr ':.' '-')
-
local version
version=$(echo "$image" | awk -F: '{print $NF}')

@@ -159,8 +155,13 @@ main ()
;;
esac

+ local image_sha
+ image_id_file=$(mktemp)
+ # Don't clutter tmpfs on fails
+ trap 'rm -f "$image_id_file"' EXIT
+
$OCI build \
- --tag "yocto-docs-$sanitized_dockername:latest" \
+ --iidfile "$image_id_file" \
--build-arg ARG_FROM="$repo/$image" \
--build-arg INCLUDE_ESSENTIAL_PACKAGES="${INCLUDE_ESSENTIAL_PACKAGES}" \
--build-arg ESSENTIAL="host_packages_scripts/$essential" \
@@ -170,6 +171,9 @@ main ()
--file "$SCRIPT_DIR/containerfiles/$containerfile" \
"$SCRIPT_DIR"

+ image_sha="$(< "$image_id_file")"
+ rm "$image_id_file"
+
local -a args_run=(
--rm
--interactive
@@ -193,7 +197,7 @@ main ()

$OCI run \
"${args_run[@]}" \
- "yocto-docs-$sanitized_dockername" \
+ "$image_sha" \
"$@"
}

--
2.51.0