blob: a07e681fe8e437ce82d06a699d6337d3b0a1fdb1 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
#!/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 <image> [<make target>]
#
# 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/../.."
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:
- almalinux:8
- almalinux:9
- centos:stream9
- centos:stream10
- debian:11
- debian:12
- debian:13
- fedora:43
- leap:15.6
- leap:16.0
- rockylinux:8
- rockylinux:9
- ubuntu:22.04
- ubuntu:24.04
- ubuntu:25.04
- ubuntu:25.10
- ubuntu:26.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}')
# Default to docker.io unless overwritten below
local repo=docker.io
case $image in
"almalinux:8"*|\
"almalinux:9"*)
containerfile=Containerfile.almalinux
essential=almalinux_essential.sh
docs=almalinux_docs.sh
docs_pdf=tlmgr_docs_pdf.sh
pip3=pip3_docs.sh
;;
"centos:stream9"*|\
"centos:stream10"*)
containerfile=Containerfile.stream
essential=centosstream_essential.sh
docs=centosstream_docs.sh
docs_pdf=tlmgr_docs_pdf.sh
pip3=pip3_docs.sh
repo=quay.io/centos
;;
"debian:11"*|\
"debian:12"*|\
"debian:13"*)
containerfile=Containerfile.debian
essential=ubuntu_essential.sh
docs=ubuntu_docs.sh
docs_pdf=ubuntu_docs_pdf.sh
pip3=pip3_docs.sh
;;
"fedora:43"*)
containerfile=Containerfile.fedora
essential=fedora_essential.sh
docs=fedora_docs.sh
docs_pdf=fedora_docs_pdf.sh
pip3=pip3_docs.sh
;;
"leap:15.6"*)
image=opensuse/leap:$version
containerfile=Containerfile.zypper
essential=opensuse_essential_15.6.sh
docs=opensuse_docs.sh
docs_pdf=opensuse_docs_pdf.sh
pip3=pip3_docs.sh
;;
"leap:16.0"*)
image=opensuse/leap:$version
containerfile=Containerfile.zypper
essential=opensuse_essential_16.0.sh
docs=opensuse_docs.sh
docs_pdf=opensuse_docs_pdf.sh
pip3=pip3_docs.sh
;;
"rockylinux:8"*|\
"rockylinux:9"*)
containerfile=Containerfile.rocky
essential=rockylinux_essential.sh
docs=rockylinux_docs.sh
docs_pdf=tlmgr_docs_pdf.sh
pip3=pip3_docs.sh
;;
"ubuntu:22.04"*|\
"ubuntu:24.04"*|\
"ubuntu:25.04"*|\
"ubuntu:25.10"*|\
"ubuntu:26.04"*)
containerfile=Containerfile.ubuntu
essential=ubuntu_essential.sh
docs=ubuntu_docs.sh
docs_pdf=ubuntu_docs_pdf.sh
pip3=pip3_docs.sh
;;
*)
echo "$image not supported!"
usage
exit 1
;;
esac
$OCI build \
--tag "yocto-docs-$sanitized_dockername:latest" \
--build-arg ARG_FROM="$repo/$image" \
--build-arg INCLUDE_ESSENTIAL_PACKAGES="${INCLUDE_ESSENTIAL_PACKAGES}" \
--build-arg ESSENTIAL="host_packages_scripts/$essential" \
--build-arg DOCS="host_packages_scripts/$docs" \
--build-arg DOCS_PDF="host_packages_scripts/$docs_pdf" \
--build-arg PIP3="host_packages_scripts/$pip3" \
--file "$SCRIPT_DIR/containerfiles/$containerfile" \
"$SCRIPT_DIR"
local -a args_run=(
--rm
--interactive
--tty
--volume="$DOCS_DIR:/docs:rw"
--workdir=/docs
--security-opt label=disable
)
if [ "$(basename "$OCI")" = "docker" ]; then
args_run+=(
--user="$(id -u)":"$(id -g)"
)
elif [ "$(basename "$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 "$@"
|
