Bootlin training-materials: embedded Linux slides and labs you rebuild yourself

A course repository, not a course

Bootlin's training-materials repository holds the document sources behind its embedded Linux and kernel training, and the primary language recorded for it is TeX. The homepage points at the company's training catalogue rather than at a download of the files.

The layout explains the shape of the thing. There are slides and labs directories for the content, a common directory for the shared LaTeX stylesheet and title pages, a typst directory for the newer format, an mk directory of make fragments, agenda and code directories, lab-data for the labs to work on, and utils for the container file and the git hook. A Makefile sits at the root and ties it together.

What makes this interesting for an engineer is that the content is not shipped as finished PDFs alone. It is a build system for documents, with formatting conventions, a pre-commit hook and a container recipe. A trainer can rebuild a course with their own examples, keep the structure Bootlin uses, and produce the same slide and lab PDFs.

The reverse reading matters too. If you are trying to evaluate Bootlin's training rather than reuse it, this repository is where the pedagogy is visible. The lab guidelines in the project documentation describe how a chapter must be structured, down to the subchapter command and the objectives line, which tells you what a Bootlin lab looks like before you ever attend one.

LaTeX and Typst in the same tree

The repository contains document sources in two formats, LaTeX with .tex files and Typst with .typ files, and the documentation is explicit about how the two coexist.

For the Typst content the rule is strict: the files are expected to be properly formatted at any point in the git history, and the chosen formatting tool is typstyle. To make sure an unformatted Typst file is never committed, the project ships a git pre-commit hook that you copy into your own hooks directory:

$ cp utils/git-hooks/pre-commit .git/hooks

Once installed, git refuses to commit any file that is not properly formatted, and it is then up to you to format those files with the command the hook hints at, stage them again and commit. That is a workflow decision rather than a technical necessity, and it is the kind of rule that tells you the project expects a mixed toolchain to be maintained by several people over time.

The Makefile reflects the same split. There is a separate variable for the LaTeX stylesheet, pointing at common/beamerthemeBootlin.sty, and a separate one for the Typst stylesheet, pointing at typst/local/bootlin/0.1.0/lib.typ. The Typst invocation gets its own options, including a root directory, a package path inside the repository, a font path and a flag to ignore system fonts.

So the direction of travel is a Typst pipeline being brought up alongside the LaTeX one, with the shared stylesheet as the thing being ported. A newcomer should expect to read the Makefile fragments in mk/ to find out which targets are already on Typst.

The toolchain is xelatex, Inkscape, dia and typst

Building the documents requires a real desktop publishing toolchain, and the documentation gives the package lists for two distributions.

On Ubuntu 22.04 the documented install is:

sudo apt install --no-install-recommends git-core inkscape \
  texlive-latex-base texlive-latex-extra texlive-font-utils dia \
  python3-pygments texlive-fonts-recommended \
  texlive-fonts-extra make texlive-xetex texlive-extra-utils \
  fonts-inconsolata fonts-liberation \
  xfonts-scalable lmodern texlive-science texlive-plain-generic \
  texlive-lang-french ghostscript

Arch Linux has its own list, pulling texlive-binextra, texlive-fontsextra, texlive-xetex and the rest, plus dia-git installed through the yay helper.

Two tools are listed separately because they are not in the package manager: Typst, with the documentation recommending the standalone executable installation method, and typstyle, the formatter for the Typst sources.

The Makefile shows what the tools are actually for. PDFLATEX is xelatex, so the PDFs are produced with XeLaTeX rather than pdfLaTeX, which is what allows the font selection the documents rely on. Inkscape converts the vector drawings, and the Makefile even detects whether Inkscape 1 is in use, because the output flag changed between versions. dia produces the diagrams. EPSTOPDF and ImageMagick handle the remaining raster conversions, and typst compile handles the Typst documents.

The overall dependency weight is the practical objection to adopting this repository as a starting point for your own course. It is a full publishing environment, not a single binary.

Building in a container avoids the whole toolchain

Because the dependency list is so long, the project provides a container recipe, and it is the only documented way to build without installing everything locally.

The container is built from the Dockerfile in the utils/container directory, and the documentation asks you to replace $OCI by either docker or podman:

   $ $OCI build -t bootlin-training:latest utils/container

Then you run a make target inside it. With Docker the invocation passes your own user id so that the files written into the working directory belong to you rather than to root:

      $ docker run -u $(id -u):$(id -g) -v $(pwd):/training -it --rm bootlin-training <target>

Podman has its own variant, using the keep-id user namespace option instead of the explicit user mapping:

      $ podman run --userns=keep-id -v $(pwd):/training -it --rm bootlin-training <target>

The target argument is a make target such as full-yocto-slides.pdf, and the documentation points at make help for the list.

One troubleshooting note covers the most common failure. If the materials stop compiling after you upgrade your distribution, you may have to run make clean for them to compile again, with a linked example case about a LaTeX and Beamer interaction that turns on toolchain versions. The stale auxiliary files left by a previous toolchain are the usual culprit, and the fix is one command.

