| Message ID | 20251211-build-docs-container-tlmgr-v2-3-58719c103a50@bootlin.com |
|---|---|
| State | Under Review |
| Headers | show |
| Series | Add missing CentOS Stream / RockyLinux distros to the system-requirements.rst doc | expand |
Hi Antonin, On 12/11/25 10:06 AM, Antonin Godard via lists.yoctoproject.org wrote: > Add support for building the docs in CentOS Stream 9. As there are no > official images for CentOS Stream, use tgagor/centos from dockerhub > which is actively updated. > There's one, on quay.io, managed by Red Hat. > The centosstream_essential.sh centosstream_docs.sh files are based on > the almalinux files. > > Introduce a new installation script: tlmgr_docs_pdf.sh. As I wasn't able > to locate all the necessary tex packages to build the documentation in a > PDF format, I resorted to using what is used on the Autobuilder: a local > installation of texlive packages through tlmgr. > > This will allow us to provide a way of building the docs as PDF for the > distros that lack this support at the moment. > > Use a new Containerfile.stream file as it needs TEXTOOLDIR exported for > installing the texlive tools in a known directory (we assume the base > dnf Containerfile does not need it, as it is currently the case for > Fedora). > Not applicable anymore since we use Containerfile.dnf? > Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> > --- > documentation/ref-manual/system-requirements.rst | 35 ++++++++++++++++++++++ > documentation/tools/build-docs-container | 14 ++++++++- > .../tools/containerfiles/Containerfile.dnf | 3 ++ > .../tools/containerfiles/Containerfile.stream | 1 + > .../host_packages_scripts/centosstream_docs.sh | 1 + > .../centosstream_essential.sh | 5 ++++ > .../tools/host_packages_scripts/tlmgr_docs_pdf.sh | 7 +++++ > 7 files changed, 65 insertions(+), 1 deletion(-) > > diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst > index 9ed29a1df..e9d5012e3 100644 > --- a/documentation/ref-manual/system-requirements.rst > +++ b/documentation/ref-manual/system-requirements.rst > @@ -266,6 +266,41 @@ documentation in PDF format: > .. literalinclude:: ../tools/host_packages_scripts/almalinux_docs_pdf.sh > :language: shell > > +CentOS Stream Packages > +---------------------- > + > +Here are the packages needed to build an image on a headless system > +with a supported CentOS Stream distribution: > + > +.. literalinclude:: ../tools/host_packages_scripts/centosstream_essential.sh > + :language: shell > + > +Here are the packages needed to build Project documentation manuals: > + > +.. literalinclude:: ../tools/host_packages_scripts/centosstream_docs.sh > + :language: shell > + > +.. literalinclude:: ../tools/host_packages_scripts/pip3_docs.sh > + :language: shell > + > +In addition to the previous packages, the following TeX Live packages > +are needed to build the documentation in PDF format and can be installed with > +the `TeX Live package manager <https://tug.org/texlive/tlmgr.html>`__: > + > +.. literalinclude:: ../tools/host_packages_scripts/tlmgr_docs_pdf.sh > + :language: shell > + > +.. warning:: > + > + The Tex Live installation above is only valid for `x86_64` hosts. > + > +Before building the documentation PDF, setup the ``PATH`` to use the installed > +packages: > + > +.. code-block:: console > + > + $ export PATH="${PATH}:${textooldir}/tl/bin/x86_64-linux" > + I'm assuming textooldir is NOT a typically set environment variable so we should specify the user is expected to modify this to match their path? > .. _system-requirements-buildtools: > > Required Git, tar, Python, make and gcc Versions > diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container > index 7d25b15b9..0800c4333 100755 > --- a/documentation/tools/build-docs-container > +++ b/documentation/tools/build-docs-container > @@ -33,6 +33,7 @@ $0 OCI_IMAGE [make arguments...] > > OCI_IMAGE is an image:tag of an OCI image hosted on hub.docker.com. It is one > of: > + - centos:stream9 > - debian:12 > - debian:13 > - fedora:39 > @@ -91,6 +92,14 @@ main () > # docs_pdf=almalinux_docs_pdf.sh > # pip3=pip3_docs.sh > # ;; > + "centos:stream9"*) > + 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 > + ;; > # Missing python3-saneyaml > # "debian:11"*|\ > "debian:12"*|\ > @@ -135,9 +144,12 @@ main () > ;; > esac > > + # Default to docker.io unless specified above > + [ -z "$repo" ] && repo=docker.io > + Maybe set this at the top with other defaults so they all are in the same place? > $OCI build \ > --tag "yocto-docs-$sanitized_dockername:latest" \ > - --build-arg ARG_FROM="docker.io/$image" \ > + --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" \ > diff --git a/documentation/tools/containerfiles/Containerfile.dnf b/documentation/tools/containerfiles/Containerfile.dnf > index 65c526705..fd47fde34 100644 > --- a/documentation/tools/containerfiles/Containerfile.dnf > +++ b/documentation/tools/containerfiles/Containerfile.dnf > @@ -7,6 +7,9 @@ ARG DOCS=fedora_docs.sh > ARG DOCS_PDF=fedora_docs_pdf.sh > ARG PIP3=pip3_docs.sh > > +ENV TEXTOOLDIR=/opt/docs-build-tex-tools > +ENV PATH="$PATH:$TEXTOOLDIR/tl/bin/x86_64-linux" > + > # 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 > diff --git a/documentation/tools/containerfiles/Containerfile.stream b/documentation/tools/containerfiles/Containerfile.stream > new file mode 120000 > index 000000000..7237e9b99 > --- /dev/null > +++ b/documentation/tools/containerfiles/Containerfile.stream > @@ -0,0 +1 @@ > +Containerfile.dnf > \ No newline at end of file > diff --git a/documentation/tools/host_packages_scripts/centosstream_docs.sh b/documentation/tools/host_packages_scripts/centosstream_docs.sh > new file mode 100644 > index 000000000..351f75893 > --- /dev/null > +++ b/documentation/tools/host_packages_scripts/centosstream_docs.sh > @@ -0,0 +1 @@ > +sudo dnf install -y git glibc-locale-source librsvg2-tools make python3-pip which wget This is the same as for documentation/tools/host_packages_scripts/almalinux_docs.sh except for -y and wget. I'm assuming we only need the latter for the PDF variant, so maybe symlink this here to almalinux_docs.sh and then install wget as part of tlmgr_docs_pdf.sh? If curl is installed as part of the other dependencies, another option is to use curl instead of wget to avoid requiring this additional dependency? > diff --git a/documentation/tools/host_packages_scripts/centosstream_essential.sh b/documentation/tools/host_packages_scripts/centosstream_essential.sh > new file mode 100644 > index 000000000..e38fa93c2 > --- /dev/null > +++ b/documentation/tools/host_packages_scripts/centosstream_essential.sh > @@ -0,0 +1,5 @@ > +sudo dnf install -y epel-release > +sudo yum install -y dnf-plugins-core > +sudo dnf config-manager --set-enabled crb > +sudo dnf makecache > +sudo dnf install -y bzip2 ccache chrpath cpio cpp diffstat diffutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip libacl make patch perl perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip rpcgen socat tar texinfo unzip wget which xz zstd Isn't this the same for documentation/tools/host_packages_scripts/almalinux_essential.sh? so just symlink it? > diff --git a/documentation/tools/host_packages_scripts/tlmgr_docs_pdf.sh b/documentation/tools/host_packages_scripts/tlmgr_docs_pdf.sh > new file mode 100644 > index 000000000..727bf9e35 > --- /dev/null > +++ b/documentation/tools/host_packages_scripts/tlmgr_docs_pdf.sh > @@ -0,0 +1,7 @@ > +textooldir=${TEXTOOLDIR:-"./docs-build-tex-tools"} > +mkdir -p "$textooldir"/tl > +wget https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz -O "$textooldir"/install-tl-unx.tar.gz > +tar xzf "$textooldir"/install-tl-unx.tar.gz -C "$textooldir" > +"$textooldir"/install-tl-*/install-tl --scheme=small --texdir="${textooldir}"/tl --no-interaction > +PATH="$PATH:${textooldir}/tl/bin/x86_64-linux" tlmgr install titlesec varwidth tabulary needspace upquote framed capt-of wrapfig fncychap gnu-freefont ctex latexmk nimbus15 > +rm -r "$textooldir"/install-tl* > > > > -=-=-=-=-=-=-=-=-=-=-=- > Links: You receive all messages sent to this group. > View/Reply Online (#8243): https://lists.yoctoproject.org/g/docs/message/8243 > Mute This Topic: https://lists.yoctoproject.org/mt/116726509/6293953 > Group Owner: docs+owner@lists.yoctoproject.org > Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [quentin.schulz@cherry.de] > -=-=-=-=-=-=-=-=-=-=-=- >
diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst index 9ed29a1df..e9d5012e3 100644 --- a/documentation/ref-manual/system-requirements.rst +++ b/documentation/ref-manual/system-requirements.rst @@ -266,6 +266,41 @@ documentation in PDF format: .. literalinclude:: ../tools/host_packages_scripts/almalinux_docs_pdf.sh :language: shell +CentOS Stream Packages +---------------------- + +Here are the packages needed to build an image on a headless system +with a supported CentOS Stream distribution: + +.. literalinclude:: ../tools/host_packages_scripts/centosstream_essential.sh + :language: shell + +Here are the packages needed to build Project documentation manuals: + +.. literalinclude:: ../tools/host_packages_scripts/centosstream_docs.sh + :language: shell + +.. literalinclude:: ../tools/host_packages_scripts/pip3_docs.sh + :language: shell + +In addition to the previous packages, the following TeX Live packages +are needed to build the documentation in PDF format and can be installed with +the `TeX Live package manager <https://tug.org/texlive/tlmgr.html>`__: + +.. literalinclude:: ../tools/host_packages_scripts/tlmgr_docs_pdf.sh + :language: shell + +.. warning:: + + The Tex Live installation above is only valid for `x86_64` hosts. + +Before building the documentation PDF, setup the ``PATH`` to use the installed +packages: + +.. code-block:: console + + $ export PATH="${PATH}:${textooldir}/tl/bin/x86_64-linux" + .. _system-requirements-buildtools: Required Git, tar, Python, make and gcc Versions diff --git a/documentation/tools/build-docs-container b/documentation/tools/build-docs-container index 7d25b15b9..0800c4333 100755 --- a/documentation/tools/build-docs-container +++ b/documentation/tools/build-docs-container @@ -33,6 +33,7 @@ $0 OCI_IMAGE [make arguments...] OCI_IMAGE is an image:tag of an OCI image hosted on hub.docker.com. It is one of: + - centos:stream9 - debian:12 - debian:13 - fedora:39 @@ -91,6 +92,14 @@ main () # docs_pdf=almalinux_docs_pdf.sh # pip3=pip3_docs.sh # ;; + "centos:stream9"*) + 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 + ;; # Missing python3-saneyaml # "debian:11"*|\ "debian:12"*|\ @@ -135,9 +144,12 @@ main () ;; esac + # Default to docker.io unless specified above + [ -z "$repo" ] && repo=docker.io + $OCI build \ --tag "yocto-docs-$sanitized_dockername:latest" \ - --build-arg ARG_FROM="docker.io/$image" \ + --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" \ diff --git a/documentation/tools/containerfiles/Containerfile.dnf b/documentation/tools/containerfiles/Containerfile.dnf index 65c526705..fd47fde34 100644 --- a/documentation/tools/containerfiles/Containerfile.dnf +++ b/documentation/tools/containerfiles/Containerfile.dnf @@ -7,6 +7,9 @@ ARG DOCS=fedora_docs.sh ARG DOCS_PDF=fedora_docs_pdf.sh ARG PIP3=pip3_docs.sh +ENV TEXTOOLDIR=/opt/docs-build-tex-tools +ENV PATH="$PATH:$TEXTOOLDIR/tl/bin/x86_64-linux" + # 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 diff --git a/documentation/tools/containerfiles/Containerfile.stream b/documentation/tools/containerfiles/Containerfile.stream new file mode 120000 index 000000000..7237e9b99 --- /dev/null +++ b/documentation/tools/containerfiles/Containerfile.stream @@ -0,0 +1 @@ +Containerfile.dnf \ No newline at end of file diff --git a/documentation/tools/host_packages_scripts/centosstream_docs.sh b/documentation/tools/host_packages_scripts/centosstream_docs.sh new file mode 100644 index 000000000..351f75893 --- /dev/null +++ b/documentation/tools/host_packages_scripts/centosstream_docs.sh @@ -0,0 +1 @@ +sudo dnf install -y git glibc-locale-source librsvg2-tools make python3-pip which wget diff --git a/documentation/tools/host_packages_scripts/centosstream_essential.sh b/documentation/tools/host_packages_scripts/centosstream_essential.sh new file mode 100644 index 000000000..e38fa93c2 --- /dev/null +++ b/documentation/tools/host_packages_scripts/centosstream_essential.sh @@ -0,0 +1,5 @@ +sudo dnf install -y epel-release +sudo yum install -y dnf-plugins-core +sudo dnf config-manager --set-enabled crb +sudo dnf makecache +sudo dnf install -y bzip2 ccache chrpath cpio cpp diffstat diffutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip libacl make patch perl perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip rpcgen socat tar texinfo unzip wget which xz zstd diff --git a/documentation/tools/host_packages_scripts/tlmgr_docs_pdf.sh b/documentation/tools/host_packages_scripts/tlmgr_docs_pdf.sh new file mode 100644 index 000000000..727bf9e35 --- /dev/null +++ b/documentation/tools/host_packages_scripts/tlmgr_docs_pdf.sh @@ -0,0 +1,7 @@ +textooldir=${TEXTOOLDIR:-"./docs-build-tex-tools"} +mkdir -p "$textooldir"/tl +wget https://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz -O "$textooldir"/install-tl-unx.tar.gz +tar xzf "$textooldir"/install-tl-unx.tar.gz -C "$textooldir" +"$textooldir"/install-tl-*/install-tl --scheme=small --texdir="${textooldir}"/tl --no-interaction +PATH="$PATH:${textooldir}/tl/bin/x86_64-linux" tlmgr install titlesec varwidth tabulary needspace upquote framed capt-of wrapfig fncychap gnu-freefont ctex latexmk nimbus15 +rm -r "$textooldir"/install-tl*
Add support for building the docs in CentOS Stream 9. As there are no official images for CentOS Stream, use tgagor/centos from dockerhub which is actively updated. The centosstream_essential.sh centosstream_docs.sh files are based on the almalinux files. Introduce a new installation script: tlmgr_docs_pdf.sh. As I wasn't able to locate all the necessary tex packages to build the documentation in a PDF format, I resorted to using what is used on the Autobuilder: a local installation of texlive packages through tlmgr. This will allow us to provide a way of building the docs as PDF for the distros that lack this support at the moment. Use a new Containerfile.stream file as it needs TEXTOOLDIR exported for installing the texlive tools in a known directory (we assume the base dnf Containerfile does not need it, as it is currently the case for Fedora). Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- documentation/ref-manual/system-requirements.rst | 35 ++++++++++++++++++++++ documentation/tools/build-docs-container | 14 ++++++++- .../tools/containerfiles/Containerfile.dnf | 3 ++ .../tools/containerfiles/Containerfile.stream | 1 + .../host_packages_scripts/centosstream_docs.sh | 1 + .../centosstream_essential.sh | 5 ++++ .../tools/host_packages_scripts/tlmgr_docs_pdf.sh | 7 +++++ 7 files changed, 65 insertions(+), 1 deletion(-)