poky/documentation/tools/build-docs-container

#!/usr/bin/env bash

-*- vim: set expandtab tabstop=2 shiftwidth=2:

Build a container ready to build the documentation be reading the dependencies

listed in shell scripts in documentation/tools/host_packages_scripts, and

start a documentation build in this container.

Usage:

./documentation/tools/build-docs-container []

e.g.:

./documentation/tools/build-docs-container ubuntu:24.04 html

Will build the docs in an Ubuntu 24.04 container in html.

The container engine can be selected by exporting CONTAINERCMD in the

environment. The default is docker, but podman can also be used.

set -eu -o pipefail

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() { echo "$0 -- script to build documentation from within a container

$0 OCI_IMAGE [make arguments...]

OCI_IMAGE is an image:tag of an OCI image hosted on hub.docker.com. It is one of: - debian:12 - debian:13 - fedora:39 - fedora:40 - fedora:41 - fedora:42 - leap:15.5 - leap:15.6 - ubuntu:22.04 - ubuntu:24.04 - ubuntu:25.04

[make arguments] is one or more argument to pass to the make command of 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). " }

main () { if [ "$#" -lt 1 ]; then usage exit 1 fi

local image="$1" shift

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}')

case $image in # Missing latexmk texlive-gnu-freefont packages at the very least # "almalinux:8"|
# "almalinux:9") # containerfile=Containerfile.almalinux # docs=almalinux_docs.sh # docs_pdf=almalinux_docs_pdf.sh # pip3=pip3_docs.sh # ;; # Missing python3-saneyaml # "debian:11"|
"debian:12"|
"debian:13") containerfile=Containerfile.debian essential=ubuntu_essential.sh docs=ubuntu_docs.sh docs_pdf=ubuntu_docs_pdf.sh ;; "fedora:39"|
"fedora:40"|
"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 ;; "leap:15.5"|
"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 ;; "ubuntu:22.04"|
"ubuntu:24.04"|
"ubuntu:25.04") containerfile=Containerfile.ubuntu essential=ubuntu_essential.sh docs=ubuntu_docs.sh docs_pdf=ubuntu_docs_pdf.sh ;; *) echo "$image not supported!" usage exit 1 ;; esac

$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:-}"
--file "$SCRIPT_DIR/$containerfile"
"$SH_DIR/"

local -a args_run=( --rm --interactive --tty --volume="$DOCS_DIR:/docs:rw" --workdir=/docs --security-opt label=disable )

if [ "$OCI" = "docker" ]; then args_run+=( --user="$(id -u)":"$(id -g)" ) elif [ "$OCI" = "podman" ]; then # we need net access to fetch bitbake terms args_run+=( --cap-add=NET_RAW --userns=keep-id ) fi

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

main "$@"