Once the container exists, a full rebuild of a course is a single docker run, which makes this the practical way to work on the sources.

The Makefile is the index of every training

There is no single command that builds everything, and that is by design. The Makefile includes every fragment matching mk/*.mk, and the list of trainings is derived from those file names:

ALL_TRAININGS_MKS = $(sort $(notdir $(wildcard mk/*.mk)))
ALL_TRAININGS = $(patsubst %.mk,%,$(ALL_TRAININGS_MKS))

So the mk directory is the catalogue. Each fragment corresponds to a training, and the documented targets follow that pattern:

make full-linux-kernel-slides.pdf
make full-linux-kernel-bbb-labs.pdf

The Makefile also sets the shared output directory to out, points the LaTeX run at the stylesheet in the common directory through the TEXINPUTS environment variable and texfot, and passes the flags -shell-escape, -file-line-error and -halt-on-error to the LaTeX run. That last combination is worth understanding. -halt-on-error means a broken document fails the build instead of producing a PDF with an error in it, and -file-line-error makes the log point at the offending line, which matters when a course is hundreds of pages long.

The build also handles the picture pipeline. A helper function computes which .dia and .svg files need conversion to PDF and where the results belong, and the output of that step feeds the document builds. That is why Inkscape and dia appear in the dependency list: the diagrams are sources that are converted as part of the build, not assets checked in as images.

Authoring rules that make slides and labs consistent

The documentation spends a lot of space on formatting, and reading it is the fastest way to understand how the documents are put together.

For labs, a chapter must start with a subchapter command carrying the objectives, for example a subchapter whose second argument lists what the reader will set up and do. Sections and subsections are available for the rest of the structure. For fixed sized text inside a paragraph, the documentation insists on the \code macro rather than the plain typewriter style, because \code provides proper line wrapping on dashes and slashes, which keeps the line of text within the width of the page. It also notes that \code does not require escaping of dollar or low line signs, which is a small quality of life detail that shows up constantly in shell commands and file paths. The macro cannot be used in section or chapter titles, where the typewriter style is required instead, with the special characters escaped by hand.

For code blocks that stand alone, the verbatim environment is used, and it likewise needs no escaping of dollar or low line signs. When a block is too wide, the documentation suggests wrapping it in a small font size environment, with the warning that this must be used sparingly because the verbatim environment does not wrap lines and the result reads badly if overused. URLs go through a dedicated macro so they become clickable links in the PDF.

For slides, the rules are about reuse. A new training starts with a file in the common directory named after the training, containing the setup of variables such as authors and a title slide. Every new chapter should be split so it can be reused in other trainings, with one file per subsection named after the training, section and subsection, and the aggregation of all files is done by the Makefile. That is a content architecture decision: a kernel chapter can drop into a different course without unpicking it.

Code snippets are highlighted with the minted package, which uses pygments as its backend, and the Debian and Ubuntu package python-pygments is required for it.

A custom licence and a recent working tree

The licence is listed as a custom one that GitHub cannot classify, with a LICENSE file at the root of the repository, so anyone planning to reuse or redistribute the sources needs to read that file rather than assume a standard open source grant applies. This is a note on the repository's own terms, not legal advice.

The maintenance signal is straightforward: the last push was on 2026-10-20, and the repository has no GitHub releases, which is normal for a document source tree where the built PDFs are published through the training catalogue rather than through the repository's release page.

There is one more piece of tooling worth knowing about, for people who edit the sources in Emacs. The documentation recommends the AUCTex package:

sudo apt install auctex

and then adding a few lines to the Emacs configuration so that the code and url macros are treated as verbatim macros:

(load "auctex.el" nil t t)
(require 'latex)
(add-to-list 'LaTeX-verbatim-macros-with-braces "code")
(add-to-list 'LaTeX-verbatim-macros-with-braces "url")

The point of those lines is explained in the documentation: without them, Emacs text colorization falls over when characters such as dollar, low line or percent appear inside those macros unescaped. It is a small configuration detail that tells you the macros are used heavily in the sources.

Together, the repository is a well specified document pipeline with a container escape hatch, strict conventions and a formatting hook. Adopting it means adopting those conventions.

Editorial conclusion

Bootlin training-materials suits an engineer who teaches embedded Linux, or who wants to reuse a well structured kernel lab in an internal course, and who is prepared to install a fairly heavy TeX and graphics toolchain. It is the wrong choice if you only want the finished PDFs, since those are what the hosted training at bootlin.com/training/ is for, and it is the wrong choice if your team does not want to maintain a two-format document pipeline with a Typst migration in progress. Verify three things before you start: that your target exists in the list printed by make help, that the container path actually works on your machine, since it is the only documented way to avoid installing the toolchain locally, and that the custom LICENSE file at the root of the repository allows the reuse you have in mind.

Frequently asked questions

Official sources

1. bootlin/training-materials on GitHub
2. Issues
3. Project website
4. README