tools/build-docs-container: add option to install essential packages

The script currently only installs the files necessary to build the
docs. Since we also have the essential packages listed it can be useful
to include them in the containers, at least to validate that these
successfully install.

Add an env variable for including these packages in the container. The
default is to not include these, so the current behavior is unchanged.

(From yocto-docs rev: 723e531ea442df96fd592635a2fbfba73e737886)

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/tools/Containerfile.apt

@@ -1,6 +1,8 @@
 ARG ARG_FROM=debian:12 # default value to avoid warning
 FROM $ARG_FROM
 
+ARG INCLUDE_ESSENTIAL_PACKAGES=0
+ARG ESSENTIAL=ubuntu_essential.sh
 ARG DOCS=ubuntu_docs.sh
 ARG DOCS_PDF=ubuntu_docs_pdf.sh
 
@@ -8,12 +10,14 @@ ENV DEBIAN_FRONTEND=noninteractive
 ARG TZ=Europe/Vienna
 
 # relative to the location of the dockerfile
+COPY --chmod=777 ${ESSENTIAL} /temp/host_packages_essential.sh
 COPY --chmod=777 ${DOCS} /temp/host_packages_docs.sh
 COPY --chmod=777 ${DOCS_PDF} /temp/host_packages_docs_pdf.sh
 
 RUN ln -fs "/usr/share/zoneinfo/$TZ" /etc/localtime \
  && apt-get update \
  && apt-get install -y sudo \
+ && if [ "$INCLUDE_ESSENTIAL_PACKAGES" = "1" ]; then yes | /temp/host_packages_essential.sh; fi \
  && yes | /temp/host_packages_docs.sh \
  && yes | /temp/host_packages_docs_pdf.sh \
  && apt-get --yes autoremove \

documentation/tools/Containerfile.dnf

@@ -1,17 +1,21 @@
 ARG ARG_FROM=fedora:40 # default value to avoid warning
 FROM $ARG_FROM
 
+ARG INCLUDE_ESSENTIAL_PACKAGES=0
+ARG ESSENTIAL=fedora_essential.sh
 ARG DOCS=fedora_docs.sh
 ARG DOCS_PDF=fedora_docs_pdf.sh
 ARG PIP3=pip3_docs.sh
 
 # relative to the location of the dockerfile
+COPY --chmod=777 ${ESSENTIAL} /temp/host_packages_essential.sh
 COPY --chmod=777 ${DOCS} /temp/host_packages_docs.sh
 COPY --chmod=777 ${DOCS_PDF} /temp/host_packages_docs_pdf.sh
 COPY --chmod=777 ${PIP3} /temp/pip3_docs.sh
 
 RUN dnf update -y \
  && dnf install -y sudo \
+ && if [ "$INCLUDE_ESSENTIAL_PACKAGES" = "1" ]; then yes | /temp/host_packages_essential.sh; fi \
  && yes | /temp/host_packages_docs.sh \
  && yes | /temp/host_packages_docs_pdf.sh \
  && yes | /temp/pip3_docs.sh \

documentation/tools/Containerfile.zypper

@@ -1,11 +1,14 @@
 ARG ARG_FROM=opensuse/leap:15.4 # default value to avoid warning
 FROM $ARG_FROM
 
+ARG INCLUDE_ESSENTIAL_PACKAGES=0
+ARG ESSENTIAL=opensuse_essential.sh
 ARG DOCS=opensuse_docs.sh
 ARG DOCS_PDF=opensuse_docs_pdf.sh
 ARG PIP3=pip3_docs.sh
 
 # relative to the location of the dockerfile
+COPY --chmod=777 ${ESSENTIAL} /temp/host_packages_essential.sh
 COPY --chmod=777 ${DOCS} /temp/host_packages_docs.sh
 COPY --chmod=777 ${DOCS_PDF} /temp/host_packages_docs_pdf.sh
 COPY --chmod=777 ${PIP3} /temp/pip3_docs.sh
@@ -20,6 +23,7 @@ RUN for script in /temp/*.sh; do \
 
 RUN zypper update -y \
  && zypper install -y sudo \
+ && if [ "$INCLUDE_ESSENTIAL_PACKAGES" = "1" ]; then yes | /temp/host_packages_essential.sh; fi \
  && yes | /temp/host_packages_docs.sh \
  && yes | /temp/host_packages_docs_pdf.sh \
  && yes | /temp/pip3_docs.sh \

documentation/tools/build-docs-container

@@ -24,6 +24,7 @@ SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
 CONTAINERCMD=${CONTAINERCMD:-docker}
 DOCS_DIR="$SCRIPT_DIR/../.."
 SH_DIR="$SCRIPT_DIR/host_packages_scripts"
+INCLUDE_ESSENTIAL_PACKAGES=${INCLUDE_ESSENTIAL_PACKAGES:-0}
 
 function usage()
 {
@@ -49,6 +50,16 @@ $0 OCI_IMAGE [make arguments...]
    documentation/Makefile, see that file for what's supported. This is typically
    intended to be used to provide specific make targets.
    Default: publish
+
+   Environment variables:
+
+   - CONTAINERCMD can be set to 'docker' or 'podman' to select the
+     container engine (default: 'docker').
+
+   - INCLUDE_ESSENTIAL_PACKAGES can be set to 0 or 1 to also include essential
+     packages listed in documentation/tools/host_packages_scripts/*_essential.sh.
+     This is not required to build the documentation but can be useful to validate
+     the installation of packages listed in these files (default: 0).
 "
 }
 
@@ -85,6 +96,7 @@ main ()
     "debian:12"*|\
     "debian:13"*)
       containerfile=Containerfile.debian
+      essential=ubuntu_essential.sh
       docs=ubuntu_docs.sh
       docs_pdf=ubuntu_docs_pdf.sh
       ;;
@@ -93,6 +105,7 @@ main ()
     "fedora:41"*|\
     "fedora:42"*)
       containerfile=Containerfile.fedora
+      essential=fedora_essential.sh
       docs=fedora_docs.sh
       docs_pdf=fedora_docs_pdf.sh
       pip3=pip3_docs.sh
@@ -119,6 +132,7 @@ main ()
     # "leap:15.6"*)
       image=opensuse/leap:$version
       containerfile=Containerfile.zypper
+      essential=opensuse_essential.sh
       docs=opensuse_docs.sh
       docs_pdf=opensuse_docs_pdf.sh
       pip3=pip3_docs.sh
@@ -129,6 +143,7 @@ main ()
     "ubuntu:24.04"*|\
     "ubuntu:25.04"*)
       containerfile=Containerfile.ubuntu
+      essential=ubuntu_essential.sh
       docs=ubuntu_docs.sh
       docs_pdf=ubuntu_docs_pdf.sh
       ;;
@@ -142,6 +157,8 @@ main ()
   $OCI build \
     --tag "yocto-docs-$sanitized_dockername:latest" \
     --build-arg ARG_FROM="docker.io/$image" \
+    --build-arg INCLUDE_ESSENTIAL_PACKAGES="${INCLUDE_ESSENTIAL_PACKAGES}" \
+    --build-arg ESSENTIAL="$essential" \
     --build-arg DOCS="$docs" \
     --build-arg DOCS_PDF="$docs_pdf" \
     --build-arg PIP3="${pip3:-}" \