* [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
@ 2026-08-26 1:34 Trevor Woerner
2026-08-26 1:34 ` [PATCH 01/10] ref-manual/variables.rst: use the bitbake code-block language Trevor Woerner
` (12 more replies)
0 siblings, 13 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say
what they are instead of rendering as plain literal blocks. This tags
the ones in yocto-docs.
One patch per manual, which is also roughly one reviewable unit per
patch. No prose changes, no reflowing, no reindenting - every hunk turns
a literal-block introducer into a code-block directive and nothing else.
Which blocks were converted was decided by reading, not by pattern
matching. Blocks that share BitBake's assignment shape but are another
language were left alone: a Makefile, Django settings, an Automake
fragment, a wic kickstart include, kernel .scc metadata, U-Boot Image
Tree Source. So were blocks an author had deliberately marked "none",
which usually means "this is not purely code" rather than "nobody got
round to it".
Please do not apply this yet
----------------------------
The autobuilder builds the docs with a pinned buildtools tarball that
currently carries Pygments 2.19.2, which predates the BitBake lexer.
run-docs-build also passes SPHINXOPTS="-j auto", dropping the -W the
Makefile defaults to, so on that toolchain every one of these blocks
would publish unhighlighted and the build would still succeed. I have
asked separately about refreshing that tarball.
Sending now for review rather than to be merged. Once the toolchain can
render it, this applies as-is.
Depends on
----------
"docs: state the language of nine literal blocks explicitly", sent
separately, which gives some non-BitBake blocks their correct language.
That patch stands on its own and can go in independently; this series
is based on it only so the two do not touch the same lines.
Not included
------------
Six blocks in ref-manual/ trip a defect in the released BitBake lexer,
fixed upstream but not yet in a release. They are a separate patch, held
until that release, so the rest is not blocked behind them.
Trevor Woerner (10):
ref-manual/variables.rst: use the bitbake code-block language
ref-manual: use the bitbake code-block language
dev-manual: use the bitbake code-block language
migration-guides: use the bitbake code-block language
kernel-dev: use the bitbake code-block language
test-manual: use the bitbake code-block language
overview-manual: use the bitbake code-block language
security-manual: use the bitbake code-block language
sdk-manual: use the bitbake code-block language
docs-wide: use the bitbake code-block language
documentation/brief-yoctoprojectqs/index.rst | 4 +-
documentation/bsp-manual/bsp.rst | 28 +-
.../contributor-guide/recipe-style-guide.rst | 24 +-
documentation/dev-manual/bblock.rst | 4 +-
documentation/dev-manual/bmaptool.rst | 4 +-
documentation/dev-manual/build-quality.rst | 8 +-
documentation/dev-manual/building.rst | 44 +-
.../dev-manual/creating-fragments.rst | 6 +-
.../dev-manual/custom-distribution.rst | 4 +-
.../dev-manual/customizing-images.rst | 32 +-
documentation/dev-manual/debugging.rst | 40 +-
documentation/dev-manual/device-manager.rst | 12 +-
documentation/dev-manual/devtool.rst | 8 +-
documentation/dev-manual/disk-space.rst | 4 +-
.../dev-manual/error-reporting-tool.rst | 12 +-
documentation/dev-manual/external-scm.rst | 20 +-
.../dev-manual/gobject-introspection.rst | 12 +-
documentation/dev-manual/hashequivserver.rst | 12 +-
documentation/dev-manual/init-manager.rst | 16 +-
documentation/dev-manual/layers.rst | 56 +-
documentation/dev-manual/libraries.rst | 12 +-
documentation/dev-manual/licenses.rst | 60 +-
.../dev-manual/limiting-resources.rst | 4 +-
documentation/dev-manual/multiconfig.rst | 40 +-
documentation/dev-manual/new-machine.rst | 4 +-
documentation/dev-manual/new-recipe.rst | 160 +-
documentation/dev-manual/packages.rst | 44 +-
.../dev-manual/poky-manual-setup.rst | 4 +-
.../dev-manual/prebuilt-libraries.rst | 12 +-
documentation/dev-manual/qemu.rst | 4 +-
documentation/dev-manual/quilt.rst | 4 +-
documentation/dev-manual/sbom.rst | 4 +-
.../dev-manual/speeding-up-build.rst | 4 +-
.../dev-manual/sstate-mirrors-setup.rst | 16 +-
.../dev-manual/temporary-source-code.rst | 8 +-
.../dev-manual/upgrading-recipes.rst | 12 +-
documentation/dev-manual/wayland.rst | 8 +-
documentation/dev-manual/x32-psabi.rst | 4 +-
documentation/kernel-dev/advanced.rst | 48 +-
documentation/kernel-dev/common.rst | 88 +-
documentation/kernel-dev/faq.rst | 8 +-
.../migration-guides/migration-1.3.rst | 8 +-
.../migration-guides/migration-1.6.rst | 12 +-
.../migration-guides/migration-1.7.rst | 4 +-
.../migration-guides/migration-1.8.rst | 12 +-
.../migration-guides/migration-2.0.rst | 8 +-
.../migration-guides/migration-2.1.rst | 4 +-
.../migration-guides/migration-2.2.rst | 11 +-
.../migration-guides/migration-2.3.rst | 12 +-
.../migration-guides/migration-2.5.rst | 4 +-
.../migration-guides/migration-2.6.rst | 12 +-
.../migration-guides/migration-3.0.rst | 4 +-
.../migration-guides/migration-3.1.rst | 12 +-
.../migration-guides/migration-3.2.rst | 8 +-
.../migration-guides/migration-3.3.rst | 8 +-
.../migration-guides/migration-3.4.rst | 16 +-
.../migration-guides/migration-4.0.rst | 12 +-
.../migration-guides/migration-4.1.rst | 8 +-
.../migration-guides/migration-4.2.rst | 12 +-
.../migration-guides/migration-5.1.rst | 12 +-
.../migration-guides/migration-5.2.rst | 24 +-
.../migration-guides/migration-5.3.rst | 36 +-
.../migration-guides/migration-6.0.rst | 44 +-
.../migration-guides/migration-6.1.rst | 12 +-
.../migration-guides/release-notes-4.0.rst | 4 +-
.../migration-guides/release-notes-4.3.rst | 4 +-
.../migration-guides/release-notes-5.0.rst | 4 +-
.../migration-guides/release-notes-5.3.rst | 8 +-
documentation/overview-manual/concepts.rst | 68 +-
documentation/profile-manual/intro.rst | 16 +-
documentation/ref-manual/classes.rst | 168 +-
.../ref-manual/devtool-reference.rst | 4 +-
documentation/ref-manual/faq.rst | 20 +-
documentation/ref-manual/features.rst | 12 +-
documentation/ref-manual/qa-checks.rst | 20 +-
documentation/ref-manual/tasks.rst | 20 +-
documentation/ref-manual/variables.rst | 1635 ++++++++++++-----
.../appendix-customizing-standard.rst | 4 +-
.../sdk-manual/appendix-customizing.rst | 16 +-
.../security-manual/read-only-rootfs.rst | 8 +-
.../security-manual/securing-images.rst | 8 +-
.../security-manual/sstate-signing.rst | 16 +-
.../security-manual/vulnerabilities.rst | 32 +-
documentation/test-manual/intro.rst | 4 +-
documentation/test-manual/ptest.rst | 24 +-
.../test-manual/reproducible-builds.rst | 8 +-
documentation/test-manual/runtime-testing.rst | 52 +-
87 files changed, 2505 insertions(+), 843 deletions(-)
^ permalink raw reply [flat|nested] 33+ messages in thread
* [PATCH 01/10] ref-manual/variables.rst: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 02/10] ref-manual: " Trevor Woerner
` (11 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 418 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
The variables glossary is the densest concentration of BitBake syntax in
the documentation, and nearly every entry showing how to set a variable
was affected.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
documentation/ref-manual/variables.rst | 1635 ++++++++++++++++++------
1 file changed, 1226 insertions(+), 409 deletions(-)
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 646a77982646..61a4c6faca20 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -31,7 +31,9 @@ system and gives an overview of their function and contents.
ABI extensions are set in the machine include files. For example, the
``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
- following extension::
+ following extension:
+
+ .. code-block:: bitbake
ABIEXTENSION = "eabi"
@@ -43,7 +45,9 @@ system and gives an overview of their function and contents.
requirement on the existence of the package.
Like all package-controlling variables, you must always use them in
- conjunction with a package name override, as in::
+ conjunction with a package name override, as in:
+
+ .. code-block:: bitbake
ALLOW_EMPTY:${PN} = "1"
ALLOW_EMPTY:${PN}-dev = "1"
@@ -58,7 +62,9 @@ system and gives an overview of their function and contents.
To use the variable, list out the package's commands that are also
provided by another package. For example, if the ``busybox`` package
- has four such commands, you identify them as follows::
+ has four such commands, you identify them as follows:
+
+ .. code-block:: bitbake
ALTERNATIVE:busybox = "sh sed test bracket"
@@ -71,7 +77,9 @@ system and gives an overview of their function and contents.
locations. For example, if the ``bracket`` command provided by the
``busybox`` package is duplicated through another package, you must
use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual
- location::
+ location:
+
+ .. code-block:: bitbake
ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
@@ -92,7 +100,9 @@ system and gives an overview of their function and contents.
default regardless of the command name or package, a default for
specific duplicated commands regardless of the package, or a default
for specific commands tied to particular packages. Here are the
- available syntax forms::
+ available syntax forms:
+
+ .. code-block:: bitbake
ALTERNATIVE_PRIORITY = "priority"
ALTERNATIVE_PRIORITY[name] = "priority"
@@ -108,7 +118,9 @@ system and gives an overview of their function and contents.
default location for all duplicated commands regardless of the
command name or package, a default for specific duplicated commands
regardless of the package, or a default for specific commands tied to
- particular packages. Here are the available syntax forms::
+ particular packages. Here are the available syntax forms:
+
+ .. code-block:: bitbake
ALTERNATIVE_TARGET = "target"
ALTERNATIVE_TARGET[name] = "target"
@@ -156,7 +168,9 @@ system and gives an overview of their function and contents.
determines the type of information used to create a released archive.
You can use this variable to create archives of patched source,
original source, configured source, and so forth by employing the
- following variable flags (varflags)::
+ following variable flags (varflags):
+
+ .. code-block:: bitbake
ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
@@ -196,7 +210,9 @@ system and gives an overview of their function and contents.
shlibname:packagename[_version]
Here is an example that adds a shared library named ``libEGL.so.1``
- as being provided by the ``libegl-implementation`` package::
+ as being provided by the ``libegl-implementation`` package:
+
+ .. code-block:: bitbake
ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
@@ -217,14 +233,18 @@ system and gives an overview of their function and contents.
:term:`AUTOREV`
When :term:`SRCREV` is set to the value of this variable, it specifies to
- use the latest source revision in the repository. Here is an example::
+ use the latest source revision in the repository. Here is an example:
+
+ .. code-block:: bitbake
SRCREV = "${AUTOREV}"
If you use the previous statement to retrieve the latest version of
software, you need to make sure :term:`PV` contains the ``+`` sign so
:term:`bitbake` includes source control information to :term:`PKGV` when
- packaging the recipe. For example::
+ packaging the recipe. For example:
+
+ .. code-block:: bitbake
PV = "6.10.y+git"
@@ -259,7 +279,9 @@ system and gives an overview of their function and contents.
Azure Storage Shared Access Signature, when using the
:ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
This variable can be defined to be used by the fetcher to authenticate
- and gain access to non-public artifacts::
+ and gain access to non-public artifacts:
+
+ .. code-block:: bitbake
AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""
@@ -270,7 +292,9 @@ system and gives an overview of their function and contents.
The directory within the :term:`Build Directory` in which the
OpenEmbedded build system places generated objects during a recipe's
build process. By default, this directory is the same as the
- :term:`S` directory, which is defined as::
+ :term:`S` directory, which is defined as:
+
+ .. code-block:: bitbake
S = "${UNPACKDIR}/${BP}"
@@ -284,13 +308,17 @@ system and gives an overview of their function and contents.
packages are packages installed only through the
:term:`RRECOMMENDS` variable. You can prevent any
of these "recommended" packages from being installed by listing them
- with the :term:`BAD_RECOMMENDATIONS` variable::
+ with the :term:`BAD_RECOMMENDATIONS` variable:
+
+ .. code-block:: bitbake
BAD_RECOMMENDATIONS = "package_name package_name package_name ..."
You can set this variable globally in your ``local.conf`` file or you
can attach it to a specific image recipe by using the recipe name
- override::
+ override:
+
+ .. code-block:: bitbake
BAD_RECOMMENDATIONS:pn-target_image = "package_name"
@@ -315,7 +343,9 @@ system and gives an overview of their function and contents.
By default, all built binaries will be deployed and installed under their
original name.
- Here is an example usage of this variable::
+ Here is an example usage of this variable:
+
+ .. code-block:: bitbake
BAREBOX_BINARY = "barebox-boundarydevices-imx6dl-nitrogen6x-1g.img"
@@ -326,7 +356,9 @@ system and gives an overview of their function and contents.
This variable is mainly useful for generic use cases where a dedicated
configuration is not required.
The :ref:`ref-classes-barebox` class itself already sets it for some QEMU
- machines::
+ machines:
+
+ .. code-block:: bitbake
BAREBOX_CONFIG:qemuarm = "multi_v7_defconfig"
BAREBOX_CONFIG:qemuarm64 = "multi_v8_defconfig"
@@ -361,7 +393,9 @@ system and gives an overview of their function and contents.
- There is limited support for wildcard matching against the beginning of
host names. For example, the following setting matches
- ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``::
+ ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``:
+
+ .. code-block:: bitbake
BB_ALLOWED_NETWORKS = "*.gnu.org"
@@ -473,7 +507,9 @@ system and gives an overview of their function and contents.
not specify G, M, or K, Kbytes is assumed by
default. Do not use GB, MB, or KB.
- Here are some examples::
+ Here are some examples:
+
+ .. code-block:: bitbake
BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
@@ -513,7 +549,9 @@ system and gives an overview of their function and contents.
If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
- monitoring interval defaults to the following::
+ monitoring interval defaults to the following:
+
+ .. code-block:: bitbake
BB_DISKMON_WARNINTERVAL = "50M,5K"
@@ -536,7 +574,9 @@ system and gives an overview of their function and contents.
G, M, or K for Gbytes, Mbytes, or Kbytes,
respectively. You cannot use GB, MB, or KB.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
BB_DISKMON_WARNINTERVAL = "50M,5K"
@@ -568,7 +608,9 @@ system and gives an overview of their function and contents.
For performance reasons, creating and placing tarballs of these
repositories is not the default action by the OpenEmbedded build
- system::
+ system:
+
+ .. code-block:: bitbake
BB_GENERATE_MIRROR_TARBALLS = "1"
@@ -724,7 +766,9 @@ system and gives an overview of their function and contents.
long the BitBake server stays resident between invocations.
For example, the following statement in your ``local.conf`` file
- instructs the server to be unloaded after 20 seconds of inactivity::
+ instructs the server to be unloaded after 20 seconds of inactivity:
+
+ .. code-block:: bitbake
BB_SERVER_TIMEOUT = "20"
@@ -775,7 +819,9 @@ system and gives an overview of their function and contents.
the form "``multilib:``\ multilib_name".
To build a different variant of the recipe with a minimal amount of
- code, it usually is as simple as adding the following to your recipe::
+ code, it usually is as simple as adding the following to your recipe:
+
+ .. code-block:: bitbake
BBCLASSEXTEND =+ "native nativesdk"
BBCLASSEXTEND =+ "multilib:multilib_name"
@@ -857,7 +903,9 @@ system and gives an overview of their function and contents.
``collection_name:filename_pattern``.
The following example identifies two collection names and two
- filename patterns::
+ filename patterns:
+
+ .. code-block:: bitbake
BBFILES_DYNAMIC += " \
clang-layer:${LAYERDIR}/dynamic-layers/meta-clang/*/*/*.bbappend \
@@ -888,7 +936,9 @@ system and gives an overview of their function and contents.
:term:`BBLAYERS`
Lists the layers to enable during the build. This variable is defined
in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
BBLAYERS = " \
/home/scottrif/bitbake-builds/layers/meta \
@@ -920,13 +970,17 @@ system and gives an overview of their function and contents.
The following example uses a complete regular expression to tell
BitBake to ignore all recipe and recipe append files in the
- ``meta-ti/recipes-misc/`` directory::
+ ``meta-ti/recipes-misc/`` directory:
+
+ .. code-block:: bitbake
BBMASK = "meta-ti/recipes-misc/"
If you want to mask out multiple directories or recipes, you can
specify multiple regular expression fragments. This next example
- masks out multiple directories and individual recipes::
+ masks out multiple directories and individual recipes:
+
+ .. code-block:: bitbake
BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
BBMASK += "/meta-oe/recipes-support/"
@@ -944,7 +998,9 @@ system and gives an overview of their function and contents.
building targets with multiple configurations. Use this variable in
your ``conf/local.conf`` configuration file. Specify a
multiconfigname for each configuration file you are using. For
- example, the following line specifies three configuration files::
+ example, the following line specifies three configuration files:
+
+ .. code-block:: bitbake
BBMULTICONFIG = "configA configB configC"
@@ -987,7 +1043,9 @@ system and gives an overview of their function and contents.
and replaced.
To add multiple scripts, separate them by spaces. Here is an example
- from the ``libpng`` recipe::
+ from the ``libpng`` recipe:
+
+ .. code-block:: bitbake
BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
@@ -1042,7 +1100,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_AR`
Specifies the architecture-specific :manpage:`archiver <ar(1)>` for the
build host, and its default definition is derived in part from
- :term:`BUILD_PREFIX`::
+ :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_AR = "${BUILD_PREFIX}ar"
@@ -1063,7 +1123,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_AS`
Specifies the architecture-specific :manpage:`assembler <as(1)>` for the
build host, and its default definition is derived in part from
- :term:`BUILD_PREFIX`::
+ :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_AS = "${BUILD_PREFIX}as ${BUILD_AS_ARCH}"
@@ -1083,7 +1145,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_CC`
Specifies the architecture-specific C compiler for the build host,
and its default definition is derived in part from :term:`BUILD_PREFIX`
- and :term:`BUILD_CC_ARCH`::
+ and :term:`BUILD_CC_ARCH`:
+
+ .. code-block:: bitbake
BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}"
@@ -1104,7 +1168,9 @@ system and gives an overview of their function and contents.
Specifies the :manpage:`linker <ld(1)>` command to be used for the build
host when the C compiler is being used as the linker, and its default
definition is derived in part from :term:`BUILD_PREFIX` and
- :term:`BUILD_CC_ARCH`::
+ :term:`BUILD_CC_ARCH`:
+
+ .. code-block:: bitbake
BUILD_CCLD = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}"
@@ -1126,7 +1192,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_CPP`
Specifies the C preprocessor command (to both the C and the C++ compilers)
when building for the build host, and its default definition is derived in
- part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`::
+ part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`:
+
+ .. code-block:: bitbake
BUILD_CPP = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH} -E"
@@ -1148,7 +1216,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_CXX`
Specifies the architecture-specific C++ compiler for the build host,
and its default definition is derived in part from :term:`BUILD_PREFIX`
- and :term:`BUILD_CC_ARCH`::
+ and :term:`BUILD_CC_ARCH`:
+
+ .. code-block:: bitbake
BUILD_CXX = "${CCACHE}${BUILD_PREFIX}g++ ${BUILD_CC_ARCH}"
@@ -1170,7 +1240,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_FC`
Specifies the Fortran compiler command for the build host, and its default
definition is derived in part from :term:`BUILD_PREFIX` and
- :term:`BUILD_CC_ARCH`::
+ :term:`BUILD_CC_ARCH`:
+
+ .. code-block:: bitbake
BUILD_FC = "${BUILD_PREFIX}gfortran ${BUILD_CC_ARCH}"
@@ -1186,7 +1258,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_LD`
Specifies the linker command for the build host, and its default
definition is derived in part from :term:`BUILD_PREFIX` and
- :term:`BUILD_LD_ARCH`::
+ :term:`BUILD_LD_ARCH`:
+
+ .. code-block:: bitbake
BUILD_LD = "${BUILD_PREFIX}ld ${BUILD_LD_ARCH}"
@@ -1212,7 +1286,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_NM`
Specifies the architecture-specific utility to list symbols from object
files for the build host, and its default definition is derived in part
- from :term:`BUILD_PREFIX`::
+ from :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_NM = "${BUILD_PREFIX}nm"
@@ -1228,7 +1304,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_OBJCOPY`
Specifies the architecture-specific utility to copy object files for the
build host, and its default definition is derived in part from
- :term:`BUILD_PREFIX`::
+ :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_OBJCOPY = "${BUILD_PREFIX}objcopy"
@@ -1244,7 +1322,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_OBJDUMP`
Specifies the architecture-specific utility to display object files
information for the build host, and its default definition is derived in
- part from :term:`BUILD_PREFIX`::
+ part from :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_OBJDUMP = "${BUILD_PREFIX}objdump"
@@ -1280,7 +1360,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_RANLIB`
Specifies the architecture-specific utility to generate indexes for
archives for the build host, and its default definition is derived in part
- from :term:`BUILD_PREFIX`::
+ from :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_RANLIB = "${BUILD_PREFIX}ranlib -D"
@@ -1296,7 +1378,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_READELF`
Specifies the architecture-specific utility to display information about
ELF files for the build host, and its default definition is derived in
- part from :term:`BUILD_PREFIX`::
+ part from :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_READELF = "${BUILD_PREFIX}readelf"
@@ -1312,7 +1396,9 @@ system and gives an overview of their function and contents.
:term:`BUILD_STRIP`
Specifies the command to be used to strip debugging symbols from binaries
produced for the build host, and its default definition is derived in part
- from :term:`BUILD_PREFIX`::
+ from :term:`BUILD_PREFIX`:
+
+ .. code-block:: bitbake
BUILD_STRIP = "${BUILD_PREFIX}strip"
@@ -1358,7 +1444,9 @@ system and gives an overview of their function and contents.
"1".
By default, the :ref:`ref-classes-buildhistory` class
- enables committing the buildhistory output in a local Git repository::
+ enables committing the buildhistory output in a local Git repository:
+
+ .. code-block:: bitbake
BUILDHISTORY_COMMIT ?= "1"
@@ -1375,7 +1463,9 @@ system and gives an overview of their function and contents.
does not produce an error.
By default, the :ref:`ref-classes-buildhistory` class sets the variable
- as follows::
+ as follows:
+
+ .. code-block:: bitbake
BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
@@ -1386,7 +1476,9 @@ system and gives an overview of their function and contents.
see the :ref:`ref-classes-buildhistory` class.
By default, the :ref:`ref-classes-buildhistory` class sets the directory
- as follows::
+ as follows:
+
+ .. code-block:: bitbake
BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
@@ -1414,7 +1506,9 @@ system and gives an overview of their function and contents.
each file staged (i.e. the output of the task).
By default, the :ref:`ref-classes-buildhistory` class enables the
- following features::
+ following features:
+
+ .. code-block:: bitbake
BUILDHISTORY_FEATURES ?= "image package sdk"
@@ -1430,7 +1524,9 @@ system and gives an overview of their function and contents.
Consequently, you can include files that might not always be present.
By default, the :ref:`ref-classes-buildhistory` class provides paths to
- the following files::
+ the following files:
+
+ .. code-block:: bitbake
BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
@@ -1443,7 +1539,9 @@ system and gives an overview of their function and contents.
all use the same top level directory.
By default, the :ref:`ref-classes-buildhistory` class sets the variable
- as follows::
+ as follows:
+
+ .. code-block:: bitbake
BUILDHISTORY_PATH_PREFIX_STRIP ?= ""
@@ -1461,7 +1559,9 @@ system and gives an overview of their function and contents.
repository.
By default, the :ref:`ref-classes-buildhistory` class sets the variable
- as follows::
+ as follows:
+
+ .. code-block:: bitbake
BUILDHISTORY_PUSH_REPO ?= ""
@@ -1586,7 +1686,9 @@ system and gives an overview of their function and contents.
``bitbake.conf`` file.
As an example, the following override allows you to install extra
- files, but only when building for the target::
+ files, but only when building for the target:
+
+ .. code-block:: bitbake
do_install:append:class-target() {
install my-extra-file ${D}${sysconfdir}
@@ -1594,7 +1696,9 @@ system and gives an overview of their function and contents.
Here is an example where ``FOO`` is set to
"native" when building for the build host, and to "other" when not
- building for the build host::
+ building for the build host:
+
+ .. code-block:: bitbake
FOO:class-native = "native"
FOO = "other"
@@ -1711,7 +1815,9 @@ system and gives an overview of their function and contents.
To add a new feature item pointing to a wildcard, use a variable flag
to specify the feature item name and use the value to specify the
- wildcard. Here is an example::
+ wildcard. Here is an example:
+
+ .. code-block:: bitbake
COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
@@ -1748,7 +1854,9 @@ system and gives an overview of their function and contents.
To use the :term:`CONFFILES` variable, provide a package name override
that identifies the resulting package. Then, provide a
- space-separated list of files. Here is an example::
+ space-separated list of files. Here is an example:
+
+ .. code-block:: bitbake
CONFFILES:${PN} += "${sysconfdir}/file1 \
${sysconfdir}/file2 ${sysconfdir}/file3"
@@ -1803,7 +1911,9 @@ system and gives an overview of their function and contents.
When using the :ref:`ref-classes-autotools` class, the
:term:`CONFIGURE_SCRIPT` variable stores the location of the ``configure``
script for the Autotools build system. The default definition for this
- variable is::
+ variable is:
+
+ .. code-block:: bitbake
CONFIGURE_SCRIPT ?= "${AUTOTOOLS_SCRIPT_PATH}/configure"
@@ -1865,7 +1975,9 @@ system and gives an overview of their function and contents.
- Checksums for the image
An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types`
- class is::
+ class is:
+
+ .. code-block:: bitbake
CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}"
@@ -2038,14 +2150,18 @@ system and gives an overview of their function and contents.
:term:`CVE_CHECK_STATUSMAP`
Mapping variable for all possible reasons of :term:`CVE_STATUS`:
``Patched``, ``Unpatched`` and ``Ignored``.
- See :oecore_path:`meta/conf/cve-check-map.conf` for more details::
+ See :oecore_path:`meta/conf/cve-check-map.conf` for more details:
+
+ .. code-block:: bitbake
CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored"
:term:`CVE_CHECK_VEX_JUSTIFICATION`
Mapping variable for :term:`CVE_STATUS` reasons
(for example ``not-applicable-platform``) to :ref:`ref-classes-vex`
- justifications. Should be set as follows::
+ justifications. Should be set as follows:
+
+ .. code-block:: bitbake
CVE_CHECK_VEX_JUSTIFICATION[not-applicable-config] = "vulnerableCodeNotPresent"
@@ -2059,14 +2175,18 @@ system and gives an overview of their function and contents.
database or matches with multiple entries in the database, the default
value needs to be changed.
- Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`::
+ Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`:
+
+ .. code-block:: bitbake
CVE_PRODUCT = "oracle_berkeley_db berkeley_db"
Sometimes the product name is not specific enough, for example
"tar" has been matching CVEs for the GNU ``tar`` package and also
the ``node-tar`` node.js extension. To avoid this problem, use the
- vendor name as a prefix. The syntax for this is::
+ vendor name as a prefix. The syntax for this is:
+
+ .. code-block:: bitbake
CVE_PRODUCT = "vendor:package"
@@ -2076,7 +2196,9 @@ system and gives an overview of their function and contents.
:term:`CVE_STATUS`
The CVE ID which is patched or should be ignored. Here is
- an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
+ an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`:
+
+ .. code-block:: bitbake
CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"
@@ -2087,7 +2209,9 @@ system and gives an overview of their function and contents.
:term:`CVE_STATUS_GROUPS`
If there are many CVEs with the same status and reason, they can by simplified by using this
- variable instead of many similar lines with :term:`CVE_STATUS`::
+ variable instead of many similar lines with :term:`CVE_STATUS`:
+
+ .. code-block:: bitbake
CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED"
@@ -2106,7 +2230,9 @@ system and gives an overview of their function and contents.
which do not map to upstream software component release versions and the versions
used in the CVE database, then this variable can be used to set the
version number for :ref:`ref-classes-vex` or
- :ref:`ref-classes-create-spdx`. Example::
+ :ref:`ref-classes-create-spdx`. Example:
+
+ .. code-block:: bitbake
CVE_VERSION = "2.39"
@@ -2160,7 +2286,9 @@ system and gives an overview of their function and contents.
which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a
particular package should not be renamed according to Debian library
package naming. You must use the package name as an override when you
- set this variable. Here is an example from the ``fontconfig`` recipe::
+ set this variable. Here is an example from the ``fontconfig`` recipe:
+
+ .. code-block:: bitbake
DEBIAN_NOAUTONAME:fontconfig-utils = "1"
@@ -2170,7 +2298,9 @@ system and gives an overview of their function and contents.
the library name for an individual package. Overriding the library
name in these cases is rare. You must use the package name as an
override when you set this variable. Here is an example from the
- ``dbus`` recipe::
+ ``dbus`` recipe:
+
+ .. code-block:: bitbake
DEBIANNAME:${PN} = "dbus-1"
@@ -2239,7 +2369,9 @@ system and gives an overview of their function and contents.
needed by the recipe at build time.
As an example, consider a recipe ``foo`` that contains the following
- assignment::
+ assignment:
+
+ .. code-block:: bitbake
DEPENDS = "bar"
@@ -2262,7 +2394,9 @@ system and gives an overview of their function and contents.
As another example, :term:`DEPENDS` can also be used to add utilities
that run on the build machine during the build. For example, a recipe
that makes use of a code generator built by the recipe ``codegen``
- might have the following::
+ might have the following:
+
+ .. code-block:: bitbake
DEPENDS = "codegen-native"
@@ -2331,7 +2465,9 @@ system and gives an overview of their function and contents.
The BitBake configuration file initially defines the
:term:`DEPLOY_DIR_DEB` variable as a sub-folder of
- :term:`DEPLOY_DIR`::
+ :term:`DEPLOY_DIR`:
+
+ .. code-block:: bitbake
DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
@@ -2371,7 +2507,9 @@ system and gives an overview of their function and contents.
":ref:`ref-classes-package_ipk`".
The BitBake configuration file initially defines this variable as a
- sub-folder of :term:`DEPLOY_DIR`::
+ sub-folder of :term:`DEPLOY_DIR`:
+
+ .. code-block:: bitbake
DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
@@ -2389,7 +2527,9 @@ system and gives an overview of their function and contents.
":ref:`ref-classes-package_rpm`".
The BitBake configuration file initially defines this variable as a
- sub-folder of :term:`DEPLOY_DIR`::
+ sub-folder of :term:`DEPLOY_DIR`:
+
+ .. code-block:: bitbake
DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
@@ -2404,7 +2544,9 @@ system and gives an overview of their function and contents.
:term:`DEPLOYDIR`
When inheriting the :ref:`ref-classes-deploy` class, the
:term:`DEPLOYDIR` points to a temporary work area for deployed files that
- is set in the :ref:`ref-classes-deploy` class as follows::
+ is set in the :ref:`ref-classes-deploy` class as follows:
+
+ .. code-block:: bitbake
DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
@@ -2453,7 +2595,9 @@ system and gives an overview of their function and contents.
:yocto_git:`meta-poky </meta-yocto/tree/meta-poky>`.
Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as
- follows::
+ follows:
+
+ .. code-block:: bitbake
DISTRO = "poky"
@@ -2554,7 +2698,9 @@ system and gives an overview of their function and contents.
when they are provided by the :term:`DISTRO_FEATURES_DEFAULTS` variable.
You can also opt out of all default features by setting
- :term:`DISTRO_FEATURES_OPTED_OUT` to ``*``::
+ :term:`DISTRO_FEATURES_OPTED_OUT` to ``*``:
+
+ .. code-block:: bitbake
DISTRO_FEATURES_OPTED_OUT = "*"
@@ -2572,7 +2718,9 @@ system and gives an overview of their function and contents.
of :yocto_git:`meta-poky </meta-yocto/tree/meta-poky>`.
Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set
- as follows::
+ as follows:
+
+ .. code-block:: bitbake
DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
@@ -2603,7 +2751,9 @@ system and gives an overview of their function and contents.
:term:`OVERRIDES`.
Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf
- </meta-yocto/tree/meta-poky/conf/distro/poky-tiny.conf>`::
+ </meta-yocto/tree/meta-poky/conf/distro/poky-tiny.conf>`:
+
+ .. code-block:: bitbake
DISTROOVERRIDES = "poky:poky-tiny"
@@ -2711,7 +2861,9 @@ system and gives an overview of their function and contents.
You can set :term:`ERR_REPORT_DIR` to the path you want the error
reporting tool to store the debug files as follows in your
- ``local.conf`` file::
+ ``local.conf`` file:
+
+ .. code-block:: bitbake
ERR_REPORT_DIR = "path"
@@ -2726,7 +2878,9 @@ system and gives an overview of their function and contents.
A list of classes to remove from the :term:`INHERIT`
value globally within the extensible SDK configuration. The
:ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
- default value::
+ default value:
+
+ .. code-block:: bitbake
ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory"
@@ -2801,7 +2955,9 @@ system and gives an overview of their function and contents.
package's particular libraries only and not the whole package.
Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a
- particular package::
+ particular package:
+
+ .. code-block:: bitbake
EXCLUDE_FROM_SHLIBS = "1"
@@ -2835,7 +2991,9 @@ system and gives an overview of their function and contents.
The full package version specification as it appears on the final
packages produced by a recipe. The variable's value is normally used
to fix a runtime dependency to the exact same version of another
- package in the same recipe::
+ package in the same recipe:
+
+ .. code-block:: bitbake
RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
@@ -2948,7 +3106,9 @@ system and gives an overview of their function and contents.
Specifies additional options for the image creation command that has
been specified in :term:`IMAGE_CMD`. When setting
this variable, use an override for the associated image type. Here is
- an example::
+ an example:
+
+ .. code-block:: bitbake
EXTRA_IMAGECMD:ext3 ?= "-i 4096"
@@ -2992,7 +3152,9 @@ system and gives an overview of their function and contents.
In addition to standard Meson options, such options correspond to
`Meson build options <https://mesonbuild.com/Build-options.html>`__
defined in the ``meson_options.txt`` file in the sources to build.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled"
@@ -3034,7 +3196,9 @@ system and gives an overview of their function and contents.
printf "%q" $(mkpasswd -m sha256crypt tester01)
- The resulting hash is set to a variable and used in ``useradd`` command parameters::
+ The resulting hash is set to a variable and used in ``useradd`` command parameters:
+
+ .. code-block:: bitbake
inherit extrausers
PASSWD = "\$X\$ABC123\$A-Long-Hash"
@@ -3043,7 +3207,9 @@ system and gives an overview of their function and contents.
useradd -p '${PASSWD}' tester-sue; \
"
- Finally, here is an example that sets the root password::
+ Finally, here is an example that sets the root password:
+
+ .. code-block:: bitbake
inherit extrausers
EXTRA_USERS_PARAMS = "\
@@ -3059,7 +3225,9 @@ system and gives an overview of their function and contents.
Additionally there is a special ``passwd-expire`` command that will
cause the password for a user to be expired and thus force changing it
- on first login, for example::
+ on first login, for example:
+
+ .. code-block:: bitbake
EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
@@ -3074,7 +3242,9 @@ system and gives an overview of their function and contents.
added to the beginning of the environment variable ``PATH``. As an
example, the following prepends
"${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
- ``PATH``::
+ ``PATH``:
+
+ .. code-block:: bitbake
EXTRANATIVEPATH = "foo bar"
@@ -3103,7 +3273,9 @@ system and gives an overview of their function and contents.
Defines one or more packages to include in an image when a specific
item is included in :term:`IMAGE_FEATURES`.
When setting the value, :term:`FEATURE_PACKAGES` should have the name of
- the feature item as an override. Here is an example::
+ the feature item as an override. Here is an example:
+
+ .. code-block:: bitbake
FEATURE_PACKAGES_widget = "package1 package2"
@@ -3123,7 +3295,9 @@ system and gives an overview of their function and contents.
OPKG to support runtime package management of IPK packages. You set
this variable in your ``local.conf`` file.
- Consider the following example::
+ Consider the following example:
+
+ .. code-block:: bitbake
FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
@@ -3148,7 +3322,9 @@ system and gives an overview of their function and contents.
To use the :term:`FILES` variable, provide a package name override that
identifies the resulting package. Then, provide a space-separated
list of files or paths that identify the files you want included as
- part of the resulting package. Here is an example::
+ part of the resulting package. Here is an example:
+
+ .. code-block:: bitbake
FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
@@ -3183,7 +3359,9 @@ system and gives an overview of their function and contents.
symbolic link (symlink) for shared libraries on the target platform.
The following statement from the ``bitbake.conf`` shows how it is
- set::
+ set:
+
+ .. code-block:: bitbake
FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
@@ -3196,7 +3374,9 @@ system and gives an overview of their function and contents.
Best practices dictate that you accomplish this by using
:term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you
- prepend paths as follows::
+ prepend paths as follows:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
@@ -3218,7 +3398,9 @@ system and gives an overview of their function and contents.
are directing BitBake to extend the path by prepending directories
to the search path.
- Here is another common use::
+ Here is another common use:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
@@ -3226,13 +3408,17 @@ system and gives an overview of their function and contents.
:term:`FILESPATH` variable to include a directory named ``files`` that is
in the same directory as the corresponding append file.
- This next example specifically adds three paths::
+ This next example specifically adds three paths:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"
A final example shows how you can extend the search path and include
a :term:`MACHINE`-specific override, which is useful
- in a BSP layer::
+ in a BSP layer:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"
@@ -3262,7 +3448,9 @@ system and gives an overview of their function and contents.
":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
section of the BitBake User Manual.
- By default, the :term:`FILESOVERRIDES` variable is defined as::
+ By default, the :term:`FILESOVERRIDES` variable is defined as:
+
+ .. code-block:: bitbake
FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
@@ -3283,7 +3471,9 @@ system and gives an overview of their function and contents.
The default value for the :term:`FILESPATH` variable is defined in the
:ref:`ref-classes-base` class found in ``meta/classes-global`` in
- :term:`OpenEmbedded-Core (OE-Core)`::
+ :term:`OpenEmbedded-Core (OE-Core)`:
+
+ .. code-block:: bitbake
FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
"${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
@@ -3379,7 +3569,9 @@ system and gives an overview of their function and contents.
set this value to "2", as two 32 bit values (cells) will be needed
to represent such addresses.
- Here is an example setting "0x400000000" as a load address::
+ Here is an example setting "0x400000000" as a load address:
+
+ .. code-block:: bitbake
FIT_ADDRESS_CELLS = "2"
UBOOT_LOADADDRESS = "0x04 0x00000000"
@@ -3416,7 +3608,9 @@ system and gives an overview of their function and contents.
bootloader configurations or just need an alias configuration name for
some other reason.
- For example::
+ For example:
+
+ .. code-block:: bitbake
FIT_CONF_MAPPINGS = "\
dtb-extra-conf:am335x-bonegreen:bonegreen \
@@ -3440,7 +3634,9 @@ system and gives an overview of their function and contents.
:term:`FIT_DESC`
Specifies the description string encoded into a FIT image. The
default value is set by the :ref:`ref-classes-kernel-fit-image` class as
- follows::
+ follows:
+
+ .. code-block:: bitbake
FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
@@ -3531,7 +3727,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_ARCH[foo] = "arm"
@@ -3544,7 +3742,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_COMPRESSION[foo] = "gzip"
@@ -3562,7 +3762,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_DESCRIPTION[foo] = "Foo firmware binary"
@@ -3575,7 +3777,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_ENTRYPOINT[foo] = "0x80234000"
@@ -3588,7 +3792,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_FILENAME[foo] = "foo-firmware.bin"
@@ -3600,7 +3806,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_LOADADDRESS[foo] = "0x80230000"
@@ -3613,7 +3821,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_OS[foo] = "linux"
@@ -3626,7 +3836,9 @@ system and gives an overview of their function and contents.
This variable cannot be used directly, but only defining flags on it.
- Example::
+ Example:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "foo"
FIT_LOADABLE_TYPE[foo] = "firmware"
@@ -3649,7 +3861,9 @@ system and gives an overview of their function and contents.
For example, the following configuration adds as loadables a TF-A BL31
firmware and a (compressed) TEE firmware, to be loaded respectively at
- 0x204E0000 and 0x96000000::
+ 0x204E0000 and 0x96000000:
+
+ .. code-block:: bitbake
FIT_LOADABLES = "atf tee"
@@ -3709,7 +3923,9 @@ system and gives an overview of their function and contents.
``mkimage`` during FIT image generation, providing flexibility for platforms
that require additional ``mkimage`` arguments beyond the defaults.
- For example::
+ For example:
+
+ .. code-block:: bitbake
FIT_MKIMAGE_EXTRA_OPTS = "-B 8 -E"
@@ -3775,7 +3991,9 @@ system and gives an overview of their function and contents.
Example:
- - Add a script ``boot.cmd`` to the Linux kernel recipe::
+ - Add a script ``boot.cmd`` to the Linux kernel recipe:
+
+ .. code-block:: bitbake
FIT_UBOOT_ENV = "boot.cmd"
SRC_URI += "file://${FIT_UBOOT_ENV}"
@@ -3820,14 +4038,18 @@ system and gives an overview of their function and contents.
Programming (ROP) attacks much more difficult to execute.
By default the ``security_flags.inc`` file enables PIE by setting the
- variable as follows::
+ variable as follows:
+
+ .. code-block:: bitbake
GCCPIE ?= "--enable-default-pie"
:term:`GCCVERSION`
Specifies the default version of the GNU C Compiler (GCC) used for
compilation. By default, :term:`GCCVERSION` is set to "8.x" in the
- ``meta/conf/distro/include/tcmode-default.inc`` include file::
+ ``meta/conf/distro/include/tcmode-default.inc`` include file:
+
+ .. code-block:: bitbake
GCCVERSION ?= "8.%"
@@ -3851,7 +4073,9 @@ system and gives an overview of their function and contents.
:term:`GITHUB_BASE_URI`
When inheriting the :ref:`ref-classes-github-releases`
class, specifies the base URL for fetching releases for the github
- project you wish to fetch sources from. The default value is as follows::
+ project you wish to fetch sources from. The default value is as follows:
+
+ .. code-block:: bitbake
GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/"
@@ -3865,7 +4089,9 @@ system and gives an overview of their function and contents.
:term:`IMAGE_LINGUAS` appropriately.
You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file.
- By default, all locales are generated::
+ By default, all locales are generated:
+
+ .. code-block:: bitbake
GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
@@ -3879,7 +4105,9 @@ system and gives an overview of their function and contents.
Here is an example setting from the
:oe_git:`go-helloworld_0.1.bb </openembedded-core/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>`
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
GO_IMPORT = "golang.org/x/example"
@@ -3891,14 +4119,18 @@ system and gives an overview of their function and contents.
Here is an example setting from the
:oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>`
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
GO_INSTALL = "\
${GO_IMPORT}/cmd/crucible \
${GO_IMPORT}/cmd/habtool \
"
- By default, :term:`GO_INSTALL` is defined as::
+ By default, :term:`GO_INSTALL` is defined as:
+
+ .. code-block:: bitbake
GO_INSTALL ?= "${GO_IMPORT}/..."
@@ -3942,7 +4174,9 @@ system and gives an overview of their function and contents.
passed to the ``groupadd`` command if you wish to add a group to the
system when the package is installed.
- Here is an example from the ``dbus`` recipe::
+ Here is an example from the ``dbus`` recipe:
+
+ .. code-block:: bitbake
GROUPADD_PARAM:${PN} = "-r netdev"
@@ -3950,7 +4184,9 @@ system and gives an overview of their function and contents.
groups' parameters with a semicolon.
Here is an example adding multiple groups from the ``useradd-example.bb``
- file in the ``meta-skeleton`` layer::
+ file in the ``meta-skeleton`` layer:
+
+ .. code-block:: bitbake
GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2"
@@ -4137,7 +4373,9 @@ system and gives an overview of their function and contents.
installed name, separate it from the original name with a semi-colon
(;). Source files need to be located in
:term:`DEPLOY_DIR_IMAGE`. Here are two
- examples::
+ examples:
+
+ .. code-block:: bitbake
IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
@@ -4146,7 +4384,9 @@ system and gives an overview of their function and contents.
this case, the destination file must have the same name as the base
name of the source file path. To install files into a directory
within the target location, pass its name after a semi-colon (;).
- Here are two examples::
+ Here are two examples:
+
+ .. code-block:: bitbake
IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
@@ -4185,7 +4425,9 @@ system and gives an overview of their function and contents.
type, which corresponds to the value set in
:term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
``btrfs``, and so forth). When setting this variable, you should use
- an override for the associated type. Here is an example::
+ an override for the associated type. Here is an example:
+
+ .. code-block:: bitbake
IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
--output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
@@ -4233,7 +4475,9 @@ system and gives an overview of their function and contents.
installed name, separate it from the original name with a semi-colon
(;). Source files need to be located in
:term:`DEPLOY_DIR_IMAGE`. Here are two
- examples::
+ examples:
+
+ .. code-block:: bitbake
IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
@@ -4242,7 +4486,9 @@ system and gives an overview of their function and contents.
this case, the destination file must have the same name as the base
name of the source file path. To install files into a directory
within the target location, pass its name after a semi-colon (;).
- Here are two examples::
+ Here are two examples:
+
+ .. code-block:: bitbake
IMAGE_EFI_BOOT_FILES = "boot/loader/*"
IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
@@ -4267,7 +4513,9 @@ system and gives an overview of their function and contents.
installed name, separate it from the original name with a semi-colon
(;). Source files need to be located in
:term:`DEPLOY_DIR_IMAGE`. Here is an
- example::
+ example:
+
+ .. code-block:: bitbake
IMAGE_EXTRA_PARTITION_FILES = "foobar file.conf;config"
@@ -4280,7 +4528,9 @@ system and gives an overview of their function and contents.
The destination file will have the same name as the base
name of the source file path. To install files into a renamed directory
within the target location, pass its name after a semi-colon (;).
- Here are two examples::
+ Here are two examples:
+
+ .. code-block:: bitbake
IMAGE_EXTRA_PARTITION_FILES = "foo/*"
IMAGE_EXTRA_PARTITION_FILES = "foo/*;bar/"
@@ -4299,7 +4549,9 @@ system and gives an overview of their function and contents.
part --source extra_partition --fstype=ext4 --uuid e7d0824e-cda3-4bed-9f54-9ef5312d105d
part --source extra_partition --fstype=ext4 --part-name config
- And the following configuration::
+ And the following configuration:
+
+ .. code-block:: bitbake
IMAGE_EXTRA_PARTITION_FILES_label-foo = "foo/*"
IMAGE_EXTRA_PARTITION_FILES_uuid-e7d0824e-cda3-4bed-9f54-9ef5312d105d = "foo/*;bar/"
@@ -4345,7 +4597,9 @@ system and gives an overview of their function and contents.
Specifies the formats the OpenEmbedded build system uses during the
build when creating the root filesystem. For example, setting
:term:`IMAGE_FSTYPES` as follows causes the build system to create root
- filesystems using two formats: ``.ext3`` and ``.tar.bz2``::
+ filesystems using two formats: ``.ext3`` and ``.tar.bz2``:
+
+ .. code-block:: bitbake
IMAGE_FSTYPES = "ext3 tar.bz2"
@@ -4390,7 +4644,9 @@ system and gives an overview of their function and contents.
them into auto-generated entries in :term:`IMAGE_INSTALL` in addition
to its default contents.
- When you use this variable, it is best to use it as follows::
+ When you use this variable, it is best to use it as follows:
+
+ .. code-block:: bitbake
IMAGE_INSTALL:append = " package-name"
@@ -4433,7 +4689,9 @@ system and gives an overview of their function and contents.
into separate packages. Setting the :term:`IMAGE_LINGUAS` variable
ensures that any locale packages that correspond to packages already
selected for installation into the image are also installed. Here is
- an example::
+ an example:
+
+ .. code-block:: bitbake
IMAGE_LINGUAS = "pt-br de-de"
@@ -4452,7 +4710,9 @@ system and gives an overview of their function and contents.
The name of the output image symlink (which does not include
the version part as :term:`IMAGE_NAME` does). The default value
is derived using the :term:`IMAGE_BASENAME` and
- :term:`IMAGE_MACHINE_SUFFIX` variables::
+ :term:`IMAGE_MACHINE_SUFFIX` variables:
+
+ .. code-block:: bitbake
IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}"
@@ -4460,21 +4720,27 @@ system and gives an overview of their function and contents.
It is possible to set this to "" to disable symlink creation,
however, you also need to set :term:`IMAGE_NAME` to still have
- a reasonable value e.g.::
+ a reasonable value e.g.:
+
+ .. code-block:: bitbake
IMAGE_LINK_NAME = ""
IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
:term:`IMAGE_MACHINE_SUFFIX`
Specifies the by default machine-specific suffix for image file names
- (before the extension). The default value is set as follows::
+ (before the extension). The default value is set as follows:
+
+ .. code-block:: bitbake
IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}"
The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE`
subdirectory, so you may find it unnecessary to also include this suffix
in the name of every image file. If you prefer to remove the suffix you
- can set this variable to an empty string::
+ can set this variable to an empty string:
+
+ .. code-block:: bitbake
IMAGE_MACHINE_SUFFIX = ""
@@ -4488,7 +4754,9 @@ system and gives an overview of their function and contents.
packagename packagearch version
The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest
- file as follows::
+ file as follows:
+
+ .. code-block:: bitbake
IMAGE_MANIFEST = "${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"
@@ -4501,7 +4769,9 @@ system and gives an overview of their function and contents.
:term:`IMAGE_NAME`
The name of the output image files minus the extension. By default
this variable is set using the :term:`IMAGE_LINK_NAME`, and
- :term:`IMAGE_VERSION_SUFFIX` variables::
+ :term:`IMAGE_VERSION_SUFFIX` variables:
+
+ .. code-block:: bitbake
IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}"
@@ -4517,7 +4787,9 @@ system and gives an overview of their function and contents.
:ref:`ref-classes-core-image` class, the :term:`IMAGE_OUTPUT_MANIFEST`
points to a manifest ``json`` file that lists what images were created by
various image creation tasks (as defined by the :term:`IMAGE_FSTYPES`
- variable). It is set in the :ref:`ref-classes-image` class as follows::
+ variable). It is set in the :ref:`ref-classes-image` class as follows:
+
+ .. code-block:: bitbake
IMAGE_OUTPUT_MANIFEST = "${IMAGE_OUTPUT_MANIFEST_DIR}/manifest.json"
@@ -4527,7 +4799,9 @@ system and gives an overview of their function and contents.
a directory that stores a manifest ``json`` file that lists what
images were created by various image creation tasks (as defined by the
:term:`IMAGE_FSTYPES` variable). It is set in the :ref:`ref-classes-image`
- class as follows::
+ class as follows:
+
+ .. code-block:: bitbake
IMAGE_OUTPUT_MANIFEST_DIR = "${WORKDIR}/deploy-image-output-manifest"
@@ -4551,7 +4825,9 @@ system and gives an overview of their function and contents.
to boot and allows for basic post installs while still leaving a
small amount of free disk space. If 30% free space is inadequate, you
can increase the default value. For example, the following setting
- gives you 50% free space added to the image::
+ gives you 50% free space added to the image:
+
+ .. code-block:: bitbake
IMAGE_OVERHEAD_FACTOR = "1.5"
@@ -4584,7 +4860,9 @@ system and gives an overview of their function and contents.
:term:`IMAGE_POSTPROCESS_COMMAND`
Specifies a list of functions to call once the OpenEmbedded build
system creates the final image output files. You can specify
- functions separated by spaces::
+ functions separated by spaces:
+
+ .. code-block:: bitbake
IMAGE_POSTPROCESS_COMMAND += "function"
@@ -4597,7 +4875,9 @@ system and gives an overview of their function and contents.
:term:`IMAGE_PREPROCESS_COMMAND`
Specifies a list of functions to call before the OpenEmbedded build
system creates the final image output files. You can specify
- functions separated by spaces::
+ functions separated by spaces:
+
+ .. code-block:: bitbake
IMAGE_PREPROCESS_COMMAND += "function"
@@ -4628,12 +4908,16 @@ system and gives an overview of their function and contents.
This variable is particularly useful when you want to ensure that a
specific amount of free disk space is available on a device after an
image is installed and running. For example, to be sure 5 Gbytes of
- free disk space is available, set the variable as follows::
+ free disk space is available, set the variable as follows:
+
+ .. code-block:: bitbake
IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
For example, the Yocto Project Build Appliance specifically requests
- 40 Gbytes of extra space with the line::
+ 40 Gbytes of extra space with the line:
+
+ .. code-block:: bitbake
IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
@@ -4693,7 +4977,9 @@ system and gives an overview of their function and contents.
:term:`IMAGE_TYPEDEP`
Specifies a dependency from one image type on another. Here is an
- example from the :ref:`ref-classes-image-live` class::
+ example from the :ref:`ref-classes-image-live` class:
+
+ .. code-block:: bitbake
IMAGE_TYPEDEP:live = "ext3"
@@ -4766,7 +5052,9 @@ system and gives an overview of their function and contents.
When inheriting the :ref:`ref-classes-image` class directly or
through the :ref:`ref-classes-core-image` class, the
:term:`IMGDEPLOYDIR` points to a temporary work area for deployed files
- that is set in the ``image`` class as follows::
+ that is set in the ``image`` class as follows:
+
+ .. code-block:: bitbake
IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
@@ -4780,7 +5068,9 @@ system and gives an overview of their function and contents.
points to a temporary area that stores manifest ``json`` files, that list
what images were created by various images creation tasks (as defined by
the :term:`IMAGE_FSTYPES` variable). It is set in the
- :ref:`ref-classes-image` class as follows::
+ :ref:`ref-classes-image` class as follows:
+
+ .. code-block:: bitbake
IMGMANIFESTDIR = "${WORKDIR}/image-task-manifest"
@@ -4811,7 +5101,9 @@ system and gives an overview of their function and contents.
.. note::
This functionality is only regularly tested using the following
- setting::
+ setting:
+
+ .. code-block:: bitbake
INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*"
@@ -4824,7 +5116,9 @@ system and gives an overview of their function and contents.
Specifies a space-separated list of package and license pairs that
are allowed to be used even if the license is specified in
:term:`INCOMPATIBLE_LICENSE`. The package and license pairs are
- separated using a colon. Example::
+ separated using a colon. Example:
+
+ .. code-block:: bitbake
INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only"
@@ -4848,7 +5142,9 @@ system and gives an overview of their function and contents.
``classes-global/`` or ``classes/`` subdirectories.
The default value of the variable is set as follows in the
- ``meta/conf/distro/defaultsetup.conf`` file::
+ ``meta/conf/distro/defaultsetup.conf`` file:
+
+ .. code-block:: bitbake
INHERIT_DISTRO ?= "debian devshell sstate license remove-libtool create-spdx"
@@ -4862,7 +5158,9 @@ system and gives an overview of their function and contents.
support the ``autotools`` build process.
To prevent the build system from adding these dependencies automatically,
- set the :term:`INHIBIT_AUTOTOOLS_DEPS` variable as follows::
+ set the :term:`INHIBIT_AUTOTOOLS_DEPS` variable as follows:
+
+ .. code-block:: bitbake
INHIBIT_AUTOTOOLS_DEPS = "1"
@@ -4888,7 +5186,9 @@ system and gives an overview of their function and contents.
to :term:`DEPENDS` to support the ``rust`` build process.
To prevent the build system from adding these dependencies automatically,
- set the :term:`INHIBIT_DEFAULT_RUST_DEPS` variable as follows::
+ set the :term:`INHIBIT_DEFAULT_RUST_DEPS` variable as follows:
+
+ .. code-block:: bitbake
INHIBIT_DEFAULT_RUST_DEPS = "1"
@@ -4907,7 +5207,9 @@ system and gives an overview of their function and contents.
To prevent the build system from splitting out debug information
during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as
- follows::
+ follows:
+
+ .. code-block:: bitbake
INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
@@ -4953,7 +5255,9 @@ system and gives an overview of their function and contents.
traditional SysV init system.
To prevent the build system from adding these scripts and configurations
- automatically, set the :term:`INHIBIT_UPDATERCD_BBCLASS` variable as follows::
+ automatically, set the :term:`INHIBIT_UPDATERCD_BBCLASS` variable as follows:
+
+ .. code-block:: bitbake
INHIBIT_UPDATERCD_BBCLASS = "1"
@@ -5078,12 +5382,16 @@ system and gives an overview of their function and contents.
Setting the variable to "1" in a configuration file causes the
OpenEmbedded build system to generate a kernel image with the
- :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within::
+ :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within:
+
+ .. code-block:: bitbake
INITRAMFS_IMAGE_BUNDLE = "1"
By default, the :ref:`ref-classes-kernel` class sets this variable to a
- null string as follows::
+ null string as follows:
+
+ .. code-block:: bitbake
INITRAMFS_IMAGE_BUNDLE ?= ""
@@ -5114,13 +5422,17 @@ system and gives an overview of their function and contents.
:term:`INITRAMFS_LINK_NAME`
The link name of the initial RAM filesystem image. This variable is
set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
- follows::
+ follows:
+
+ .. code-block:: bitbake
INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
The value of the
``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
- file, has the following value::
+ file, has the following value:
+
+ .. code-block:: bitbake
KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
@@ -5155,7 +5467,9 @@ system and gives an overview of their function and contents.
:term:`INITRAMFS_NAME`
The base name of the initial RAM filesystem image. This variable is
set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
- follows::
+ follows:
+
+ .. code-block:: bitbake
INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
@@ -5194,7 +5508,9 @@ system and gives an overview of their function and contents.
variable.
:term:`INITSCRIPT_PARAMS`
- Specifies the options to pass to ``update-rc.d``. Here is an example::
+ Specifies the options to pass to ``update-rc.d``. Here is an example:
+
+ .. code-block:: bitbake
INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
@@ -5213,7 +5529,9 @@ system and gives an overview of their function and contents.
recipe. For example, to skip the check for symbolic link ``.so``
files in the main package of a recipe, add the following to the
recipe. The package name override must be used, which in this example
- is ``${PN}``::
+ is ``${PN}``:
+
+ .. code-block:: bitbake
INSANE_SKIP:${PN} += "dev-so"
@@ -5255,7 +5573,9 @@ system and gives an overview of their function and contents.
kernel's append file. For example, if you are using the
``linux-yocto_4.12`` kernel, the kernel recipe file is the
``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH`
- is set as follows in that kernel recipe file::
+ is set as follows in that kernel recipe file:
+
+ .. code-block:: bitbake
KBRANCH ?= "standard/base"
@@ -5267,7 +5587,9 @@ system and gives an overview of their function and contents.
Beaglebone and generic versions of both 32 and 64-bit IA
machines (``meta-yocto-bsp``) is named
``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend``.
- Here are the related statements from that append file::
+ Here are the related statements from that append file:
+
+ .. code-block:: bitbake
KBRANCH:genericx86 = "v6.1/standard/base"
KBRANCH:genericx86-64 = "v6.1/standard/base"
@@ -5296,11 +5618,15 @@ system and gives an overview of their function and contents.
KBUILD_DEFCONFIG:<machine> ?= "defconfig_file"
Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses
- a ``defconfig`` file named "bcm2709_defconfig"::
+ a ``defconfig`` file named "bcm2709_defconfig":
+
+ .. code-block:: bitbake
KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig"
- As an alternative, you can use the following within your append file::
+ As an alternative, you can use the following within your append file:
+
+ .. code-block:: bitbake
KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file"
@@ -5371,7 +5697,9 @@ system and gives an overview of their function and contents.
:term:`KCONFIG_MODE`
When used with the :ref:`ref-classes-kernel-yocto`
class, specifies the kernel configuration values to use for options
- not specified in the provided ``defconfig`` file. Valid options are::
+ not specified in the provided ``defconfig`` file. Valid options are:
+
+ .. code-block:: bitbake
KCONFIG_MODE = "alldefconfig"
KCONFIG_MODE = "allnoconfig"
@@ -5394,7 +5722,9 @@ system and gives an overview of their function and contents.
generated using the
:ref:`ref-tasks-savedefconfig`
task and placed into the Linux kernel ``${WORKDIR}`` through your
- meta-layer. Explicitely set :term:`KCONFIG_MODE`::
+ meta-layer. Explicitely set :term:`KCONFIG_MODE`:
+
+ .. code-block:: bitbake
KCONFIG_MODE = "alldefconfig"
@@ -5410,7 +5740,9 @@ system and gives an overview of their function and contents.
The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the
``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the
- following default value::
+ following default value:
+
+ .. code-block:: bitbake
KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
@@ -5443,7 +5775,9 @@ system and gives an overview of their function and contents.
building and configuring the kernel stops with an error.
You can turn these errors into warnings by setting the
- following in ``conf/local.conf``::
+ following in ``conf/local.conf``:
+
+ .. code-block:: bitbake
KERNEL_DANGLING_FEATURES_WARN_ONLY = "1"
@@ -5487,13 +5821,17 @@ system and gives an overview of their function and contents.
:term:`KERNEL_DTB_LINK_NAME`
The link name of the kernel device tree binary (DTB). This variable
is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
- follows::
+ follows:
+
+ .. code-block:: bitbake
KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
The
value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
- the same file, has the following value::
+ the same file, has the following value:
+
+ .. code-block:: bitbake
KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
@@ -5503,7 +5841,9 @@ system and gives an overview of their function and contents.
:term:`KERNEL_DTB_NAME`
The base name of the kernel device tree binary (DTB). This variable
is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
- follows::
+ follows:
+
+ .. code-block:: bitbake
KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
@@ -5556,7 +5896,9 @@ system and gives an overview of their function and contents.
For example, the following example from the ``linux-yocto-rt_4.12``
kernel recipe adds "netfilter" and "taskstats" features to all BSPs
as well as "virtio" configurations to all QEMU machines. The last two
- statements add specific configurations to targeted machine types::
+ statements add specific configurations to targeted machine types:
+
+ .. code-block:: bitbake
KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
@@ -5567,13 +5909,17 @@ system and gives an overview of their function and contents.
:term:`KERNEL_FIT_LINK_NAME`
The link name of the kernel flattened image tree (FIT) image. This
variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
- file as follows::
+ file as follows:
+
+ .. code-block:: bitbake
KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
The value of the
``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
- file, has the following value::
+ file, has the following value:
+
+ .. code-block:: bitbake
KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
@@ -5583,7 +5929,9 @@ system and gives an overview of their function and contents.
:term:`KERNEL_FIT_NAME`
The base name of the kernel flattened image tree (FIT) image. This
variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
- file as follows::
+ file as follows:
+
+ .. code-block:: bitbake
KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
@@ -5591,13 +5939,17 @@ system and gives an overview of their function and contents.
:term:`KERNEL_IMAGE_LINK_NAME`
The link name for the kernel image. This variable is set in the
- ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
+ ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:
+
+ .. code-block:: bitbake
KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
The value of
the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
- file, has the following value::
+ file, has the following value:
+
+ .. code-block:: bitbake
KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
@@ -5620,7 +5972,9 @@ system and gives an overview of their function and contents.
:term:`KERNEL_IMAGE_NAME`
The base name of the kernel image. This variable is set in the
- ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
+ ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:
+
+ .. code-block:: bitbake
KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
@@ -5629,7 +5983,9 @@ system and gives an overview of their function and contents.
:term:`KERNEL_IMAGE_STRIP_EXTRA_SECTIONS`
If this variable is set, it should contain the sections to be
stripped from the ``vmlinux`` image by the kernel-related
- :ref:`ref-tasks-strip` task. As a simple example::
+ :ref:`ref-tasks-strip` task. As a simple example:
+
+ .. code-block:: bitbake
KERNEL_IMAGE_STRIP_EXTRA_SECTIONS = ".comment .note.* .debug"
@@ -5670,7 +6026,9 @@ system and gives an overview of their function and contents.
configuration file, an append file for the recipe, or the recipe
itself).
- Specify it as follows::
+ Specify it as follows:
+
+ .. code-block:: bitbake
KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"
@@ -5678,7 +6036,9 @@ system and gives an overview of their function and contents.
system to populate the ``/etc/modules-load.d/modname.conf`` file with
the list of modules to be auto-loaded on boot. The modules appear
one-per-line in the file. Here is an example of the most common use
- case::
+ case:
+
+ .. code-block:: bitbake
KERNEL_MODULE_AUTOLOAD += "module_name"
@@ -5787,7 +6147,9 @@ system and gives an overview of their function and contents.
These mappings between different names occur in the Yocto Linux
Kernel's ``meta`` branch. As an example take a look in the
- ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file::
+ ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:
+
+ .. code-block:: bitbake
LINUX_VERSION:core2-32-intel-common = "3.19.0"
COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}"
@@ -5852,7 +6214,9 @@ system and gives an overview of their function and contents.
:term:`LAYERDEPENDS`
Lists the layers, separated by spaces, on which this layer depends.
Optionally, you can specify a specific layer version for a dependency
- by adding it to the end of the layer name. Here is an example::
+ by adding it to the end of the layer name. Here is an example:
+
+ .. code-block:: bitbake
LAYERDEPENDS_mylayer = "anotherlayer (=3)"
@@ -5880,7 +6244,9 @@ system and gives an overview of their function and contents.
Optionally, you can specify a specific layer version for a
recommendation by adding the version to the end of the layer name.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
@@ -5964,7 +6330,9 @@ system and gives an overview of their function and contents.
:term:`SPDXLICENSEMAP` flag names defined in
``meta/conf/licenses.conf``.
- Here are some examples::
+ Here are some examples:
+
+ .. code-block:: bitbake
LICENSE = "LGPL-2.1-only | GPL-3.0-only"
LICENSE = "MPL-1.0 & LGPL-2.1-only"
@@ -5981,7 +6349,9 @@ system and gives an overview of their function and contents.
situations where components of the output have different licenses.
For example, a piece of software whose code is licensed under GPLv2
but has accompanying documentation licensed under the GNU Free
- Documentation License 1.2 could be specified as follows::
+ Documentation License 1.2 could be specified as follows:
+
+ .. code-block:: bitbake
LICENSE = "GFDL-1.2 & GPL-2.0-only"
LICENSE:${PN} = "GPL-2.0.only"
@@ -6042,7 +6412,9 @@ system and gives an overview of their function and contents.
the error message will be more informative, containing the specified
extra details.
- For example, a recipe with an EULA may set::
+ For example, a recipe with an EULA may set:
+
+ .. code-block:: bitbake
LICENSE_FLAGS = "FooBar-EULA"
LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula."
@@ -6058,7 +6430,9 @@ system and gives an overview of their function and contents.
OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the
directory that holds common license text used during the build. The
:term:`LICENSE_PATH` variable allows you to extend that location to other
- areas that have additional licenses::
+ areas that have additional licenses:
+
+ .. code-block:: bitbake
LICENSE_PATH += "path-to-additional-common-licenses"
@@ -6082,12 +6456,16 @@ system and gives an overview of their function and contents.
being built using the OpenEmbedded build system is based. You define
this variable in the kernel recipe. For example, the
``linux-yocto-3.4.bb`` kernel recipe found in
- ``meta/recipes-kernel/linux`` defines the variables as follows::
+ ``meta/recipes-kernel/linux`` defines the variables as follows:
+
+ .. code-block:: bitbake
LINUX_VERSION ?= "3.4.24"
The :term:`LINUX_VERSION` variable is used to define :term:`PV`
- for the recipe::
+ for the recipe:
+
+ .. code-block:: bitbake
PV = "${LINUX_VERSION}+git"
@@ -6095,7 +6473,9 @@ system and gives an overview of their function and contents.
A string extension compiled into the version string of the Linux
kernel built with the OpenEmbedded build system. You define this
variable in the kernel recipe. For example, the linux-yocto kernel
- recipes all define the variable as follows::
+ recipes all define the variable as follows:
+
+ .. code-block:: bitbake
LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"
@@ -6139,7 +6519,9 @@ system and gives an overview of their function and contents.
:term:`MACHINE` in the ``local.conf`` file found in the
:term:`Build Directory`. By default, :term:`MACHINE` is set to
"qemux86", which is an x86-based architecture machine to be emulated
- using QEMU::
+ using QEMU:
+
+ .. code-block:: bitbake
MACHINE ?= "qemux86"
@@ -6151,7 +6533,9 @@ system and gives an overview of their function and contents.
``meta/conf/machine``.
The list of machines supported by the Yocto Project as shipped
- include the following::
+ include the following:
+
+ .. code-block:: bitbake
MACHINE ?= "qemuarm"
MACHINE ?= "qemuarm64"
@@ -6196,7 +6580,9 @@ system and gives an overview of their function and contents.
As an example, suppose the machine for which you are building
requires ``example-init`` to be run during boot to initialize the
hardware. In this case, you would use the following in the machine's
- ``.conf`` configuration file::
+ ``.conf`` configuration file:
+
+ .. code-block:: bitbake
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
@@ -6227,7 +6613,9 @@ system and gives an overview of their function and contents.
"recommends" relationship so that in the latter case, the build will
not fail due to the missing package. To accomplish this, assuming the
package for the module was called ``kernel-module-ab123``, you would
- use the following in the machine's ``.conf`` configuration file::
+ use the following in the machine's ``.conf`` configuration file:
+
+ .. code-block:: bitbake
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
@@ -6263,7 +6651,9 @@ system and gives an overview of their function and contents.
exist, so it is acceptable for the build process to depend upon
finding the package. In this case, assuming the package for the
firmware was called ``wifidriver-firmware``, you would use the
- following in the ``.conf`` file for the machine::
+ following in the ``.conf`` file for the machine:
+
+ .. code-block:: bitbake
MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
@@ -6289,7 +6679,9 @@ system and gives an overview of their function and contents.
the build to succeed instead of failing as a result of the package
not being found. To accomplish this, assuming the package for the
module was called ``kernel-module-examplewifi``, you would use the
- following in the ``.conf`` file for the machine::
+ following in the ``.conf`` file for the machine:
+
+ .. code-block:: bitbake
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
@@ -6317,7 +6709,9 @@ system and gives an overview of their function and contents.
when they are provided by the :term:`MACHINE_FEATURES_DEFAULTS` variable.
You can also opt out of all default features by setting
- :term:`MACHINE_FEATURES_OPTED_OUT` to ``*``::
+ :term:`MACHINE_FEATURES_OPTED_OUT` to ``*``:
+
+ .. code-block:: bitbake
MACHINE_FEATURES_OPTED_OUT = "*"
@@ -6332,14 +6726,18 @@ system and gives an overview of their function and contents.
should apply to a machine. For example, all machines emulated in QEMU
(e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
``meta/conf/machine/include/qemu.inc`` that prepends the following
- override to :term:`MACHINEOVERRIDES`::
+ override to :term:`MACHINEOVERRIDES`:
+
+ .. code-block:: bitbake
MACHINEOVERRIDES =. "qemuall:"
This
override allows variables to be overridden for all machines emulated
in QEMU, like in the following example from the ``connman-conf``
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
SRC_URI:append:qemuall = " file://wired.config \
file://wired-setup \
@@ -6422,23 +6820,31 @@ system and gives an overview of their function and contents.
declares build-time dependencies on tasks in other recipes by using
:term:`DEPENDS`, then a dependency on "foo" will automatically get
rewritten to a dependency on "nativesdk-foo". However, dependencies like
- the following will not get rewritten automatically::
+ the following will not get rewritten automatically:
+
+ .. code-block:: bitbake
do_foo[depends] += "recipe:do_foo"
If you want such a dependency to also get transformed, you can do the
- following::
+ following:
+
+ .. code-block:: bitbake
do_foo[depends] += "${MLPREFIX}recipe:do_foo"
:term:`module_autoload`
This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD`
variable. You should replace all occurrences of :term:`module_autoload`
- with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example::
+ with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example:
+
+ .. code-block:: bitbake
module_autoload_rfcomm = "rfcomm"
- should now be replaced with::
+ should now be replaced with:
+
+ .. code-block:: bitbake
KERNEL_MODULE_AUTOLOAD += "rfcomm"
@@ -6457,7 +6863,9 @@ system and gives an overview of their function and contents.
:term:`KERNEL_MODULE_PROBECONF`
variable.
- Here is the general syntax::
+ Here is the general syntax:
+
+ .. code-block:: bitbake
module_conf_module_name = "modprobe.d-syntax"
@@ -6469,7 +6877,9 @@ system and gives an overview of their function and contents.
Including :term:`module_conf` causes the OpenEmbedded build system to
populate the ``/etc/modprobe.d/modname.conf`` file with
``modprobe.d`` syntax lines. Here is an example that adds the options
- ``arg1`` and ``arg2`` to a module named ``mymodule``::
+ ``arg1`` and ``arg2`` to a module named ``mymodule``:
+
+ .. code-block:: bitbake
module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
@@ -6483,13 +6893,17 @@ system and gives an overview of their function and contents.
:term:`MODULE_TARBALL_LINK_NAME`
The link name of the kernel module tarball. This variable is set in
- the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
+ the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:
+
+ .. code-block:: bitbake
MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
The value
of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
- same file, has the following value::
+ same file, has the following value:
+
+ .. code-block:: bitbake
KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
@@ -6497,7 +6911,9 @@ system and gives an overview of their function and contents.
:term:`MODULE_TARBALL_NAME`
The base name of the kernel module tarball. This variable is set in
- the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
+ the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:
+
+ .. code-block:: bitbake
MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
@@ -6557,13 +6973,17 @@ system and gives an overview of their function and contents.
not exist in common licenses.
The following example shows how to add :term:`NO_GENERIC_LICENSE` to a
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"
Here is an example that
uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
- source::
+ source:
+
+ .. code-block:: bitbake
NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
@@ -6571,13 +6991,17 @@ system and gives an overview of their function and contents.
Prevents installation of all "recommended-only" packages.
Recommended-only packages are packages installed only through the
:term:`RRECOMMENDS` variable). Setting the
- :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on::
+ :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on:
+
+ .. code-block:: bitbake
NO_RECOMMENDATIONS = "1"
You can set this variable globally in your ``local.conf`` file or you
can attach it to a specific image recipe by using the recipe name
- override::
+ override:
+
+ .. code-block:: bitbake
NO_RECOMMENDATIONS:pn-target_image = "1"
@@ -6603,7 +7027,9 @@ system and gives an overview of their function and contents.
Disables auto package from splitting ``.debug`` files. If a recipe
requires ``FILES:${PN}-dbg`` to be set manually, the
:term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the
- content of the debug package. For example::
+ content of the debug package. For example:
+
+ .. code-block:: bitbake
NOAUTOPACKAGEDEBUG = "1"
FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
@@ -6613,7 +7039,9 @@ system and gives an overview of their function and contents.
:term:`NON_MULTILIB_RECIPES`
A list of recipes that should not be built for multilib. OE-Core's
``multilib.conf`` file defines a reasonable starting point for this
- list with::
+ list with:
+
+ .. code-block:: bitbake
NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot"
@@ -6699,7 +7127,9 @@ system and gives an overview of their function and contents.
By default, this variable is set to ``Ninja``, which is faster than GNU
make, but if building is broken with Ninja, a recipe can use this
- variable to use GNU make instead::
+ variable to use GNU make instead:
+
+ .. code-block:: bitbake
OECMAKE_GENERATOR = "Unix Makefiles"
@@ -6758,7 +7188,9 @@ system and gives an overview of their function and contents.
:term:`OPKGBUILDCMD`
The variable :term:`OPKGBUILDCMD` specifies the command used to build opkg
packages when using the :ref:`ref-classes-package_ipk` class. It is
- defined in :ref:`ref-classes-package_ipk` as::
+ defined in :ref:`ref-classes-package_ipk` as:
+
+ .. code-block:: bitbake
OPKGBUILDCMD ??= 'opkg-build -Z zstd -a "${ZSTD_DEFAULTS}"'
@@ -6767,7 +7199,9 @@ system and gives an overview of their function and contents.
inherited, specifies the device to be mounted for the read/write
layer of ``/etc``. There is no default, so you must set this if you
wish to enable :ref:`ref-classes-overlayfs-etc`, for
- example, assuming ``/dev/mmcblk0p2`` was the desired device::
+ example, assuming ``/dev/mmcblk0p2`` was the desired device:
+
+ .. code-block:: bitbake
OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
@@ -6782,7 +7216,9 @@ system and gives an overview of their function and contents.
inherited, specifies the file system type for the read/write
layer of ``/etc``. There is no default, so you must set this if you
wish to enable :ref:`ref-classes-overlayfs-etc`,
- for example, assuming the file system is ext4::
+ for example, assuming the file system is ext4:
+
+ .. code-block:: bitbake
OVERLAYFS_ETC_FSTYPE = "ext4"
@@ -6796,7 +7232,9 @@ system and gives an overview of their function and contents.
inherited, specifies the parent mount path for the filesystem layers.
There is no default, so you must set this if you wish to enable
:ref:`ref-classes-overlayfs-etc`, for example if the desired path is
- "/data"::
+ "/data":
+
+ .. code-block:: bitbake
OVERLAYFS_ETC_MOUNT_POINT = "/data"
@@ -6808,7 +7246,9 @@ system and gives an overview of their function and contents.
:term:`OVERLAYFS_MOUNT_POINT`
When inheriting the :ref:`ref-classes-overlayfs` class,
- specifies mount point(s) to be used. For example::
+ specifies mount point(s) to be used. For example:
+
+ .. code-block:: bitbake
OVERLAYFS_MOUNT_POINT[data] = "/data"
@@ -6825,7 +7265,9 @@ system and gives an overview of their function and contents.
:term:`OVERLAYFS_QA_SKIP`
When inheriting the :ref:`ref-classes-overlayfs` class,
provides the ability to disable QA checks for particular overlayfs
- mounts. For example::
+ mounts. For example:
+
+ .. code-block:: bitbake
OVERLAYFS_QA_SKIP[data] = "mount-configured"
@@ -6838,7 +7280,9 @@ system and gives an overview of their function and contents.
:term:`OVERLAYFS_WRITABLE_PATHS`
When inheriting the :ref:`ref-classes-overlayfs` class,
specifies writable paths used at runtime for the recipe. For
- example::
+ example:
+
+ .. code-block:: bitbake
OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
@@ -6853,7 +7297,9 @@ system and gives an overview of their function and contents.
As an example, if the string "an-override" appears as an element in
the colon-separated list in :term:`OVERRIDES`, then the following
assignment will override ``FOO`` with the value "overridden" at the
- end of parsing::
+ end of parsing:
+
+ .. code-block:: bitbake
FOO:an-override = "overridden"
@@ -6868,7 +7314,9 @@ system and gives an overview of their function and contents.
:term:`DISTROOVERRIDES` variables. Another
important override included by default is ``pn-${PN}``. This override
allows variables to be set for a single recipe within configuration
- (``.conf``) files. Here is an example::
+ (``.conf``) files. Here is an example:
+
+ .. code-block:: bitbake
FOO:pn-myrecipe = "myrecipe-specific value"
@@ -6919,7 +7367,9 @@ system and gives an overview of their function and contents.
However, if your recipe's output packages are built specific to the
target machine rather than generally for the architecture of the
machine, you should set :term:`PACKAGE_ARCH` to the value of
- :term:`MACHINE_ARCH` in the recipe as follows::
+ :term:`MACHINE_ARCH` in the recipe as follows:
+
+ .. code-block:: bitbake
PACKAGE_ARCH = "${MACHINE_ARCH}"
@@ -6942,14 +7392,18 @@ system and gives an overview of their function and contents.
OpenEmbedded build system uses when packaging data.
You can provide one or more of the following arguments for the
- variable::
+ variable:
+
+ .. code-block:: bitbake
PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
The build system uses only the first argument in the list as the
package manager when creating your image or SDK. However, packages
will be created using any additional packaging classes you specify.
- For example, if you use the following in your ``local.conf`` file::
+ For example, if you use the following in your ``local.conf`` file:
+
+ .. code-block:: bitbake
PACKAGE_CLASSES ?= "package_ipk"
@@ -7006,13 +7460,17 @@ system and gives an overview of their function and contents.
:term:`PACKAGE_EXCLUDE`
Lists packages that should not be installed into an image. For
- example::
+ example:
+
+ .. code-block:: bitbake
PACKAGE_EXCLUDE = "package_name package_name package_name ..."
You can set this variable globally in your ``local.conf`` file or you
can attach it to a specific image recipe by using the recipe name
- override::
+ override:
+
+ .. code-block:: bitbake
PACKAGE_EXCLUDE:pn-target_image = "package_name"
@@ -7067,7 +7525,9 @@ system and gives an overview of their function and contents.
Consider the following example where the :term:`PACKAGE_FEED_URIS`,
:term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
- defined in your ``local.conf`` file::
+ defined in your ``local.conf`` file:
+
+ .. code-block:: bitbake
PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
https://example.com/packagerepos/updates"
@@ -7096,7 +7556,9 @@ system and gives an overview of their function and contents.
Consider the following example where the :term:`PACKAGE_FEED_URIS`,
:term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
- defined in your ``local.conf`` file::
+ defined in your ``local.conf`` file:
+
+ .. code-block:: bitbake
PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
https://example.com/packagerepos/updates"
@@ -7125,7 +7587,9 @@ system and gives an overview of their function and contents.
Consider the following example where the :term:`PACKAGE_FEED_URIS`,
:term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
- defined in your ``local.conf`` file::
+ defined in your ``local.conf`` file:
+
+ .. code-block:: bitbake
PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
https://example.com/packagerepos/updates"
@@ -7190,7 +7654,9 @@ system and gives an overview of their function and contents.
recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in
recipes when you specify features and then arguments that define
feature behaviors. Here is the basic block structure (broken over
- multiple lines for readability)::
+ multiple lines for readability):
+
+ .. code-block:: bitbake
PACKAGECONFIG ??= "f1 f2 f3 ..."
PACKAGECONFIG[f1] = "\
@@ -7231,7 +7697,9 @@ system and gives an overview of their function and contents.
Consider the following :term:`PACKAGECONFIG` block taken from the
``librsvg`` recipe. In this example the feature is ``gtk``, which has
- three arguments that determine the feature's behavior::
+ three arguments that determine the feature's behavior:
+
+ .. code-block:: bitbake
PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
@@ -7253,22 +7721,30 @@ system and gives an overview of their function and contents.
- *Append file:* Create an append file named
``recipename.bbappend`` in your layer and override the value of
:term:`PACKAGECONFIG`. You can either completely override the
- variable::
+ variable:
+
+ .. code-block:: bitbake
PACKAGECONFIG = "f4 f5"
- Or, you can just append the variable::
+ Or, you can just append the variable:
+
+ .. code-block:: bitbake
PACKAGECONFIG:append = " f4"
- *Configuration file:* This method is identical to changing the
block through an append file except you edit your ``local.conf``
or ``mydistro.conf`` file. As with append files previously
- described, you can either completely override the variable::
+ described, you can either completely override the variable:
+
+ .. code-block:: bitbake
PACKAGECONFIG:pn-recipename = "f4 f5"
- Or, you can just amend the variable::
+ Or, you can just amend the variable:
+
+ .. code-block:: bitbake
PACKAGECONFIG:append:pn-recipename = " f4"
@@ -7293,14 +7769,18 @@ system and gives an overview of their function and contents.
:term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be
appended to. Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is
automatically filled with either the first or second element of
- :term:`PACKAGECONFIG` flag value, the recipe would be like::
+ :term:`PACKAGECONFIG` flag value, the recipe would be like:
+
+ .. code-block:: bitbake
inherit cmake
PACKAGECONFIG = "systemd"
PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF"
A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER`
- or not::
+ or not:
+
+ .. code-block:: bitbake
PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}"
@@ -7458,7 +7938,9 @@ system and gives an overview of their function and contents.
patched, it uses "patch".
If you wish to use an alternative patching tool, set the variable in
- the recipe using one of the following::
+ the recipe using one of the following:
+
+ .. code-block:: bitbake
PATCHTOOL = "patch"
PATCHTOOL = "quilt"
@@ -7609,7 +8091,9 @@ system and gives an overview of their function and contents.
:term:`POPULATE_SDK_POST_HOST_COMMAND`
Specifies a list of functions to call once the OpenEmbedded build
system has created the host part of the SDK. You can specify
- functions separated by spaces::
+ functions separated by spaces:
+
+ .. code-block:: bitbake
POPULATE_SDK_POST_HOST_COMMAND += "function"
@@ -7621,7 +8105,9 @@ system and gives an overview of their function and contents.
:term:`POPULATE_SDK_POST_TARGET_COMMAND`
Specifies a list of functions to call once the OpenEmbedded build
system has created the target part of the SDK. You can specify
- functions separated by spaces::
+ functions separated by spaces:
+
+ .. code-block:: bitbake
POPULATE_SDK_POST_TARGET_COMMAND += "function"
@@ -7705,7 +8191,9 @@ system and gives an overview of their function and contents.
*runtime* component. Runtime providers are declared in recipes that set
the :term:`RPROVIDES` variable for a specific package.
- For example::
+ For example:
+
+ .. code-block:: bitbake
PREFERRED_RPROVIDER_virtual-x-terminal-emulator = "rxvt-unicode"
@@ -7713,7 +8201,9 @@ system and gives an overview of their function and contents.
``rxvt-unicode``. The ``rxvt-unicode`` package is a runtime provider of
this component because the ``rxvt-unicode`` recipe set the following
:term:`RPROVIDES` definition for the ``rxvt-unicode`` (``${PN}``)
- package::
+ package:
+
+ .. code-block:: bitbake
RPROVIDES:${PN} = "virtual-x-terminal-emulator"
@@ -7783,7 +8273,9 @@ system and gives an overview of their function and contents.
through the "``%``" character. You can use the character to match any
number of characters, which can be useful when specifying versions
that contain long revision numbers that potentially change. Here are
- two examples::
+ two examples:
+
+ .. code-block:: bitbake
PREFERRED_VERSION_python = "3.4.0"
PREFERRED_VERSION_linux-yocto = "5.0%"
@@ -7806,13 +8298,17 @@ system and gives an overview of their function and contents.
Sometimes the :term:`PREFERRED_VERSION` variable can be set by
configuration files in a way that is hard to change. You can use
:term:`OVERRIDES` to set a machine-specific
- override. Here is an example::
+ override. Here is an example:
+
+ .. code-block:: bitbake
PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%"
Although not recommended, worst case, you can also use the
"forcevariable" override, which is the strongest override possible.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%"
@@ -7839,7 +8335,9 @@ system and gives an overview of their function and contents.
Typically, you could add a specific server for the build system to
attempt before any others by adding something like the following to
the ``local.conf`` configuration file in the
- :term:`Build Directory`::
+ :term:`Build Directory`:
+
+ .. code-block:: bitbake
PREMIRRORS:prepend = "\
git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
@@ -7879,7 +8377,9 @@ system and gives an overview of their function and contents.
standard version of the library.
Libraries specified in this variable should be specified by their
- file name. For example, from the Firefox recipe in meta-browser::
+ file name. For example, from the Firefox recipe in meta-browser:
+
+ .. code-block:: bitbake
PRIVATE_LIBS = "libmozjs.so \
libxpcom.so \
@@ -7903,7 +8403,9 @@ system and gives an overview of their function and contents.
:term:`DEPENDS`.
Consider the following example :term:`PROVIDES` statement from the recipe
- file ``eudev_3.2.9.bb``::
+ file ``eudev_3.2.9.bb``:
+
+ .. code-block:: bitbake
PROVIDES += "udev"
@@ -7940,7 +8442,9 @@ system and gives an overview of their function and contents.
package of the component that manages the ``/dev`` directory.
Setting the "preferred provider" for runtime dependencies is as
- simple as using the following assignment in a configuration file::
+ simple as using the following assignment in a configuration file:
+
+ .. code-block:: bitbake
VIRTUAL-RUNTIME_dev_manager = "udev"
@@ -7950,7 +8454,9 @@ system and gives an overview of their function and contents.
The ``conf/templates/default/local.conf.sample.extended`` configuration
file in :yocto_git:`meta-poky </meta-yocto/tree/meta-poky>` shows how the
- :term:`PRSERV_HOST` variable is set::
+ :term:`PRSERV_HOST` variable is set:
+
+ .. code-block:: bitbake
PRSERV_HOST = "localhost:0"
@@ -8078,7 +8584,9 @@ system and gives an overview of their function and contents.
This variable is similar to the :term:`QB_CMDLINE_IP_SLIRP` variable.
- Use as follows::
+ Use as follows:
+
+ .. code-block:: bitbake
QB_CMDLINE_IP_TAP = "ip=192.168.7.@CLIENT@::192.168.7.@GATEWAY@:255.255.255.0::eth0"
@@ -8092,7 +8600,9 @@ system and gives an overview of their function and contents.
used by ``runqemu`` to specify the `-bios <https://www.qemu.org/docs/master/system/invocation.html#hxtool-8>`__
option of QEMU. For example, this variable can be set as follows to
emulate U-Boot for the :oecore_path:`qemuarm64 <meta/conf/machine/qemuarm64.conf>`
- machine::
+ machine:
+
+ .. code-block:: bitbake
QB_DEFAULT_BIOS = "u-boot.bin"
@@ -8143,14 +8653,18 @@ system and gives an overview of their function and contents.
to the Linux kernel's ``-append`` QEMU options, which controls the Linux kernel
command-line.
- For example::
+ For example:
+
+ .. code-block:: bitbake
QB_KERNEL_CMDLINE_APPEND = "console=ttyS0"
:term:`QB_MEM`
The :term:`QB_MEM` variable controls the amount of memory allocated to the
- emulated machine. Specify as follows::
+ emulated machine. Specify as follows:
+
+ .. code-block:: bitbake
QB_MEM = "-m 512"
@@ -8160,7 +8674,9 @@ system and gives an overview of their function and contents.
the network device instantiated by QEMU. This value needs to be compatible
with the :term:`QB_TAP_OPT` variable.
- Example::
+ Example:
+
+ .. code-block:: bitbake
QB_NETWORK_DEVICE = "-device virtio-net-pci,netdev=net0,mac=@MAC@"
@@ -8172,7 +8688,9 @@ system and gives an overview of their function and contents.
controls extra options to be appended to the NFS rootfs options in the
Linux kernel command-line.
- For example::
+ For example:
+
+ .. code-block:: bitbake
QB_NFSROOTFS_EXTRA_OPT = "wsize=4096,rsize=4096"
@@ -8187,7 +8705,9 @@ system and gives an overview of their function and contents.
pass-through for host random number generator, it can speedup boot
in system mode, where system is experiencing entropy starvation.
- For example::
+ For example:
+
+ .. code-block:: bitbake
QB_RNG = "-object rng-random,filename=/dev/urandom,id=rng0 -device virtio-rng-pci,rng=rng0"
@@ -8201,7 +8721,9 @@ system and gives an overview of their function and contents.
When using ``runqemu``, the :term:`QB_SERIAL_OPT` variable controls the
serial port option.
- For example::
+ For example:
+
+ .. code-block:: bitbake
QB_SERIAL_OPT = "-serial mon:stdio"
@@ -8211,7 +8733,9 @@ system and gives an overview of their function and contents.
amount of CPU cores made availalble inside the QEMU guest, each mapped to
a thread on the host.
- For example::
+ For example:
+
+ .. code-block:: bitbake
QB_SMP = "-smp 8".
@@ -8225,7 +8749,9 @@ system and gives an overview of their function and contents.
When using ``runqemu``, the :term:`QB_TAP_OPT` variable controls
the network option for "tap" mode.
- For example::
+ For example:
+
+ .. code-block:: bitbake
QB_TAP_OPT = "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no"
@@ -8240,7 +8766,9 @@ system and gives an overview of their function and contents.
will not be installed if conflicting packages are not first removed.
Like all package-controlling variables, you must always use them in
- conjunction with a package name override. Here is an example::
+ conjunction with a package name override. Here is an example:
+
+ .. code-block:: bitbake
RCONFLICTS:${PN} = "another_conflicting_package_name"
@@ -8248,7 +8776,9 @@ system and gives an overview of their function and contents.
specifying versioned dependencies. Although the syntax varies
depending on the packaging format, BitBake hides these differences
from you. Here is the general syntax to specify versions with the
- :term:`RCONFLICTS` variable::
+ :term:`RCONFLICTS` variable:
+
+ .. code-block:: bitbake
RCONFLICTS:${PN} = "package (operator version)"
@@ -8261,7 +8791,9 @@ system and gives an overview of their function and contents.
- >=
For example, the following sets up a dependency on version 1.2 or
- greater of the package ``foo``::
+ greater of the package ``foo``:
+
+ .. code-block:: bitbake
RCONFLICTS:${PN} = "foo (>= 1.2)"
@@ -8270,7 +8802,9 @@ system and gives an overview of their function and contents.
packages that must be installed in order for the package to function
correctly. As an example, the following assignment declares that the
package ``foo`` needs the packages ``bar`` and ``baz`` to be
- installed::
+ installed:
+
+ .. code-block:: bitbake
RDEPENDS:foo = "bar baz"
@@ -8311,7 +8845,9 @@ system and gives an overview of their function and contents.
name (remember that a single recipe can build multiple packages). For
example, suppose you are building a development package that depends
on the ``perl`` package. In this case, you would use the following
- :term:`RDEPENDS` statement::
+ :term:`RDEPENDS` statement:
+
+ .. code-block:: bitbake
RDEPENDS:${PN}-dev += "perl"
@@ -8340,7 +8876,9 @@ system and gives an overview of their function and contents.
specifying versioned dependencies. Although the syntax varies
depending on the packaging format, BitBake hides these differences
from you. Here is the general syntax to specify versions with the
- :term:`RDEPENDS` variable::
+ :term:`RDEPENDS` variable:
+
+ .. code-block:: bitbake
RDEPENDS:${PN} = "package (operator version)"
@@ -8360,7 +8898,9 @@ system and gives an overview of their function and contents.
specification.
For example, the following sets up a dependency on version 1.2 or
- greater of the package ``foo``::
+ greater of the package ``foo``:
+
+ .. code-block:: bitbake
RDEPENDS:${PN} = "foo (>= 1.2)"
@@ -8385,7 +8925,9 @@ system and gives an overview of their function and contents.
meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>"
It can also be directly defined in a recipe,
- for example in the ``libgpiod`` one::
+ for example in the ``libgpiod`` one:
+
+ .. code-block:: bitbake
RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>"
@@ -8554,7 +9096,9 @@ system and gives an overview of their function and contents.
:term:`ROOT_HOME`
Defines the root home directory. By default, this directory is set as
- follows in the BitBake configuration file::
+ follows in the BitBake configuration file:
+
+ .. code-block:: bitbake
ROOT_HOME ??= "/home/root"
@@ -8564,7 +9108,9 @@ system and gives an overview of their function and contents.
prefer to have a read-only root filesystem and prefer to keep
writeable data in one place.
- When setting ``INIT_MANAGER = systemd``, the default will be set to::
+ When setting ``INIT_MANAGER = systemd``, the default will be set to:
+
+ .. code-block:: bitbake
ROOT_HOME ?= "/root"
@@ -8580,7 +9126,9 @@ system and gives an overview of their function and contents.
:term:`ROOTFS_POSTINSTALL_COMMAND`
Specifies a list of functions to call after the OpenEmbedded build
system has installed packages. You can specify functions separated by
- spaces::
+ spaces:
+
+ .. code-block:: bitbake
ROOTFS_POSTINSTALL_COMMAND += "function"
@@ -8593,7 +9141,9 @@ system and gives an overview of their function and contents.
:term:`ROOTFS_POSTPROCESS_COMMAND`
Specifies a list of functions to call once the OpenEmbedded build
system has created the root filesystem. You can specify functions
- separated by spaces::
+ separated by spaces:
+
+ .. code-block:: bitbake
ROOTFS_POSTPROCESS_COMMAND += "function"
@@ -8608,7 +9158,9 @@ system and gives an overview of their function and contents.
system has removed unnecessary packages. When runtime package
management is disabled in the image, several packages are removed
including ``base-passwd``, ``shadow``, and ``update-alternatives``.
- You can specify functions separated by spaces::
+ You can specify functions separated by spaces:
+
+ .. code-block:: bitbake
ROOTFS_POSTUNINSTALL_COMMAND += "function"
@@ -8621,7 +9173,9 @@ system and gives an overview of their function and contents.
:term:`ROOTFS_PREPROCESS_COMMAND`
Specifies a list of functions to call before the OpenEmbedded build
system has created the root filesystem. You can specify functions
- separated by spaces::
+ separated by spaces:
+
+ .. code-block:: bitbake
ROOTFS_PREPROCESS_COMMAND += "function"
@@ -8646,7 +9200,9 @@ system and gives an overview of their function and contents.
As with all package-controlling variables, you must always use the
variable in conjunction with a package name override. Here is an
- example::
+ example:
+
+ .. code-block:: bitbake
RPROVIDES:${PN} = "widget-abi-2"
@@ -8677,7 +9233,9 @@ system and gives an overview of their function and contents.
particular package whose usability is being extended. For example,
suppose you are building a development package that is extended to
support wireless functionality. In this case, you would use the
- following::
+ following:
+
+ .. code-block:: bitbake
RRECOMMENDS:${PN}-dev += "wireless_package_name"
@@ -8690,7 +9248,9 @@ system and gives an overview of their function and contents.
specifying versioned recommends. Although the syntax varies depending
on the packaging format, BitBake hides these differences from you.
Here is the general syntax to specify versions with the
- :term:`RRECOMMENDS` variable::
+ :term:`RRECOMMENDS` variable:
+
+ .. code-block:: bitbake
RRECOMMENDS:${PN} = "package (operator version)"
@@ -8703,7 +9263,9 @@ system and gives an overview of their function and contents.
- >=
For example, the following sets up a recommend on version 1.2 or
- greater of the package ``foo``::
+ greater of the package ``foo``:
+
+ .. code-block:: bitbake
RRECOMMENDS:${PN} = "foo (>= 1.2)"
@@ -8715,7 +9277,9 @@ system and gives an overview of their function and contents.
the other package to the :term:`RCONFLICTS` variable.
As with all package-controlling variables, you must use this variable
- in conjunction with a package name override. Here is an example::
+ in conjunction with a package name override. Here is an example:
+
+ .. code-block:: bitbake
RREPLACES:${PN} = "other_package_being_replaced"
@@ -8723,7 +9287,9 @@ system and gives an overview of their function and contents.
specifying versioned replacements. Although the syntax varies
depending on the packaging format, BitBake hides these differences
from you. Here is the general syntax to specify versions with the
- :term:`RREPLACES` variable::
+ :term:`RREPLACES` variable:
+
+ .. code-block:: bitbake
RREPLACES:${PN} = "package (operator version)"
@@ -8736,7 +9302,9 @@ system and gives an overview of their function and contents.
- >=
For example, the following sets up a replacement using version 1.2
- or greater of the package ``foo``::
+ or greater of the package ``foo``:
+
+ .. code-block:: bitbake
RREPLACES:${PN} = "foo (>= 1.2)"
@@ -8749,7 +9317,9 @@ system and gives an overview of their function and contents.
As with all package-controlling variables, you must always use this
variable in conjunction with a package name override. Here is an
- example::
+ example:
+
+ .. code-block:: bitbake
RSUGGESTS:${PN} = "useful_package another_package"
@@ -8811,7 +9381,9 @@ system and gives an overview of their function and contents.
- The ``ext`` flag contains the filename extension (suffix). The output
filename is going will be ``${IMAGE_NAME}${ext}``.
- For example::
+ For example:
+
+ .. code-block:: bitbake
SBOM_CVE_CHECK_EXPORT_VARS = "SBOM_CVE_CHECK_EXPORT_SPDX3"
SBOM_CVE_CHECK_EXPORT_SPDX3[type] = "spdx3"
@@ -8888,7 +9460,9 @@ system and gives an overview of their function and contents.
The directory set up and used by the
:ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the
SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>`
- class defines :term:`SDK_DEPLOY` as follows::
+ class defines :term:`SDK_DEPLOY` as follows:
+
+ .. code-block:: bitbake
SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
@@ -8896,7 +9470,9 @@ system and gives an overview of their function and contents.
The parent directory used by the OpenEmbedded build system when
creating SDK output. The
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
- the variable as follows::
+ the variable as follows:
+
+ .. code-block:: bitbake
SDK_DIR = "${WORKDIR}/sdk"
@@ -8926,7 +9502,9 @@ system and gives an overview of their function and contents.
packagename packagearch version
The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
- defines the manifest file as follows::
+ defines the manifest file as follows:
+
+ .. code-block:: bitbake
SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
@@ -8973,7 +9551,9 @@ system and gives an overview of their function and contents.
:term:`SDKMACHINE`,
:term:`IMAGE_BASENAME`,
:term:`TUNE_PKGARCH`, and
- :term:`MACHINE` variables::
+ :term:`MACHINE` variables:
+
+ .. code-block:: bitbake
SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}"
@@ -8984,7 +9564,9 @@ system and gives an overview of their function and contents.
:term:`SDK_OUTPUT`
The location used by the OpenEmbedded build system when creating SDK
output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
- class defines the variable as follows::
+ class defines the variable as follows:
+
+ .. code-block:: bitbake
SDK_DIR = "${WORKDIR}/sdk"
SDK_OUTPUT = "${SDK_DIR}/image"
@@ -9057,7 +9639,9 @@ system and gives an overview of their function and contents.
packagename packagearch version
The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
- defines the manifest file as follows::
+ defines the manifest file as follows:
+
+ .. code-block:: bitbake
SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
@@ -9077,7 +9661,9 @@ system and gives an overview of their function and contents.
this title is based on the :term:`DISTRO_NAME` or
:term:`DISTRO` variable and is set in the
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
- follows::
+ follows:
+
+ .. code-block:: bitbake
SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
@@ -9104,7 +9690,9 @@ system and gives an overview of their function and contents.
:term:`SDK_VERSION`
Specifies the version of the SDK. The Poky distribution configuration file
(``/meta-poky/conf/distro/poky.conf``) sets the default
- :term:`SDK_VERSION` as follows::
+ :term:`SDK_VERSION` as follows:
+
+ .. code-block:: bitbake
SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
@@ -9122,7 +9710,9 @@ system and gives an overview of their function and contents.
default, this directory is based on the :term:`DISTRO`
variable and is set in the
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
- follows::
+ follows:
+
+ .. code-block:: bitbake
SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
@@ -9190,7 +9780,9 @@ system and gives an overview of their function and contents.
Defines a serial console (TTY) to enable using
:wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the
baud rate followed by the TTY device name separated by a semicolon.
- Use spaces to separate multiple devices::
+ Use spaces to separate multiple devices:
+
+ .. code-block:: bitbake
SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
@@ -9205,14 +9797,18 @@ system and gives an overview of their function and contents.
the ``setup.py`` file is located if it is not at the root of the source
tree (as specified by :term:`S`). For example, in a recipe where the
sources are fetched from a Git repository and ``setup.py`` is in a
- ``python/pythonmodule`` subdirectory, you would have this::
+ ``python/pythonmodule`` subdirectory, you would have this:
+
+ .. code-block:: bitbake
SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule"
:term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS`
A list of recipe dependencies that should not be used to determine
signatures of tasks from one recipe when they depend on tasks from
- another recipe. For example::
+ another recipe. For example:
+
+ .. code-block:: bitbake
SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
@@ -9220,7 +9816,9 @@ system and gives an overview of their function and contents.
You can use the special token ``"*"`` on the left-hand side of the
dependency to match all recipes except the one on the right-hand
- side. Here is an example::
+ side. Here is an example:
+
+ .. code-block:: bitbake
SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
@@ -9251,7 +9849,9 @@ system and gives an overview of their function and contents.
after the other had been built.
:term:`SIGGEN_LOCKEDSIGS`
- The list of locked tasks, with the form::
+ The list of locked tasks, with the form:
+
+ .. code-block:: bitbake
SIGGEN_LOCKEDSIGS += "<package>:<task>:<signature>"
@@ -9260,7 +9860,9 @@ system and gives an overview of their function and contents.
rebuilding the ``<task>``. If it does not exist, BitBake will build the
``<task>`` and the sstate cache will be used next time.
- Example::
+ Example:
+
+ .. code-block:: bitbake
SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"
@@ -9286,7 +9888,9 @@ system and gives an overview of their function and contents.
:term:`SIGGEN_LOCKEDSIGS_TYPES`
Allowed overrides for :term:`SIGGEN_LOCKEDSIGS`. This is mainly used
for architecture specific locks. A common value for
- :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``::
+ :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``:
+
+ .. code-block:: bitbake
SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}"
@@ -9312,7 +9916,9 @@ system and gives an overview of their function and contents.
To enable file removal, set the variable to "1" in your
``conf/local.conf`` configuration file in your:
- :term:`Build Directory`::
+ :term:`Build Directory`:
+
+ .. code-block:: bitbake
SKIP_FILEDEPS = "1"
@@ -9324,7 +9930,9 @@ system and gives an overview of their function and contents.
To prevent a recipe from being built, use the :term:`SKIP_RECIPE`
variable in your ``local.conf`` file or distribution configuration.
- Here is an example which prevents ``myrecipe`` from being built::
+ Here is an example which prevents ``myrecipe`` from being built:
+
+ .. code-block:: bitbake
SKIP_RECIPE[myrecipe] = "Not supported by our organization."
@@ -9369,7 +9977,9 @@ system and gives an overview of their function and contents.
:oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`.
If a recipe wishes to override the default behavior, it should set its
- own :term:`SOURCE_DATE_EPOCH` value::
+ own :term:`SOURCE_DATE_EPOCH` value:
+
+ .. code-block:: bitbake
SOURCE_DATE_EPOCH = "1613559011"
@@ -9398,7 +10008,9 @@ system and gives an overview of their function and contents.
To use this variable, you must globally inherit the
:ref:`ref-classes-own-mirrors` class and then provide
- the URL to your mirrors. Here is the general syntax::
+ the URL to your mirrors. Here is the general syntax:
+
+ .. code-block:: bitbake
INHERIT += "own-mirrors"
SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"
@@ -9428,7 +10040,9 @@ system and gives an overview of their function and contents.
Another method to configure the username and password is from the URL
in :term:`SOURCE_MIRROR_URL` directly, with the ``user`` and ``pswd``
- parameters::
+ parameters:
+
+ .. code-block:: bitbake
SOURCE_MIRROR_URL = "http://example.com/my_source_mirror;user=<user>;pswd=<password>"
@@ -9456,18 +10070,24 @@ system and gives an overview of their function and contents.
This variable can be set in two ways:
- - For the entire recipe::
+ - For the entire recipe:
+
+ .. code-block:: bitbake
SPDX_CONCLUDED_LICENSE = "MIT & Apache-2.0"
- - For an individual package produced by the recipe::
+ - For an individual package produced by the recipe:
+
+ .. code-block:: bitbake
SPDX_CONCLUDED_LICENSE:${PN} = "MIT & Apache-2.0"
:term:`SPDX_CUSTOM_ANNOTATION_VARS`
This option allows to associate `SPDX annotations
<https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe,
- using the values of variables in the recipe::
+ using the values of variables in the recipe:
+
+ .. code-block:: bitbake
ANNOTATION1 = "First annotation for recipe"
ANNOTATION2 = "Second annotation for recipe"
@@ -9533,14 +10153,18 @@ system and gives an overview of their function and contents.
so the sub-variable names follow directly from
``SPDX_IMAGE_SUPPLIER``.
- Example (set in the image recipe or in a :term:`configuration file`)::
+ Example (set in the image recipe or in a :term:`configuration file`):
+
+ .. code-block:: bitbake
SPDX_IMAGE_SUPPLIER = "SPDX_IMAGE_SUPPLIER"
SPDX_IMAGE_SUPPLIER_name = "Acme Corp"
SPDX_IMAGE_SUPPLIER_type = "organization"
Alternatively, you can use any other prefix name, which is useful for
- sharing an agent definition across multiple supplier variables::
+ sharing an agent definition across multiple supplier variables:
+
+ .. code-block:: bitbake
MY_COMPANY_name = "Acme Corp"
MY_COMPANY_type = "organization"
@@ -9566,7 +10190,9 @@ system and gives an overview of their function and contents.
Enabling this variable will result in non-reproducible SPDX output,
because the build invocation identity changes with every run.
- Enable as follows::
+ Enable as follows:
+
+ .. code-block:: bitbake
SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
@@ -9586,7 +10212,9 @@ system and gives an overview of their function and contents.
This enables an external tool to use the SPDX information to disregard
vulnerabilities that are not compiled in the packages.
- Enable this option as follows::
+ Enable this option as follows:
+
+ .. code-block:: bitbake
SPDX_INCLUDE_COMPILED_SOURCES = "1"
@@ -9615,7 +10243,9 @@ system and gives an overview of their function and contents.
This variable only has effect when using the SPDX 3.0 output
format (see :ref:`ref-classes-create-spdx`).
- Enable this option as follows::
+ Enable this option as follows:
+
+ .. code-block:: bitbake
SPDX_INCLUDE_KERNEL_CONFIG = "1"
@@ -9636,7 +10266,9 @@ system and gives an overview of their function and contents.
This variable only has effect when using the SPDX 3.0 output
format (see :ref:`ref-classes-create-spdx`).
- Enable this option as follows::
+ Enable this option as follows:
+
+ .. code-block:: bitbake
SPDX_INCLUDE_PACKAGECONFIG = "1"
@@ -9654,7 +10286,9 @@ system and gives an overview of their function and contents.
``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also
modified to include references to such source file descriptions.
- Enable this option as follows::
+ Enable this option as follows:
+
+ .. code-block:: bitbake
SPDX_INCLUDE_SOURCES = "1"
@@ -9697,7 +10331,9 @@ system and gives an overview of their function and contents.
- ``SPDX_INVOKED_BY_name``: display name of the invoking agent
- ``SPDX_INVOKED_BY_type``: agent type, such as ``software`` for a CI system
- Example (CI pipeline invoking the build)::
+ Example (CI pipeline invoking the build):
+
+ .. code-block:: bitbake
SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
SPDX_INVOKED_BY = "SPDX_INVOKED_BY"
@@ -9752,7 +10388,9 @@ system and gives an overview of their function and contents.
- ``SPDX_ON_BEHALF_OF_name``: display name of the commissioning agent
- ``SPDX_ON_BEHALF_OF_type``: agent type, such as ``organization``
- Example (CI system building on behalf of a customer organization)::
+ Example (CI system building on behalf of a customer organization):
+
+ .. code-block:: bitbake
SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1"
SPDX_INVOKED_BY = "SPDX_INVOKED_BY"
@@ -9778,7 +10416,9 @@ system and gives an overview of their function and contents.
Typically set in a distro :term:`configuration file` to apply globally
to all packages, or in a specific software recipe (or a ``.bbappend``)
to apply only to packages of that recipe. Recipe-level overrides
- (``SPDX_PACKAGE_SUPPLIER:pn-<recipe>``) are also supported::
+ (``SPDX_PACKAGE_SUPPLIER:pn-<recipe>``) are also supported:
+
+ .. code-block:: bitbake
SPDX_PACKAGE_SUPPLIER = "SPDX_PACKAGE_SUPPLIER"
SPDX_PACKAGE_SUPPLIER_name = "Acme Corp"
@@ -9809,7 +10449,9 @@ system and gives an overview of their function and contents.
:term:`SPDX_PRETTY`
This option makes the SPDX output more human-readable, using
identation and newlines, instead of the default output in a
- single line::
+ single line:
+
+ .. code-block:: bitbake
SPDX_PRETTY = "1"
@@ -9938,13 +10580,17 @@ system and gives an overview of their function and contents.
└── psplash_%.bbappend
And here are the contents of the ``psplash_%.bbappend`` file in
- this example::
+ this example:
+
+ .. code-block:: bitbake
SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default"
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
You could even add specific configuration options for ``psplash``,
- for example::
+ for example:
+
+ .. code-block:: bitbake
EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen"
@@ -10022,7 +10668,9 @@ system and gives an overview of their function and contents.
The :term:`SRCPV` variable used to be defined in the
``meta/conf/bitbake.conf`` configuration file in
- :term:`OpenEmbedded-Core (OE-Core)` as follows::
+ :term:`OpenEmbedded-Core (OE-Core)` as follows:
+
+ .. code-block:: bitbake
SRCPV = "${@bb.fetch2.get_srcrev(d)}"
@@ -10052,13 +10700,17 @@ system and gives an overview of their function and contents.
A list of tasks that are typically not relevant (and therefore skipped)
when building using the :ref:`ref-classes-externalsrc`
class. The default value as set in that class file is the set of tasks
- that are rarely needed when using external source::
+ that are rarely needed when using external source:
+
+ .. code-block:: bitbake
SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch"
The notable exception is when processing external kernel source as
defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for
- aesthetics)::
+ aesthetics):
+
+ .. code-block:: bitbake
SRCTREECOVEREDTASKS += "\
do_validate_branches \
@@ -10123,7 +10775,9 @@ system and gives an overview of their function and contents.
you point to can also be from builds on other machines.
The Yocto Project actually shares the cache data objects built by its
- autobuilder::
+ autobuilder:
+
+ .. code-block:: bitbake
SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
@@ -10183,11 +10837,15 @@ system and gives an overview of their function and contents.
size and time costs of the artefact are similar to just running the
tasks. This generally only applies to end artefact output like images.
- The syntax to disable it for one task is::
+ The syntax to disable it for one task is:
+
+ .. code-block:: bitbake
SSTATE_SKIP_CREATION:task-image-complete = "1"
- The syntax to disable it for the whole recipe is::
+ The syntax to disable it for the whole recipe is:
+
+ .. code-block:: bitbake
SSTATE_SKIP_CREATION = "1"
@@ -10402,7 +11060,9 @@ system and gives an overview of their function and contents.
to an actual stamp file is constructed by evaluating this string and
then appending additional information. Currently, the default
assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf``
- file is::
+ file is:
+
+ .. code-block:: bitbake
STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
@@ -10446,7 +11106,9 @@ system and gives an overview of their function and contents.
:term:`SYSLINUX_DEFAULT_CONSOLE`
Specifies the kernel boot default console. If you want to use a
console other than the default, set this variable in your recipe as
- follows where "X" is the console number you want to use::
+ follows where "X" is the console number you want to use:
+
+ .. code-block:: bitbake
SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
@@ -10465,7 +11127,9 @@ system and gives an overview of their function and contents.
Specifies the alternate serial port or turns it off. To turn off
serial, set this variable to an empty string in your recipe. The
variable's default value is set in the
- :ref:`ref-classes-syslinux` class as follows::
+ :ref:`ref-classes-syslinux` class as follows:
+
+ .. code-block:: bitbake
SYSLINUX_SERIAL ?= "0 115200"
@@ -10474,7 +11138,9 @@ system and gives an overview of their function and contents.
:term:`SYSLINUX_SERIAL_TTY`
Specifies the alternate console=tty... kernel boot argument. The
variable's default value is set in the :ref:`ref-classes-syslinux`
- class as follows::
+ class as follows:
+
+ .. code-block:: bitbake
SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
@@ -10497,7 +11163,9 @@ system and gives an overview of their function and contents.
:term:`SYSROOT_DIRS`
Directories that are staged into the sysroot by the
:ref:`ref-tasks-populate_sysroot` task. By
- default, the following directories are staged::
+ default, the following directories are staged:
+
+ .. code-block:: bitbake
SYSROOT_DIRS = " \
${includedir} \
@@ -10526,14 +11194,18 @@ system and gives an overview of their function and contents.
``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So,
the linking process will fail.
- To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`::
+ To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`:
+
+ .. code-block:: bitbake
SYSROOT_DIRS:append = " /opt/lib"
.. note::
Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail
because the linker does not know that location, since :term:`TARGET_LDFLAGS`
- doesn't contain it (if your recipe is for the target). Therefore, so you should add::
+ doesn't contain it (if your recipe is for the target). Therefore, so you should add:
+
+ .. code-block:: bitbake
TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib"
@@ -10542,7 +11214,9 @@ system and gives an overview of their function and contents.
:ref:`ref-tasks-populate_sysroot` task. You
can use this variable to exclude certain subdirectories of
directories listed in :term:`SYSROOT_DIRS` from
- staging. By default, the following directories are not staged::
+ staging. By default, the following directories are not staged:
+
+ .. code-block:: bitbake
SYSROOT_DIRS_IGNORE = " \
${mandir} \
@@ -10565,7 +11239,9 @@ system and gives an overview of their function and contents.
:ref:`ref-tasks-populate_sysroot` task for
``-native`` recipes, in addition to those specified in
:term:`SYSROOT_DIRS`. By default, the following
- extra directories are staged::
+ extra directories are staged:
+
+ .. code-block:: bitbake
SYSROOT_DIRS_NATIVE = " \
${bindir} \
@@ -10594,7 +11270,9 @@ system and gives an overview of their function and contents.
:term:`SYSTEMD_SERVICE` should start
automatically or not. By default, the service is enabled to
automatically start at boot time. The default setting is in the
- :ref:`ref-classes-systemd` class as follows::
+ :ref:`ref-classes-systemd` class as follows:
+
+ .. code-block:: bitbake
SYSTEMD_AUTO_ENABLE ??= "enable"
@@ -10605,7 +11283,9 @@ system and gives an overview of their function and contents.
"systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the
configuration file that should be used. By default, the
:ref:`ref-classes-systemd-boot` class sets the
- :term:`SYSTEMD_BOOT_CFG` as follows::
+ :term:`SYSTEMD_BOOT_CFG` as follows:
+
+ .. code-block:: bitbake
SYSTEMD_BOOT_CFG ?= "${S}/loader.conf"
@@ -10617,7 +11297,9 @@ system and gives an overview of their function and contents.
"systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a
list of entry files (``*.conf``) to install that contain one boot
entry per file. By default, the :ref:`ref-classes-systemd-boot` class
- sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows::
+ sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows:
+
+ .. code-block:: bitbake
SYSTEMD_BOOT_ENTRIES ?= ""
@@ -10629,7 +11311,9 @@ system and gives an overview of their function and contents.
"systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the
boot menu timeout in seconds. By default, the
:ref:`ref-classes-systemd-boot` class sets the
- :term:`SYSTEMD_BOOT_TIMEOUT` as follows::
+ :term:`SYSTEMD_BOOT_TIMEOUT` as follows:
+
+ .. code-block:: bitbake
SYSTEMD_BOOT_TIMEOUT ?= "10"
@@ -10649,7 +11333,9 @@ system and gives an overview of their function and contents.
For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb
</meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>`
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
SYSTEMD_DEFAULT_TARGET = "graphical.target"
@@ -10658,7 +11344,9 @@ system and gives an overview of their function and contents.
this variable locates the systemd unit files when they are not found
in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES`
variable is set such that the systemd unit files are assumed to
- reside in the recipes main package::
+ reside in the recipes main package:
+
+ .. code-block:: bitbake
SYSTEMD_PACKAGES ?= "${PN}"
@@ -10674,7 +11362,9 @@ system and gives an overview of their function and contents.
When you specify this file in your recipe, use a package name
override to indicate the package to which the value applies. Here is
- an example from the connman recipe::
+ an example from the connman recipe:
+
+ .. code-block:: bitbake
SYSTEMD_SERVICE:${PN} = "connman.service"
@@ -10694,7 +11384,9 @@ system and gives an overview of their function and contents.
:term:`T`
This variable points to a directory were BitBake places temporary
files, which consist mostly of task logs and scripts, when building a
- particular recipe. The variable is typically set as follows::
+ particular recipe. The variable is typically set as follows:
+
+ .. code-block:: bitbake
T = "${WORKDIR}/temp"
@@ -10728,7 +11420,9 @@ system and gives an overview of their function and contents.
Specifies architecture-specific assembler flags for the target
system. :term:`TARGET_AS_ARCH` is initialized from
:term:`TUNE_ASARGS` by default in the BitBake
- configuration file (``meta/conf/bitbake.conf``)::
+ configuration file (``meta/conf/bitbake.conf``):
+
+ .. code-block:: bitbake
TARGET_AS_ARCH = "${TUNE_ASARGS}"
@@ -10799,7 +11493,9 @@ system and gives an overview of their function and contents.
Specifies architecture-specific linker flags for the target system.
:term:`TARGET_LD_ARCH` is initialized from
:term:`TUNE_LDARGS` by default in the BitBake
- configuration file (``meta/conf/bitbake.conf``)::
+ configuration file (``meta/conf/bitbake.conf``):
+
+ .. code-block:: bitbake
TARGET_LD_ARCH = "${TUNE_LDARGS}"
@@ -10988,7 +11684,9 @@ system and gives an overview of their function and contents.
program does.
For example, to use the Picocom terminal program on serial device
- ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows::
+ ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:
+
+ .. code-block:: bitbake
TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
@@ -11037,13 +11735,17 @@ system and gives an overview of their function and contents.
Tests include ``ping``, ``ssh``, ``df`` among others. You can add
your own tests to the list of tests by appending :term:`TEST_SUITES` as
- follows::
+ follows:
+
+ .. code-block:: bitbake
TEST_SUITES:append = " mytest"
Alternatively, you can
provide the "auto" option to have all applicable tests run against
- the image::
+ the image:
+
+ .. code-block:: bitbake
TEST_SUITES:append = " auto"
@@ -11055,7 +11757,9 @@ system and gives an overview of their function and contents.
another test must appear later in the list than the test on which
they depend. For example, if you append the list of tests with two
tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
- ``test_A``, then you must order the tests as follows::
+ ``test_A``, then you must order the tests as follows:
+
+ .. code-block:: bitbake
TEST_SUITES = "test_A test_B"
@@ -11065,7 +11769,9 @@ system and gives an overview of their function and contents.
:term:`TEST_TARGET`
Specifies the target controller to use when running tests against a
- test image. The default controller to use is "qemu"::
+ test image. The default controller to use is "qemu":
+
+ .. code-block:: bitbake
TEST_TARGET = "qemu"
@@ -11104,7 +11810,9 @@ system and gives an overview of their function and contents.
set to "qemu".
When you specify the IP address, you can also include a port. Here is
- an example::
+ an example:
+
+ .. code-block:: bitbake
TEST_TARGET_IP = "192.168.1.4:2201"
@@ -11164,7 +11872,9 @@ system and gives an overview of their function and contents.
If you want to establish this directory in a location other than the
default, you can set it to another value in your
- :ref:`structure-build-conf-site.conf` configuration file::
+ :ref:`structure-build-conf-site.conf` configuration file:
+
+ .. code-block:: bitbake
TMPDIR = "/another/location"
@@ -11240,7 +11950,9 @@ system and gives an overview of their function and contents.
:term:`TOOLCHAIN_OPTIONS`
This variable holds extra options passed to the compiler and the linker
for non ``-native`` recipes as they have to point to their custom
- ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`::
+ ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`:
+
+ .. code-block:: bitbake
TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}"
@@ -11250,7 +11962,9 @@ system and gives an overview of their function and contents.
:term:`TOOLCHAIN_OUTPUTNAME`
This variable defines the name used for the toolchain output. The
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
- the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows::
+ the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:
+
+ .. code-block:: bitbake
TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
@@ -11304,7 +12018,9 @@ system and gives an overview of their function and contents.
:term:`TUNE_ARCH` is tied closely to
:term:`TARGET_ARCH`, which defines the target
machine's architecture. The BitBake configuration file
- (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows::
+ (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:
+
+ .. code-block:: bitbake
TARGET_ARCH = "${TUNE_ARCH}"
@@ -11326,7 +12042,9 @@ system and gives an overview of their function and contents.
typically under ``meta/conf/machine/include/`` and are influenced
through :term:`TUNE_FEATURES`. For example, the
``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
- for the x86 architecture as follows::
+ for the x86 architecture as follows:
+
+ .. code-block:: bitbake
TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
@@ -11372,7 +12090,9 @@ system and gives an overview of their function and contents.
typically under ``meta/conf/machine/include/`` and are influenced
through :term:`TUNE_FEATURES`. For example, the
``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
- for the x86 architecture as follows::
+ for the x86 architecture as follows:
+
+ .. code-block:: bitbake
TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
@@ -11385,13 +12105,17 @@ system and gives an overview of their function and contents.
:term:`TUNE_PKGARCH`
The package architecture understood by the packaging system to define
the architecture, ABI, and tuning of output packages. The specific
- tune is defined using the "_tune" override as follows::
+ tune is defined using the "_tune" override as follows:
+
+ .. code-block:: bitbake
TUNE_PKGARCH:tune-tune = "tune"
These tune-specific package architectures are defined in the machine
include files. Here is an example of the "core2-32" tuning as used in
- the ``meta/conf/machine/include/x86/tune-core2.inc`` file::
+ the ``meta/conf/machine/include/x86/tune-core2.inc`` file:
+
+ .. code-block:: bitbake
TUNE_PKGARCH:tune-core2-32 = "core2-32"
@@ -11403,7 +12127,9 @@ system and gives an overview of their function and contents.
:term:`OpenEmbedded-Core (OE-Core)`. Here is an example from
the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
that lists the "o32" and "n64" features as conflicting with the "n32"
- feature::
+ feature:
+
+ .. code-block:: bitbake
TUNECONFLICTS[n32] = "o32 n64"
@@ -11412,7 +12138,9 @@ system and gives an overview of their function and contents.
feature. The specified feature is stored as a flag. Valid features
are specified in the machine include files (e.g.
``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
- from that file::
+ from that file:
+
+ .. code-block:: bitbake
TUNEVALID[bigendian] = "Enable big-endian mode."
@@ -11429,7 +12157,9 @@ system and gives an overview of their function and contents.
:term:`UBOOT_CONFIG_FRAGMENTS`, :term:`UBOOT_CONFIG_IMAGE_FSTYPES`, and
:term:`UBOOT_CONFIG_MAKE_OPTS`.
- Here is an updated example from the ``meta-freescale`` layer. ::
+ Here is an updated example from the ``meta-freescale`` layer.
+
+ .. code-block:: bitbake
UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor"
@@ -11455,7 +12185,9 @@ system and gives an overview of their function and contents.
:term:`UBOOT_CONFIG_BINARY`
This variable cannot be set to a value in a config, it is a placeholder
- for configuring the :term:`UBOOT_CONFIG` flow via flags::
+ for configuring the :term:`UBOOT_CONFIG` flow via flags:
+
+ .. code-block:: bitbake
UBOOT_CONFIG_BINARY[foo] = "binary1"
UBOOT_CONFIG_BINARY[bar] = "binary2"
@@ -11478,7 +12210,9 @@ system and gives an overview of their function and contents.
:term:`UBOOT_CONFIG_FRAGMENTS`
This variable cannot be set to a value in a config, it is a placeholder
- for configuring the :term:`UBOOT_CONFIG` flow via flags::
+ for configuring the :term:`UBOOT_CONFIG` flow via flags:
+
+ .. code-block:: bitbake
UBOOT_CONFIG_FRAGMENTS[foo] = "frag1 frag2"
UBOOT_CONFIG_FRAGMENTS[bar] = "frag3"
@@ -11496,7 +12230,9 @@ system and gives an overview of their function and contents.
:term:`UBOOT_CONFIG_IMAGE_FSTYPES`
This variable cannot be set to a value in a config, it is a placeholder
- for configuring the :term:`UBOOT_CONFIG` flow via flags::
+ for configuring the :term:`UBOOT_CONFIG` flow via flags:
+
+ .. code-block:: bitbake
UBOOT_CONFIG_IMAGE_FSTYPES[foo] = "fstype1"
UBOOT_CONFIG_IMAGE_FSTYPES[bar] = "fstype2"
@@ -11513,7 +12249,9 @@ system and gives an overview of their function and contents.
:term:`UBOOT_CONFIG_MAKE_OPTS`
This variable cannot be set to a value in a config, it is a placeholder
- for configuring the :term:`UBOOT_CONFIG` flow via flags::
+ for configuring the :term:`UBOOT_CONFIG` flow via flags:
+
+ .. code-block:: bitbake
UBOOT_CONFIG_MAKE_OPTS[foo] = "OPT1=foo OPT2=2"
UBOOT_CONFIG_MAKE_OPTS[bar] = "OPT1=bar"
@@ -11568,13 +12306,17 @@ system and gives an overview of their function and contents.
Some examples:
- - Adding a script ``boot.cmd`` as a uImage to ``/boot``::
+ - Adding a script ``boot.cmd`` as a uImage to ``/boot``:
+
+ .. code-block:: bitbake
UBOOT_ENV = "boot"
UBOOT_ENV_SUFFIX = "scr"
SRC_URI += "file://${UBOOT_ENV_SRC}"
- - Adding a script ``uEnv.txt`` as a plain text file to ``/boot``::
+ - Adding a script ``uEnv.txt`` as a plain text file to ``/boot``:
+
+ .. code-block:: bitbake
UBOOT_ENV = "uEnv"
UBOOT_ENV_SUFFIX = "txt"
@@ -11603,7 +12345,9 @@ system and gives an overview of their function and contents.
set this value to "2", as two 32 bit values (cells) will be needed
to represent such addresses.
- Here is an example setting "0x400000000" as a load address::
+ Here is an example setting "0x400000000" as a load address:
+
+ .. code-block:: bitbake
UBOOT_FIT_ADDRESS_CELLS = "2"
UBOOT_LOADADDRESS = "0x04 0x00000000"
@@ -11617,19 +12361,25 @@ system and gives an overview of their function and contents.
Secure Monitor. This variable enables the generation of a U-Boot FIT
image with a Trusted Firmware-A (TF-A) binary.
- Its default value is "0", so set it to "1" to enable this functionality::
+ Its default value is "0", so set it to "1" to enable this functionality:
+
+ .. code-block:: bitbake
UBOOT_FIT_ARM_TRUSTED_FIRMWARE = "1"
:term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE`
Specifies the path to the Trusted Firmware-A (TF-A) binary. Its default
- value is "bl31.bin"::
+ value is "bl31.bin":
+
+ .. code-block:: bitbake
UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin"
If a relative path is provided, the file is expected to be relative to
U-Boot's :term:`B` directory. An absolute path can be provided too,
- e.g.::
+ e.g.:
+
+ .. code-block:: bitbake
UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/bl31.bin"
@@ -11637,7 +12387,9 @@ system and gives an overview of their function and contents.
you must add the necessary dependency in a U-Boot ``.bbappend`` file. The
recipe name for Trusted Firmware-A (TF-A) binary is
``trusted-firmware-a``, which comes from the
- :yocto_git:`meta-arm </meta-arm>` layer::
+ :yocto_git:`meta-arm </meta-arm>` layer:
+
+ .. code-block:: bitbake
do_compile[depends] += "trusted-firmware-a:do_deploy"
@@ -11648,7 +12400,9 @@ system and gives an overview of their function and contents.
:term:`UBOOT_FIT_CONF_FIRMWARE`
Adds one image to the ``firmware`` property of the configuration node of
the U-Boot Image Tree Source (ITS). Sets the ``firmware`` property to
- select the image to boot first::
+ select the image to boot first:
+
+ .. code-block:: bitbake
UBOOT_FIT_CONF_FIRMWARE = "fwa"
@@ -11658,13 +12412,17 @@ system and gives an overview of their function and contents.
Adds one or more user-defined images to the ``loadables`` property of the
configuration node of the U-Boot Image Tree Source (ITS). This variable
is handled by the local shell in the recipe so appropriate escaping
- should be done, e.g. escaping quotes.::
+ should be done, e.g. escaping quotes.:
+
+ .. code-block:: bitbake
UBOOT_FIT_CONF_USER_LOADABLES = '\"fwa\", \"fwb\"'
:term:`UBOOT_FIT_DESC`
Specifies the description string encoded into a U-Boot fitImage. The default
- value is set by the :ref:`ref-classes-uboot-sign` class as follows::
+ value is set by the :ref:`ref-classes-uboot-sign` class as follows:
+
+ .. code-block:: bitbake
UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
@@ -11673,7 +12431,9 @@ system and gives an overview of their function and contents.
they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`.
The default value is "0".
- Enable this as follows::
+ Enable this as follows:
+
+ .. code-block:: bitbake
UBOOT_FIT_GENERATE_KEYS = "1"
@@ -11716,19 +12476,25 @@ system and gives an overview of their function and contents.
the surrounding system. This variable enables the generation of a U-Boot
FIT image with a Trusted Execution Environment (TEE) binary.
- Its default value is "0", so set it to "1" to enable this functionality::
+ Its default value is "0", so set it to "1" to enable this functionality:
+
+ .. code-block:: bitbake
UBOOT_FIT_TEE = "1"
:term:`UBOOT_FIT_TEE_IMAGE`
Specifies the path to the Trusted Execution Environment (TEE) binary. Its
- default value is "tee-raw.bin"::
+ default value is "tee-raw.bin":
+
+ .. code-block:: bitbake
UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"
If a relative path is provided, the file is expected to be relative to
U-Boot's :term:`B` directory. An absolute path can be provided too,
- e.g.::
+ e.g.:
+
+ .. code-block:: bitbake
UBOOT_FIT_TEE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/tee-raw.bin"
@@ -11736,7 +12502,9 @@ system and gives an overview of their function and contents.
recipe, you must add the necessary dependency in a U-Boot ``.bbappend``
file. The recipe name for Trusted Execution Environment (TEE) binary is
``optee-os``, which comes from the :yocto_git:`meta-arm </meta-arm>`
- layer::
+ layer:
+
+ .. code-block:: bitbake
do_compile[depends] += "optee-os:do_deploy"
@@ -11764,7 +12532,9 @@ system and gives an overview of their function and contents.
};
};
- Users can include their custom ITS snippet in this variable, e.g.::
+ Users can include their custom ITS snippet in this variable, e.g.:
+
+ .. code-block:: bitbake
UBOOT_FIT_FWA_ITS = '\
fwa {\n\
@@ -11817,7 +12587,9 @@ system and gives an overview of their function and contents.
This variable allows to generate a FIT image for U-Boot, which is one
of the ways to implement a verified boot process.
- Its default value is "0", so set it to "1" to enable this functionality::
+ Its default value is "0", so set it to "1" to enable this functionality:
+
+ .. code-block:: bitbake
UBOOT_FITIMAGE_ENABLE = "1"
@@ -11829,7 +12601,9 @@ system and gives an overview of their function and contents.
These fragments are located in same ``${S}/configs/`` directory as the
defconfig.
- For example::
+ For example:
+
+ .. code-block:: bitbake
UBOOT_MACHINE = "am62x_evm_r5_defconfig"
UBOOT_FRAGMENTS = "am62x_r5_usbdfu.config"
@@ -11840,7 +12614,9 @@ system and gives an overview of their function and contents.
This variable enables the generation of the U-Boot initial environment in
binary format.
- Its default value is "0", set it to "1" to enable this functionality::
+ Its default value is "0", set it to "1" to enable this functionality:
+
+ .. code-block:: bitbake
UBOOT_INITIAL_ENV_BINARY = "1"
@@ -11864,7 +12640,9 @@ system and gives an overview of their function and contents.
this variable should be set to properly generate the redundant environment
in the output U-boot environment binary file.
- Its default value is "0", set it to "1" to enable this functionality::
+ Its default value is "0", set it to "1" to enable this functionality:
+
+ .. code-block:: bitbake
UBOOT_INITIAL_ENV_BINARY_REDUND = "1"
@@ -11876,7 +12654,9 @@ system and gives an overview of their function and contents.
:term:`UBOOT_INITIAL_ENV_BINARY_SIZE`
This variable sets the binary size (in bytes) of the U-Boot initial
environment. Both hexadecimal and decimal values are supported and can be
- set as follows::
+ set as follows:
+
+ .. code-block:: bitbake
UBOOT_INITIAL_ENV_BINARY_SIZE = "0x4000"
@@ -11901,7 +12681,9 @@ system and gives an overview of their function and contents.
Appends a string to the name of the local version of the U-Boot
image. For example, assuming the version of the U-Boot image built
was "2013.10", the full version string reported by U-Boot would be
- "2013.10-yocto" given the following statement::
+ "2013.10-yocto" given the following statement:
+
+ .. code-block:: bitbake
UBOOT_LOCALVERSION = "-yocto"
@@ -12068,7 +12850,9 @@ system and gives an overview of their function and contents.
:term:`UNINATIVE_CHECKSUM` variable flags contain the checksums of the
uninative tarball as specified by the :term:`UNINATIVE_URL` variable.
There should be one checksum per tarballs published at
- :term:`UNINATIVE_URL`, which match architectures. For example::
+ :term:`UNINATIVE_URL`, which match architectures. For example:
+
+ .. code-block:: bitbake
UNINATIVE_CHECKSUM[aarch64] ?= "812045d826b7fda88944055e8526b95a5a9440bfef608d5b53fd52faab49bf85"
UNINATIVE_CHECKSUM[i686] ?= "5cc28efd0c15a75de4bcb147c6cce65f1c1c9d442173a220f08427f40a3ffa09"
@@ -12117,7 +12901,9 @@ system and gives an overview of their function and contents.
releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS`
to ``1`` in the recipe, and the OpenEmbedded build system
will compare the latest commit with the one currently specified
- by the recipe (:term:`SRCREV`)::
+ by the recipe (:term:`SRCREV`):
+
+ .. code-block:: bitbake
UPSTREAM_CHECK_COMMITS = "1"
@@ -12130,7 +12916,9 @@ system and gives an overview of their function and contents.
You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a
regular expression to filter only the relevant tags should the
- default filter not work correctly::
+ default filter not work correctly:
+
+ .. code-block:: bitbake
UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
@@ -12138,7 +12926,9 @@ system and gives an overview of their function and contents.
Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different
regular expression instead of the default one when the package
checking system is parsing the page found using
- :term:`UPSTREAM_CHECK_URI`::
+ :term:`UPSTREAM_CHECK_URI`:
+
+ .. code-block:: bitbake
UPSTREAM_CHECK_REGEX = "package_regex"
@@ -12149,7 +12939,9 @@ system and gives an overview of their function and contents.
determined by fetching the directory listing where the tarball is and
attempting to find a later tarball. When this approach does not work,
you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that
- contains the link to the latest tarball::
+ contains the link to the latest tarball:
+
+ .. code-block:: bitbake
UPSTREAM_CHECK_URI = "recipe_url"
@@ -12179,7 +12971,9 @@ system and gives an overview of their function and contents.
:term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in
the recipe allows to determine what the latest upstream version is,
you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe
- to acknowledge that the check cannot be performed::
+ to acknowledge that the check cannot be performed:
+
+ .. code-block:: bitbake
UPSTREAM_VERSION_UNKNOWN = "1"
@@ -12225,7 +13019,9 @@ system and gives an overview of their function and contents.
Classes inherited using :term:`USER_CLASSES` must be located in the
``classes-global/`` or ``classes/`` subdirectories.
- The default list is set in your ``local.conf`` file::
+ The default list is set in your ``local.conf`` file:
+
+ .. code-block:: bitbake
USER_CLASSES ?= "buildstats"
@@ -12252,7 +13048,9 @@ system and gives an overview of their function and contents.
:term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan
on using statically assigned ``gid`` and ``uid`` values, you should
set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf``
- file as follows::
+ file as follows:
+
+ .. code-block:: bitbake
USERADD_ERROR_DYNAMIC = "error"
@@ -12282,8 +13080,9 @@ system and gives an overview of their function and contents.
When applying static group identification (``gid``) values, the
OpenEmbedded build system looks in :term:`BBPATH` for a
``files/group`` file and then applies those ``uid`` values. Set the
- variable as follows in your ``local.conf`` file::
+ variable as follows in your ``local.conf`` file:
+ .. code-block:: bitbake
USERADD_GID_TABLES = "files/group"
@@ -12299,7 +13098,9 @@ system and gives an overview of their function and contents.
You must set this variable if the recipe inherits the class. For
example, the following enables adding a user for the main package in
- a recipe::
+ a recipe:
+
+ .. code-block:: bitbake
USERADD_PACKAGES = "${PN}"
@@ -12315,7 +13116,9 @@ system and gives an overview of their function and contents.
the ``useradd`` command if you add a user to the system when the
package is installed.
- Here is an example from the ``dbus`` recipe::
+ Here is an example from the ``dbus`` recipe:
+
+ .. code-block:: bitbake
USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \
--no-create-home --shell /bin/false \
@@ -12333,7 +13136,9 @@ system and gives an overview of their function and contents.
When applying static user identification (``uid``) values, the
OpenEmbedded build system looks in :term:`BBPATH` for a
``files/passwd`` file and then applies those ``uid`` values. Set the
- variable as follows in your ``local.conf`` file::
+ variable as follows in your ``local.conf`` file:
+
+ .. code-block:: bitbake
USERADD_UID_TABLES = "files/passwd"
@@ -12368,7 +13173,9 @@ system and gives an overview of their function and contents.
When a recipe inherits the :ref:`ref-classes-useradd` class, this variable
specifies for a package what parameters should be passed to the ``usermod``
command if you wish to modify a user when the package is installed.
- Is is typically used to add the user to one or more groups. For example::
+ Is is typically used to add the user to one or more groups. For example:
+
+ .. code-block:: bitbake
USERMOD_PARAM:${PN} = "--append --groups group1,group2 user"
@@ -12378,24 +13185,32 @@ system and gives an overview of their function and contents.
or in image definitions.
An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible
- to either use BusyBox based utilities::
+ to either use BusyBox based utilities:
+
+ .. code-block:: bitbake
VIRTUAL-RUNTIME_base-utils = "busybox"
or their full featured implementations from GNU Coreutils
- and other projects::
+ and other projects:
+
+ .. code-block:: bitbake
VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils"
Here are two examples using this virtual runtime package. The
first one is in :oe_git:`initramfs-framework_1.0.bb
- </openembedded-core/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb>`::
+ </openembedded-core/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb>`:
+
+ .. code-block:: bitbake
RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}"
The second example is in the :oe_git:`core-image-initramfs-boot
</openembedded-core/tree/meta/recipes-core/images/core-image-initramfs-boot.bb>`
- image definition::
+ image definition:
+
+ .. code-block:: bitbake
PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd"
@@ -12485,7 +13300,9 @@ system and gives an overview of their function and contents.
With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to
specify a list of additional dependencies (e.g. native tools,
bootloaders, and so forth), that are required to build Wic images.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
WKS_FILE_DEPENDS = "some-native-tool"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 02/10] ref-manual: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
2026-08-26 1:34 ` [PATCH 01/10] ref-manual/variables.rst: use the bitbake code-block language Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 03/10] dev-manual: " Trevor Woerner
` (10 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 62 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
documentation/ref-manual/classes.rst | 168 +++++++++++++-----
.../ref-manual/devtool-reference.rst | 4 +-
documentation/ref-manual/faq.rst | 20 ++-
documentation/ref-manual/features.rst | 12 +-
documentation/ref-manual/qa-checks.rst | 20 ++-
documentation/ref-manual/tasks.rst | 20 ++-
6 files changed, 183 insertions(+), 61 deletions(-)
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index f3d1aa64e703..5dec5008ec3f 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -206,11 +206,15 @@ package in the :term:`SRC_URI` variable and inheriting this class.
For RPMs and other packages that do not contain a subdirectory, you should set
the :term:`SRC_URI` option ``subdir`` to :term:`BP` so that the contents are
extracted to the directory expected by the default value of :term:`S`. For
-example::
+example:
+
+.. code-block:: bitbake
SRC_URI = "https://example.com/downloads/somepackage.rpm;subdir=${BP}"
-This class can also be used for tarballs. For example::
+This class can also be used for tarballs. For example:
+
+.. code-block:: bitbake
SRC_URI = "file://somepackage.tar.xz;subdir=${BP}"
@@ -372,7 +376,9 @@ make it inherit the :ref:`ref-classes-cargo` and
bitbake -c update_crates recipe
This creates a ``recipe-crates.inc`` file that you can include in your
-recipe::
+recipe:
+
+.. code-block:: bitbake
require ${BPN}-crates.inc
@@ -395,7 +401,9 @@ files between builds.
Recipes (including :ref:`ref-classes-native` ones) can make use of the host's
``ccache`` binary (via :term:`HOSTTOOLS`) if the following configuration
-statements are provided in a :term:`configuration file`::
+statements are provided in a :term:`configuration file`:
+
+.. code-block:: bitbake
ASSUME_PROVIDED += "ccache-native"
HOSTTOOLS += "ccache"
@@ -549,7 +557,9 @@ The :ref:`ref-classes-create-spdx` class provides support for
automatically creating :term:`SPDX` :term:`SBOM` documents based upon image
and SDK contents.
-This class is meant to be inherited globally from a configuration file::
+This class is meant to be inherited globally from a configuration file:
+
+.. code-block:: bitbake
INHERIT += "create-spdx"
@@ -702,7 +712,9 @@ information about using :ref:`ref-classes-devshell`.
The :ref:`ref-classes-devupstream` class uses
:term:`BBCLASSEXTEND` to add a variant of the
recipe that fetches from an alternative URI (e.g. Git) instead of a
-tarball. Here is an example::
+tarball. Here is an example:
+
+.. code-block:: bitbake
BBCLASSEXTEND = "devupstream:target"
SRC_URI:class-devupstream = "git://git.example.com/example;branch=main"
@@ -712,7 +724,9 @@ Adding the above statements to your recipe creates a variant that has
:term:`DEFAULT_PREFERENCE` set to "-1".
Consequently, you need to select the variant of the recipe to use it.
Any development-specific adjustments can be done by using the
-``class-devupstream`` override. Here is an example::
+``class-devupstream`` override. Here is an example:
+
+.. code-block:: bitbake
DEPENDS:append:class-devupstream = " gperf-native"
do_configure:prepend:class-devupstream() {
@@ -785,7 +799,9 @@ be performed using the
whole. Use the :ref:`ref-classes-useradd` class to add user and group
configuration to a specific recipe.
-Here is an example that uses this class in an image recipe::
+Here is an example that uses this class in an image recipe:
+
+.. code-block:: bitbake
inherit extrausers
EXTRA_USERS_PARAMS = "\
@@ -802,7 +818,9 @@ passwords. First on host, create the (escaped) password hash::
printf "%q" $(mkpasswd -m sha256crypt tester01)
-The resulting hash is set to a variable and used in ``useradd`` command parameters::
+The resulting hash is set to a variable and used in ``useradd`` command parameters:
+
+.. code-block:: bitbake
inherit extrausers
PASSWD = "\$X\$ABC123\$A-Long-Hash"
@@ -811,7 +829,9 @@ The resulting hash is set to a variable and used in ``useradd`` command paramete
useradd -p '${PASSWD}' tester-sue; \
"
-Finally, here is an example that sets the root password::
+Finally, here is an example that sets the root password:
+
+.. code-block:: bitbake
inherit extrausers
EXTRA_USERS_PARAMS = "\
@@ -1046,7 +1066,9 @@ specific override names are defined as ``grub_LABEL``.
For example, for a label ``factory``, the override name would be
``grub_factory``. A custom GRUB menu entry titled "Factory Install" with the
-additional parameter ``factory=yes`` can be achieved as follows::
+additional parameter ``factory=yes`` can be achieved as follows:
+
+.. code-block:: bitbake
LABELS:append = " factory"
APPEND:grub_factory = "factory=yes"
@@ -1277,7 +1299,9 @@ configuration). However, to skip one or more checks in recipes, you
should use :term:`INSANE_SKIP`. For example, to skip
the check for symbolic link ``.so`` files in the main package of a
recipe, add the following to the recipe. You need to realize that the
-package name override, in this example ``${PN}``, must be used::
+package name override, in this example ``${PN}``, must be used:
+
+.. code-block:: bitbake
INSANE_SKIP:${PN} += "dev-so"
@@ -1370,7 +1394,9 @@ The :ref:`ref-classes-kernel-fit-extra-artifacts` class exposes the required ker
artifacts to the :term:`DEPLOY_DIR_IMAGE` which are used by the
:ref:`ref-classes-kernel-fit-image` class to create the FIT image.
-The simplest example for building a FIT image is to add::
+The simplest example for building a FIT image is to add:
+
+.. code-block:: bitbake
KERNEL_CLASSES += "kernel-fit-extra-artifacts"
@@ -1383,7 +1409,9 @@ directory and a ``linux-yocto-fitimage`` package which can be installed.
The same approach works for all variants of the ``linux-yocto`` kernel.
For example, if the ``linux-yocto-rt`` kernel should be used, add the following
-lines to the machine configuration file::
+lines to the machine configuration file:
+
+.. code-block:: bitbake
KERNEL_CLASSES += "kernel-fit-extra-artifacts"
PREFERRED_PROVIDER_virtual/kernel = "linux-yocto-rt"
@@ -1460,7 +1488,9 @@ allow configuration:
U-Boot commands. When using a boot script the recipe which inherits the
:ref:`ref-classes-kernel-fit-image` class should add the script to
:term:`SRC_URI` and set the :term:`FIT_UBOOT_ENV` variable to the name of the
- file like the following::
+ file like the following:
+
+ .. code-block:: bitbake
FIT_UBOOT_ENV = "boot.txt"
SRC_URI += "file://${FIT_UBOOT_ENV}"
@@ -1504,7 +1534,9 @@ variable in your kernel recipe or machine configuration when building FIT images
It ensures that all necessary files are available for packaging into the FIT image,
such as the kernel binary, device tree blobs (DTBs), and other related files.
-For example, to enable this class, set::
+For example, to enable this class, set:
+
+.. code-block:: bitbake
KERNEL_CLASSES += "kernel-fit-extra-artifacts"
@@ -1780,7 +1812,9 @@ a couple different ways:
caused by existing code that depends on that naming convention.
- Or, create a :ref:`ref-classes-native` variant of any target recipe (e.g.
- ``myrecipe.bb``) by adding the following to the recipe::
+ ``myrecipe.bb``) by adding the following to the recipe:
+
+ .. code-block:: bitbake
BBCLASSEXTEND = "native"
@@ -1822,7 +1856,9 @@ couple different ways:
depends on the naming convention.
- Or, create a :ref:`ref-classes-nativesdk` variant of any target recipe (e.g.
- ``myrecipe.bb``) by adding the following to the recipe::
+ ``myrecipe.bb``) by adding the following to the recipe:
+
+ .. code-block:: bitbake
BBCLASSEXTEND = "nativesdk"
@@ -1889,7 +1925,9 @@ root filesystem read-only.
To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper
layer in your machine configuration. The underlying file system can be anything that
-is supported by ``overlayfs``. This has to be done in your machine configuration::
+is supported by ``overlayfs``. This has to be done in your machine configuration:
+
+.. code-block:: bitbake
OVERLAYFS_MOUNT_POINT[data] = "/data"
@@ -1903,7 +1941,9 @@ is supported by ``overlayfs``. This has to be done in your machine configuration
The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
-Then you can specify writable directories on a recipe basis (e.g. in my-application.bb)::
+Then you can specify writable directories on a recipe basis (e.g. in my-application.bb):
+
+.. code-block:: bitbake
OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
@@ -1912,11 +1952,15 @@ want to have a writable location on the file system, but do not need that the da
survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs``
file system.
-In your machine configuration::
+In your machine configuration:
+
+.. code-block:: bitbake
OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
-and then in your recipe::
+and then in your recipe:
+
+.. code-block:: bitbake
OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
@@ -1948,7 +1992,9 @@ boot stage is required. The idea is to supply a custom init script that mounts
``/etc`` before launching the actual init program, because the latter already
requires ``/etc`` to be mounted.
-Example usage in image recipe::
+Example usage in image recipe:
+
+.. code-block:: bitbake
IMAGE_FEATURES += "overlayfs-etc"
@@ -1957,14 +2003,18 @@ Example usage in image recipe::
This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`
Your machine configuration should define at least the device, mount point, and file system type
-you are going to use for ``overlayfs``::
+you are going to use for ``overlayfs``:
+
+.. code-block:: bitbake
OVERLAYFS_ETC_MOUNT_POINT = "/data"
OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
OVERLAYFS_ETC_FSTYPE ?= "ext4"
To control more mount options you should consider setting mount options
-(``defaults`` is used by default)::
+(``defaults`` is used by default):
+
+.. code-block:: bitbake
OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
@@ -1976,7 +2026,9 @@ The class provides two options for ``/sbin/init`` generation:
but it poses a restriction that package-management can't be used, because updating
the init manager would remove the generated script.
-- If you wish to keep original init as is, you can set::
+- If you wish to keep original init as is, you can set:
+
+ .. code-block:: bitbake
OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
@@ -1994,7 +2046,9 @@ before attempting to fetch it from the upstream specified in
:term:`SRC_URI` within each recipe.
To use this class, inherit it globally and specify
-:term:`SOURCE_MIRROR_URL`. Here is an example::
+:term:`SOURCE_MIRROR_URL`. Here is an example:
+
+.. code-block:: bitbake
INHERIT += "own-mirrors"
SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
@@ -2129,7 +2183,9 @@ Previously, this class was called the ``task`` class.
.. note::
- If you're defining a packagegroup and need to set::
+ If you're defining a packagegroup and need to set:
+
+ .. code-block:: bitbake
PACKAGE_ARCH = "${MACHINE_ARCH}"
@@ -2563,7 +2619,9 @@ installed by ``libtool``. Removing these files results in them being
absent from both the sysroot and target packages.
If a recipe needs the ``.la`` files to be installed, then the recipe can
-override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
+override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:
+
+.. code-block:: bitbake
REMOVE_LIBTOOL_LA = "0"
@@ -2596,7 +2654,9 @@ directory for a recipe when one of its tasks fails, or any other nominated
directories. It is useful in cases where the environment in which builds are run
is ephemeral or otherwise inaccessible for examination during debugging.
-To enable, add the following to your configuration::
+To enable, add the following to your configuration:
+
+.. code-block:: bitbake
INHERIT += "retain"
@@ -2619,7 +2679,9 @@ recipe are no longer needed. However, by default, the build system
preserves these files for inspection and possible debugging purposes. If
you would rather have these files deleted to save disk space as the build
progresses, you can enable :ref:`ref-classes-rm-work` by adding the following to
-your ``local.conf`` file, which is found in the :term:`Build Directory`::
+your ``local.conf`` file, which is found in the :term:`Build Directory`:
+
+.. code-block:: bitbake
INHERIT += "rm_work"
@@ -2628,14 +2690,18 @@ recipe, enabling :ref:`ref-classes-rm-work` will potentially result in your
changes to the source being lost. To exclude some recipes from having their work
directories deleted by :ref:`ref-classes-rm-work`, you can add the names of the
recipe or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable,
-which can also be set in your ``local.conf`` file. Here is an example::
+which can also be set in your ``local.conf`` file. Here is an example:
+
+.. code-block:: bitbake
RM_WORK_EXCLUDE += "busybox glibc"
Finally, if you are using this class for a recipe but want to prevent
:term:`BitBake` from deleting specific folders or files in that recipe's
:term:`WORKDIR` (other than ``temp``), you can preserve those folders or
-files with the :term:`RM_WORK_EXCLUDE_ITEMS` variable as follows::
+files with the :term:`RM_WORK_EXCLUDE_ITEMS` variable as follows:
+
+.. code-block:: bitbake
RM_WORK_EXCLUDE_ITEMS += "items_to_keep"
@@ -3064,7 +3130,9 @@ You should set :term:`SYSTEMD_SERVICE` to the
name of the service file. You should also use a package name override to
indicate the package to which the value applies. If the value applies to
the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
-is an example from the connman recipe::
+is an example from the connman recipe:
+
+.. code-block:: bitbake
SYSTEMD_SERVICE:${PN} = "connman.service"
@@ -3144,7 +3212,9 @@ images using QEMU and on actual hardware. The classes handle loading the
tests and starting the image. To use the classes, you need to perform
steps to set up the environment.
-To enable this class, add the following to your configuration::
+To enable this class, add the following to your configuration:
+
+.. code-block:: bitbake
IMAGE_CLASSES += "testimage"
@@ -3157,7 +3227,9 @@ following::
$ bitbake -c testimage image
Alternatively, if you wish to have tests automatically run for each image
-after it is built, you can set :term:`TESTIMAGE_AUTO`::
+after it is built, you can set :term:`TESTIMAGE_AUTO`:
+
+.. code-block:: bitbake
TESTIMAGE_AUTO = "1"
@@ -3310,7 +3382,9 @@ This class should not be inherited directly. It is inherited by the
The :ref:`ref-classes-typecheck` class provides support for validating the values of
variables set at the configuration level against their defined types.
The OpenEmbedded build system allows you to define the type of a
-variable using the "type" varflag. Here is an example::
+variable using the "type" varflag. Here is an example:
+
+.. code-block:: bitbake
IMAGE_FEATURES[type] = "list"
@@ -3325,12 +3399,16 @@ or more U-Boot build configurations.
There are three ways to configure the recipe for your machine:
- Using the :term:`UBOOT_MACHINE` variable (and its companion variable
- :term:`UBOOT_BINARY`). For example::
+ :term:`UBOOT_BINARY`). For example:
+
+ .. code-block:: bitbake
UBOOT_MACHINE = "config"
UBOOT_BINARY = "u-boot.bin"
-- Using :term:`UBOOT_CONFIG` variables. For example::
+- Using :term:`UBOOT_CONFIG` variables. For example:
+
+ .. code-block:: bitbake
UBOOT_CONFIG ??= "foo bar"
UBOOT_CONFIG[foo] = "config"
@@ -3348,7 +3426,9 @@ There are three ways to configure the recipe for your machine:
In this example, all possible configurations are selected (``foo`` and
``bar``), but it is also possible to build only ``foo`` or ``bar`` by
changing the value of :term:`UBOOT_CONFIG` to include either one or the
- other. For exmaple::
+ other. For exmaple:
+
+ .. code-block:: bitbake
UBOOT_CONFIG = "foo"
UBOOT_CONFIG[foo] = "config"
@@ -3415,7 +3495,9 @@ There are three ways to configure the recipe for your machine:
See the documentation of :term:`UBOOT_CONFIG_FRAGMENTS` for more information.
- Or, a legacy method using the :term:`UBOOT_CONFIG` variable by itself.
- *This method is being deprecated, see note below.* For example::
+ *This method is being deprecated, see note below.* For example:
+
+ .. code-block:: bitbake
UBOOT_CONFIG ??= "foo bar"
UBOOT_CONFIG[foo] = "config,images,binary"
@@ -3797,7 +3879,9 @@ The :ref:`ref-classes-vex` class is used to generate metadata needed by external
tools to check for vulnerabilities, for example CVEs.
In order to use this class, inherit the class in the ``local.conf`` file and it
-will add the ``generate_vex`` task for every recipe::
+will add the ``generate_vex`` task for every recipe:
+
+.. code-block:: bitbake
INHERIT += "vex"
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 6b21d302ff7e..dd3849e0e053 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -391,7 +391,9 @@ want to use it because the dependency on ``cdebconf`` is not easily
satisfied. Maintainers can explicit the reason that is shown by adding
the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe.
See the :oe_git:`base-passwd_*.bb </openembedded-core/tree/meta/recipes-core/base-passwd/>`
-recipe for an example::
+recipe for an example:
+
+.. code-block:: bitbake
RECIPE_NO_UPDATE_REASON = "Version 3.5.38 requires cdebconf for update-passwd utility"
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index 374ecf8e887f..0b7814589660 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -120,7 +120,9 @@ fail.
As an example, you could add a specific server for the build system to
attempt before any others by adding something like the following to the
-``local.conf`` configuration file::
+``local.conf`` configuration file:
+
+.. code-block:: bitbake
PREMIRRORS:prepend = "\
git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
@@ -134,7 +136,9 @@ HTTPS requests and direct them to the ``http://`` sources mirror. You
can use ``file://`` URLs to point to local directories or network shares
as well.
-Another option is to set::
+Another option is to set:
+
+.. code-block:: bitbake
BB_NO_NETWORK = "1"
@@ -142,7 +146,9 @@ This statement tells BitBake to issue an error
instead of trying to access the Internet. This technique is useful if
you want to ensure code builds only from local sources.
-Here is another technique::
+Here is another technique:
+
+.. code-block:: bitbake
BB_FETCH_PREMIRRORONLY = "1"
@@ -150,7 +156,9 @@ This statement limits the build system to pulling source from the
:term:`PREMIRRORS` only. Again, this technique is useful for reproducing
builds.
-Here is yet another technique::
+Here is yet another technique:
+
+.. code-block:: bitbake
BB_GENERATE_MIRROR_TARBALLS = "1"
@@ -160,7 +168,9 @@ however, the technique can simply waste time during the build.
Finally, consider an example where you are behind an HTTP-only firewall.
You could make the following changes to the ``local.conf`` configuration
-file as long as the :term:`PREMIRRORS` server is current::
+file as long as the :term:`PREMIRRORS` server is current:
+
+.. code-block:: bitbake
PREMIRRORS:prepend = "\
git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst
index 63d47d6eca16..56337992f264 100644
--- a/documentation/ref-manual/features.rst
+++ b/documentation/ref-manual/features.rst
@@ -390,7 +390,9 @@ these valid features is as follows:
installed, you can either remove ``ssh-server-dropbear`` from
``IMAGE_FEATURES`` and add ``dropbear`` to :term:`IMAGE_INSTALL`
instead, or alternatively still use the feature but set
- :term:`BAD_RECOMMENDATIONS` as follows::
+ :term:`BAD_RECOMMENDATIONS` as follows:
+
+ .. code-block:: bitbake
BAD_RECOMMENDATIONS += "openssh-sftp-server"
@@ -443,7 +445,9 @@ The :term:`DISTRO_FEATURES_OPTED_OUT` and :term:`MACHINE_FEATURES_OPTED_OUT`
variables can be used to remove a feature provided by one of the
:term:`DISTRO_FEATURES_DEFAULTS` of :term:`MACHINE_FEATURES_DEFAULTS` variables.
-For example, the two following assignments::
+For example, the two following assignments:
+
+.. code-block:: bitbake
DISTRO_FEATURES_DEFAULTS = "a b c"
DISTRO_FEATURES_OPTED_OUT = "b"
@@ -454,7 +458,9 @@ Would result in feature ``a`` and feature ``c`` making it to the final value of
You can also opt out of all default features by setting
:term:`DISTRO_FEATURES_OPTED_OUT` or :term:`MACHINE_FEATURES_OPTED_OUT` to
-``*``::
+``*``:
+
+.. code-block:: bitbake
DISTRO_FEATURES_OPTED_OUT = "*"
diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index 09b0f628a74b..49852c1b641d 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -408,7 +408,9 @@ non-UTF-8 characters. Some package managers do not support such characters.
``<package>: invalid PACKAGECONFIG(s): <configs> [invalid-packageconfig]``
Checks that no undefined features are being added to :term:`PACKAGECONFIG`.
-For example, any name "foo" for which the following form does not exist::
+For example, any name "foo" for which the following form does not exist:
+
+.. code-block:: bitbake
PACKAGECONFIG[foo] = "..."
@@ -437,7 +439,9 @@ provided by the build system. Check to be sure that the :term:`LDFLAGS`
variable is being passed to the linker command. A common workaround
for this situation is to pass in :term:`LDFLAGS` using
:term:`TARGET_CC_ARCH` within the recipe as
-follows::
+follows:
+
+.. code-block:: bitbake
TARGET_CC_ARCH += "${LDFLAGS}"
@@ -789,13 +793,17 @@ the private version of the library.
This warning indicated that there is missing spaces around an assignment.
-For example, the following assignments would print a warning::
+For example, the following assignments would print a warning:
+
+.. code-block:: bitbake
FOO="bar"
FOO= "bar"
FOO ="bar"
-These should be replaced by::
+These should be replaced by:
+
+.. code-block:: bitbake
FOO = "bar"
@@ -887,7 +895,9 @@ runtime.
Typically, the way to solve this performance issue is to add "-fPIC"
or "-fpic" to the compiler command-line options. For example, given
software that reads :term:`CFLAGS` when you build it,
-you could add the following to your recipe::
+you could add the following to your recipe:
+
+.. code-block:: bitbake
CFLAGS:append = " -fPIC"
diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst
index 3517d0b91456..405254c7b3a9 100644
--- a/documentation/ref-manual/tasks.rst
+++ b/documentation/ref-manual/tasks.rst
@@ -120,7 +120,9 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``.
The :ref:`ref-tasks-deploy` task is not added as a task by default and
consequently needs to be added manually. If you want the task to run
after :ref:`ref-tasks-compile`, you can add it by doing
-the following::
+the following:
+
+.. code-block:: bitbake
addtask deploy after do_compile
@@ -129,7 +131,9 @@ Adding :ref:`ref-tasks-deploy` after other tasks works the same way.
.. note::
You do not need to add ``before do_build`` to the ``addtask`` command
- (though it is harmless), because the :ref:`ref-classes-base` class contains the following::
+ (though it is harmless), because the :ref:`ref-classes-base` class contains the following:
+
+ .. code-block:: bitbake
do_build[recrdeptask] += "do_deploy"
@@ -335,7 +339,9 @@ and patch files needed to build the package.
As mentioned earlier, the build system treats files whose file types are
``.patch`` and ``.diff`` as patch files. However, you can use the
"apply=yes" parameter with the :term:`SRC_URI` statement to indicate any
-file as a patch file::
+file as a patch file:
+
+.. code-block:: bitbake
SRC_URI = " \
git://path_to_repo/some_package \
@@ -345,7 +351,9 @@ file as a patch file::
Conversely, if you have a file whose file type is ``.patch`` or ``.diff``
and you want to exclude it so that the :ref:`ref-tasks-patch` task does not apply
it during the patch phase, you can use the "apply=no" parameter with the
-:term:`SRC_URI` statement::
+:term:`SRC_URI` statement:
+
+.. code-block:: bitbake
SRC_URI = " \
git://path_to_repo/some_package \
@@ -468,7 +476,9 @@ recipe and would be invoked with:
$ bitbake -c listtasks recipename
-A typical definition of a manually-called task would look like::
+A typical definition of a manually-called task would look like:
+
+.. code-block:: bitbake
addtask listtasks
do_listtasks[nostamp] = "1"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 03/10] dev-manual: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
2026-08-26 1:34 ` [PATCH 01/10] ref-manual/variables.rst: use the bitbake code-block language Trevor Woerner
2026-08-26 1:34 ` [PATCH 02/10] ref-manual: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 04/10] migration-guides: " Trevor Woerner
` (9 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 176 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
documentation/dev-manual/bblock.rst | 4 +-
documentation/dev-manual/bmaptool.rst | 4 +-
documentation/dev-manual/build-quality.rst | 8 +-
documentation/dev-manual/building.rst | 44 +++--
.../dev-manual/creating-fragments.rst | 6 +-
.../dev-manual/custom-distribution.rst | 4 +-
.../dev-manual/customizing-images.rst | 32 +++-
documentation/dev-manual/debugging.rst | 40 +++--
documentation/dev-manual/device-manager.rst | 12 +-
documentation/dev-manual/devtool.rst | 8 +-
documentation/dev-manual/disk-space.rst | 4 +-
.../dev-manual/error-reporting-tool.rst | 12 +-
documentation/dev-manual/external-scm.rst | 20 ++-
.../dev-manual/gobject-introspection.rst | 12 +-
documentation/dev-manual/hashequivserver.rst | 12 +-
documentation/dev-manual/init-manager.rst | 16 +-
documentation/dev-manual/layers.rst | 56 ++++--
documentation/dev-manual/libraries.rst | 12 +-
documentation/dev-manual/licenses.rst | 60 +++++--
.../dev-manual/limiting-resources.rst | 4 +-
documentation/dev-manual/multiconfig.rst | 40 +++--
documentation/dev-manual/new-machine.rst | 4 +-
documentation/dev-manual/new-recipe.rst | 160 +++++++++++++-----
documentation/dev-manual/packages.rst | 44 +++--
.../dev-manual/poky-manual-setup.rst | 4 +-
.../dev-manual/prebuilt-libraries.rst | 12 +-
documentation/dev-manual/qemu.rst | 4 +-
documentation/dev-manual/quilt.rst | 4 +-
documentation/dev-manual/sbom.rst | 4 +-
.../dev-manual/speeding-up-build.rst | 4 +-
.../dev-manual/sstate-mirrors-setup.rst | 16 +-
.../dev-manual/temporary-source-code.rst | 8 +-
.../dev-manual/upgrading-recipes.rst | 12 +-
documentation/dev-manual/wayland.rst | 8 +-
documentation/dev-manual/x32-psabi.rst | 4 +-
35 files changed, 522 insertions(+), 176 deletions(-)
diff --git a/documentation/dev-manual/bblock.rst b/documentation/dev-manual/bblock.rst
index 605bb7565524..a6ca740c5123 100644
--- a/documentation/dev-manual/bblock.rst
+++ b/documentation/dev-manual/bblock.rst
@@ -87,7 +87,9 @@ Locking mechanism
variables: :term:`SIGGEN_LOCKEDSIGS`, :term:`SIGGEN_LOCKEDSIGS_TYPES`
and :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`.
-In particular, ``bblock`` sets::
+In particular, ``bblock`` sets:
+
+.. code-block:: bitbake
SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info"
SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}"
diff --git a/documentation/dev-manual/bmaptool.rst b/documentation/dev-manual/bmaptool.rst
index 29e7f0d2ebbd..8fd949eea2a2 100644
--- a/documentation/dev-manual/bmaptool.rst
+++ b/documentation/dev-manual/bmaptool.rst
@@ -29,7 +29,9 @@ that while this example uses a Wic image, you can use `bmaptool` to flash
any type of image. Use these steps to flash an image using `bmaptool`:
#. *Update your local.conf File:* You need to have the following set
- in your ``local.conf`` file before building your image::
+ in your ``local.conf`` file before building your image:
+
+ .. code-block:: bitbake
IMAGE_FSTYPES += "wic wic.bmap"
diff --git a/documentation/dev-manual/build-quality.rst b/documentation/dev-manual/build-quality.rst
index e9b066c4453f..6682122d4ee4 100644
--- a/documentation/dev-manual/build-quality.rst
+++ b/documentation/dev-manual/build-quality.rst
@@ -36,7 +36,9 @@ Enabling and Disabling Build History
Build history is disabled by default. To enable it, add the following
:term:`INHERIT` statement and set the :term:`BUILDHISTORY_COMMIT` variable to
"1" at the end of your ``conf/local.conf`` file found in the
-:term:`Build Directory`::
+:term:`Build Directory`:
+
+.. code-block:: bitbake
INHERIT += "buildhistory"
BUILDHISTORY_COMMIT = "1"
@@ -261,7 +263,9 @@ image. If you are just interested in this information and not interested
in collecting specific package or SDK information, you can enable
writing only image information without any history by adding the
following to your ``conf/local.conf`` file found in the
-:term:`Build Directory`::
+:term:`Build Directory`:
+
+.. code-block:: bitbake
INHERIT += "buildhistory"
BUILDHISTORY_COMMIT = "0"
diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst
index 60cb22785725..cb073a2be5ad 100644
--- a/documentation/dev-manual/building.rst
+++ b/documentation/dev-manual/building.rst
@@ -230,14 +230,18 @@ To achieve this, you need to perform some additional steps:
#. *Create a multiconfig for your Initramfs image:* You can perform the steps
on ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" to create a separate multiconfig.
For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and
- contains the variables::
+ contains the variables:
+
+ .. code-block:: bitbake
TMPDIR = "${TOPDIR}/tmp-initramfscfg"
TCLIBC = "musl"
#. *Set additional Initramfs variables on your main configuration:*
Additionally, on your main configuration (``local.conf``) you need to set the
- variables::
+ variables:
+
+ .. code-block:: bitbake
INITRAMFS_MULTICONFIG = "initramfscfg"
INITRAMFS_DEPLOY_DIR_IMAGE = "${TOPDIR}/tmp-initramfscfg/deploy/images/${MACHINE}"
@@ -416,7 +420,9 @@ instead of ``udev``.
Use your ``local.conf`` file to make changes. For example, to eliminate
``udev`` and ``glib``, set the following in the local configuration
-file::
+file:
+
+.. code-block:: bitbake
VIRTUAL-RUNTIME_dev_manager = ""
@@ -603,7 +609,9 @@ your tunings to best consider build times and package feed maintenance.
machine-architecture dependent, make sure your recipe enables the
"machine" package architecture through the
:term:`MACHINE_ARCH`
- variable::
+ variable:
+
+ .. code-block:: bitbake
PACKAGE_ARCH = "${MACHINE_ARCH}"
@@ -611,7 +619,9 @@ your tunings to best consider build times and package feed maintenance.
specifically enable a package architecture through the
:term:`PACKAGE_ARCH`, The
OpenEmbedded build system defaults to the
- :term:`TUNE_PKGARCH` setting::
+ :term:`TUNE_PKGARCH` setting:
+
+ .. code-block:: bitbake
PACKAGE_ARCH = "${TUNE_PKGARCH}"
@@ -707,13 +717,17 @@ the external directory and use it as is, not copy it.
To build from software that comes from an external source, all you need to do
is inherit the :ref:`ref-classes-externalsrc` class and then set
the :term:`EXTERNALSRC` variable to point to your external source code. Here
-are the statements to put in your ``local.conf`` file::
+are the statements to put in your ``local.conf`` file:
+
+.. code-block:: bitbake
INHERIT += "externalsrc"
EXTERNALSRC:pn-myrecipe = "path-to-your-source-tree"
This next example shows how to accomplish the same thing by setting
-:term:`EXTERNALSRC` in the recipe itself or in the recipe's append file::
+:term:`EXTERNALSRC` in the recipe itself or in the recipe's append file:
+
+.. code-block:: bitbake
EXTERNALSRC = "path"
EXTERNALSRC_BUILD = "path"
@@ -729,7 +743,9 @@ directory separate from the external source directory as specified by
to have the source built in the same directory in which it resides, or
some other nominated directory, you can set
:term:`EXTERNALSRC_BUILD`
-to point to that directory::
+to point to that directory:
+
+.. code-block:: bitbake
EXTERNALSRC_BUILD:pn-myrecipe = "path-to-your-source-tree"
@@ -757,7 +773,9 @@ Follow these steps to populate your Downloads directory:
an empty location or one that does not yet exist.
#. *Generate Tarballs of the Source Git Repositories:* Edit your
- ``local.conf`` configuration file as follows::
+ ``local.conf`` configuration file as follows:
+
+ .. code-block:: bitbake
DL_DIR = "/home/your-download-dir/"
BB_GENERATE_MIRROR_TARBALLS = "1"
@@ -795,7 +813,9 @@ directory:
#. *Using Local Files Only:* Inside your ``local.conf`` file, add the
:term:`SOURCE_MIRROR_URL` variable, inherit the
:ref:`ref-classes-own-mirrors` class, and add the
- :term:`BB_NO_NETWORK` variable to your ``local.conf``::
+ :term:`BB_NO_NETWORK` variable to your ``local.conf``:
+
+ .. code-block:: bitbake
SOURCE_MIRROR_URL ?= "file:///home/your-download-dir/"
INHERIT += "own-mirrors"
@@ -824,7 +844,9 @@ directory:
The offline build does not work if recipes attempt to find the
latest version of software by setting
:term:`SRCREV` to
- ``${``\ :term:`AUTOREV`\ ``}``::
+ ``${``\ :term:`AUTOREV`\ ``}``:
+
+ .. code-block:: bitbake
SRCREV = "${AUTOREV}"
diff --git a/documentation/dev-manual/creating-fragments.rst b/documentation/dev-manual/creating-fragments.rst
index 8dabd599f13f..ea9ad8eb23dc 100644
--- a/documentation/dev-manual/creating-fragments.rst
+++ b/documentation/dev-manual/creating-fragments.rst
@@ -61,7 +61,7 @@ Build System`:
After creating these variables, our custom fragment should look like the
following:
-.. code-block::
+.. code-block:: bitbake
:caption: custom-fragment.conf
BB_CONF_FRAGMENT_SUMMARY = "This fragment sets a limit of 4 bitbake threads and 4 parsing threads"
@@ -71,7 +71,7 @@ following:
For now, our fragment does not have any additional configuration statement.
Let's add the following assignments to our fragment:
-.. code-block::
+.. code-block:: bitbake
:caption: custom-fragment.conf (continued)
BB_NUMBER_THREADS = "4"
@@ -123,7 +123,7 @@ Adding new :term:`Built-in Fragments <Built-in Fragment>` can be done by
appending the :term:`OE_FRAGMENTS_BUILTIN` variable from your :term:`layer`
configuration file:
-.. code-block::
+.. code-block:: bitbake
:caption: layer.conf
OE_FRAGMENTS_BUILTIN:append = " custom-builtin-fragment:CUSTOM_VARIABLE"
diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst
index 4dafd2725557..1146d5313102 100644
--- a/documentation/dev-manual/custom-distribution.rst
+++ b/documentation/dev-manual/custom-distribution.rst
@@ -87,7 +87,9 @@ layer. The following steps provide some more detail:
file in the :term:`Build Directory`, set your :term:`DISTRO` variable to
point to your distribution's configuration file. For example, if your
distribution's configuration file is named ``mydistro.conf``, then
- you point to it as follows::
+ you point to it as follows:
+
+ .. code-block:: bitbake
DISTRO = "mydistro"
diff --git a/documentation/dev-manual/customizing-images.rst b/documentation/dev-manual/customizing-images.rst
index 6eed9ef56a80..b715f83990fa 100644
--- a/documentation/dev-manual/customizing-images.rst
+++ b/documentation/dev-manual/customizing-images.rst
@@ -18,7 +18,9 @@ variable changes are in effect for every build and consequently affect
all images, which might not be what you require.
To add a package to your image using the local configuration file, use
-the :term:`IMAGE_INSTALL` variable with the ``:append`` operator::
+the :term:`IMAGE_INSTALL` variable with the ``:append`` operator:
+
+.. code-block:: bitbake
IMAGE_INSTALL:append = " strace"
@@ -36,7 +38,9 @@ takes effect.
As shown in its simplest use, ``IMAGE_INSTALL:append`` affects all
images. It is possible to extend the syntax so that the variable applies
-to a specific image only. Here is an example::
+to a specific image only. Here is an example:
+
+.. code-block:: bitbake
IMAGE_INSTALL:append:pn-core-image-minimal = " strace"
@@ -105,7 +109,9 @@ Customizing Images Using Custom .bb Files
You can also customize an image by creating a custom recipe that defines
additional software as part of the image. The following example shows
-the form for the two lines you need::
+the form for the two lines you need:
+
+.. code-block:: bitbake
IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
inherit core-image
@@ -120,7 +126,9 @@ The other method for creating a custom image is to base it on an
existing image. For example, if you want to create an image based on
``core-image-sato`` but add the additional package ``strace`` to the
image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new
-``.bb`` and add the following line to the end of the copy::
+``.bb`` and add the following line to the end of the copy:
+
+.. code-block:: bitbake
IMAGE_INSTALL += "strace"
@@ -151,7 +159,9 @@ in the ``packagegroup-base.bb`` recipe.
Here is a short, fabricated example showing the same basic pieces for a
hypothetical packagegroup defined in ``packagegroup-custom.bb``, where
the variable :term:`PN` is the standard way to abbreviate the reference to
-the full packagegroup name ``packagegroup-custom``::
+the full packagegroup name ``packagegroup-custom``:
+
+.. code-block:: bitbake
DESCRIPTION = "My Custom Package Groups"
@@ -193,11 +203,15 @@ configured hostname written to ``/etc/hostname`` is "qemux86".
You can customize this name by altering the value of the "hostname"
variable in the ``base-files`` recipe using either an append file or a
-configuration file. Use the following in an append file::
+configuration file. Use the following in an append file:
+
+.. code-block:: bitbake
hostname = "myhostname"
-Use the following in a configuration file::
+Use the following in a configuration file:
+
+.. code-block:: bitbake
hostname:pn-base-files = "myhostname"
@@ -212,7 +226,9 @@ you can easily reset the default hostname.
Another point of interest is that if you unset the variable, the image
will have no default hostname in the filesystem. Here is an example that
-unsets the variable in a configuration file::
+unsets the variable in a configuration file:
+
+.. code-block:: bitbake
hostname:pn-base-files = ""
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 3afc17ad4ba2..6ee101721ef8 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -628,7 +628,9 @@ in the log, use the "debug" loglevel.
Here is an example written in Python. The code handles logging for
a function that determines the number of tasks needed to be run. See the
":ref:`ref-tasks-listtasks`"
-section for additional information::
+section for additional information:
+
+.. code-block:: bitbake
python do_listtasks() {
bb.debug(2, "Starting to figure out the task list")
@@ -654,7 +656,9 @@ The syntax you use for recipes written in Bash is similar to that of
recipes written in Python described in the previous section.
Here is an example written in Bash. The code logs the progress of
-the ``do_my_function`` function::
+the ``do_my_function`` function:
+
+.. code-block:: bitbake
do_my_function() {
bbdebug 2 "Running do_my_function"
@@ -861,7 +865,9 @@ The final thing you need to do to implement the fix in the build is to
update the "neard" recipe (i.e. ``neard-0.14.bb``) so that the
:term:`SRC_URI` statement includes
the patch file. The recipe file is in the folder above the patch. Here
-is what the edited :term:`SRC_URI` statement would look like::
+is what the edited :term:`SRC_URI` statement would look like:
+
+.. code-block:: bitbake
SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
file://neard.in \
@@ -943,7 +949,9 @@ To run a ``debuginfod`` server, you need to do the following:
(it already is in :term:`OpenEmbedded-Core (OE-Core)` defaults and
:term:`Poky` reference distribution).
- If not, set in your distro config file or in ``local.conf``::
+ If not, set in your distro config file or in ``local.conf``:
+
+ .. code-block:: bitbake
DISTRO_FEATURES:append = " debuginfod"
@@ -1010,7 +1018,9 @@ debugger.
#. *Configure your build system to construct the companion debug
filesystem:*
- In your ``local.conf`` file, set the following::
+ In your ``local.conf`` file, set the following:
+
+ .. code-block:: bitbake
IMAGE_GEN_DEBUGFS = "1"
IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
@@ -1029,7 +1039,9 @@ debugger.
#. *Configure the system to include gdbserver in the target filesystem:*
- Make the following addition in your ``local.conf`` file::
+ Make the following addition in your ``local.conf`` file:
+
+ .. code-block:: bitbake
EXTRA_IMAGE_FEATURES:append = " tools-debug"
@@ -1165,17 +1177,23 @@ debug on the target hardware.
To support this kind of debugging, you need do the following:
- Ensure that GDB is on the target. You can do this by making
- the following addition to your ``local.conf`` file::
+ the following addition to your ``local.conf`` file:
+
+ .. code-block:: bitbake
EXTRA_IMAGE_FEATURES:append = " tools-debug"
- Ensure that debug symbols are present. You can do so by adding the
- corresponding ``-dbg`` package to :term:`IMAGE_INSTALL`::
+ corresponding ``-dbg`` package to :term:`IMAGE_INSTALL`:
+
+ .. code-block:: bitbake
IMAGE_INSTALL:append = " packagename-dbg"
Alternatively, you can add the following to ``local.conf`` to include
- all the debug symbols::
+ all the debug symbols:
+
+ .. code-block:: bitbake
EXTRA_IMAGE_FEATURES:append = " dbg-pkgs"
@@ -1185,7 +1203,9 @@ To support this kind of debugging, you need do the following:
of optimization used by the compiler. For example, when adding the
following line to your ``local.conf`` file, you will reduce optimization
from :term:`FULL_OPTIMIZATION` of "-O2" to :term:`DEBUG_OPTIMIZATION`
- of "-O -fno-omit-frame-pointer"::
+ of "-O -fno-omit-frame-pointer":
+
+ .. code-block:: bitbake
DEBUG_BUILD = "1"
diff --git a/documentation/dev-manual/device-manager.rst b/documentation/dev-manual/device-manager.rst
index 49fc785feccb..1fa572090804 100644
--- a/documentation/dev-manual/device-manager.rst
+++ b/documentation/dev-manual/device-manager.rst
@@ -23,7 +23,9 @@ Using Persistent and Pre-Populated ``/dev``
To use the static method for device population, you need to set the
:term:`USE_DEVFS` variable to "0"
-as follows::
+as follows:
+
+.. code-block:: bitbake
USE_DEVFS = "0"
@@ -35,7 +37,9 @@ machine or distro configuration file. Alternatively, you can set this
variable in your ``local.conf`` configuration file.
If you do not define the :term:`IMAGE_DEVICE_TABLES` variable, the default
-``device_table-minimal.txt`` is used::
+``device_table-minimal.txt`` is used:
+
+.. code-block:: bitbake
IMAGE_DEVICE_TABLES = "device_table-mymachine.txt"
@@ -47,7 +51,9 @@ Using ``devtmpfs`` and a Device Manager
To use the dynamic method for device population, you need to use (or be
sure to set) the :term:`USE_DEVFS`
-variable to "1", which is the default::
+variable to "1", which is the default:
+
+.. code-block:: bitbake
USE_DEVFS = "1"
diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst
index d67f22277342..2078678a855e 100644
--- a/documentation/dev-manual/devtool.rst
+++ b/documentation/dev-manual/devtool.rst
@@ -981,7 +981,9 @@ the :term:`DEPENDS` variable in the original recipe to include the new
recipe.
If you need to add runtime dependencies, you can do so by adding the
-following to your recipe::
+following to your recipe:
+
+.. code-block:: bitbake
RDEPENDS:${PN} += "dependency1 dependency2 ..."
@@ -1062,7 +1064,9 @@ mind:
the command line, add the variable setting to
:term:`EXTRA_OEMAKE` or
:term:`PACKAGECONFIG_CONFARGS`
- within the recipe. Here is an example using :term:`EXTRA_OEMAKE`::
+ within the recipe. Here is an example using :term:`EXTRA_OEMAKE`:
+
+ .. code-block:: bitbake
EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
diff --git a/documentation/dev-manual/disk-space.rst b/documentation/dev-manual/disk-space.rst
index ba3afa5a2cab..efc7529d9263 100644
--- a/documentation/dev-manual/disk-space.rst
+++ b/documentation/dev-manual/disk-space.rst
@@ -8,7 +8,9 @@ Conserving Disk Space During Builds
To help conserve disk space during builds, you can add the following
statement to your project's ``local.conf`` configuration file found in
-the :term:`Build Directory`::
+the :term:`Build Directory`:
+
+.. code-block:: bitbake
INHERIT += "rm_work"
diff --git a/documentation/dev-manual/error-reporting-tool.rst b/documentation/dev-manual/error-reporting-tool.rst
index 30d1ce2b315b..3b765e30db51 100644
--- a/documentation/dev-manual/error-reporting-tool.rst
+++ b/documentation/dev-manual/error-reporting-tool.rst
@@ -28,14 +28,18 @@ Enabling and Using the Tool
By default, the error reporting tool is disabled. You can enable it by
inheriting the :ref:`ref-classes-report-error` class by adding the
following statement to the end of your ``local.conf`` file in your
-:term:`Build Directory`::
+:term:`Build Directory`:
+
+.. code-block:: bitbake
INHERIT += "report-error"
By default, the error reporting feature stores information in
``${``\ :term:`LOG_DIR`\ ``}/error-report``.
However, you can specify a directory to use by adding the following to
-your ``local.conf`` file::
+your ``local.conf`` file:
+
+.. code-block:: bitbake
ERR_REPORT_DIR = "path"
@@ -70,7 +74,9 @@ Disabling the Tool
To disable the error reporting feature, simply remove or comment out the
following statement from the end of your ``local.conf`` file in your
-:term:`Build Directory`::
+:term:`Build Directory`:
+
+.. code-block:: bitbake
INHERIT += "report-error"
diff --git a/documentation/dev-manual/external-scm.rst b/documentation/dev-manual/external-scm.rst
index e7ab8a4c6b9e..dfdd6853ff68 100644
--- a/documentation/dev-manual/external-scm.rst
+++ b/documentation/dev-manual/external-scm.rst
@@ -13,7 +13,9 @@ Subversion (SVN) and Git.
To enable this behavior, the :term:`PV` of
the recipe needs to include a ``+`` sign in its assignment.
-Here is an example::
+Here is an example:
+
+.. code-block:: bitbake
PV = "1.2.3+git"
@@ -21,7 +23,9 @@ Here is an example::
during the packaging phase.
Then, you can add the following to your
-``local.conf``::
+``local.conf``:
+
+.. code-block:: bitbake
SRCREV:pn-PN = "${AUTOREV}"
@@ -29,17 +33,23 @@ Then, you can add the following to your
which you want to enable automatic source revision updating.
If you do not want to update your local configuration file, you can add
-the following directly to the recipe to finish enabling the feature::
+the following directly to the recipe to finish enabling the feature:
+
+.. code-block:: bitbake
SRCREV = "${AUTOREV}"
The Yocto Project provides a distribution named ``poky-bleeding``, whose
-configuration file contains the line::
+configuration file contains the line:
+
+.. code-block:: bitbake
require conf/distro/include/poky-floating-revisions.inc
This line pulls in the listed include file that defines the set of
-AUTOREV-enabled recipes::
+AUTOREV-enabled recipes:
+
+.. code-block:: bitbake
INHERIT += "poky-bleeding"
diff --git a/documentation/dev-manual/gobject-introspection.rst b/documentation/dev-manual/gobject-introspection.rst
index 8203f17f0177..c57b0a302227 100644
--- a/documentation/dev-manual/gobject-introspection.rst
+++ b/documentation/dev-manual/gobject-introspection.rst
@@ -52,7 +52,9 @@ library package involves the following:
#. Try to build the recipe. If you encounter build errors that look like
something is unable to find ``.so`` libraries, check where these
libraries are located in the source tree and add the following to the
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
GIR_EXTRA_LIBS_PATH = "${B}/something/.libs"
@@ -82,7 +84,9 @@ perhaps QEMU does not work on your build host and target architecture
combination. If so, you can use either of the following methods to
disable GIR file generations:
-- Add the following to your distro configuration::
+- Add the following to your distro configuration:
+
+ .. code-block:: bitbake
DISTRO_FEATURES_OPTED_OUT = "gobject-introspection-data"
@@ -90,7 +94,9 @@ disable GIR file generations:
QEMU but will still enable building introspection tools and libraries
(i.e. building them does not require the use of QEMU).
-- Add the following to your machine configuration::
+- Add the following to your machine configuration:
+
+ .. code-block:: bitbake
MACHINE_FEATURES_OPTED_OUT = "qemu-usermode"
diff --git a/documentation/dev-manual/hashequivserver.rst b/documentation/dev-manual/hashequivserver.rst
index 75b77c30b944..3c1f813cf95f 100644
--- a/documentation/dev-manual/hashequivserver.rst
+++ b/documentation/dev-manual/hashequivserver.rst
@@ -79,7 +79,9 @@ Yocto Project Build Setup
=========================
To use the server started in the previous section, set the following variables
-in a :term:`configuration file`::
+in a :term:`configuration file`:
+
+.. code-block:: bitbake
BB_HASHSERVE = "<bind address>"
BB_SIGNATURE_HANDLER = "OEEquivHash"
@@ -91,7 +93,9 @@ See the documentation of :term:`BB_SIGNATURE_HANDLER` for more details on this
variable.
You can optionally specify an upstream server with :term:`BB_HASHSERVE_UPSTREAM`
-variable. For example::
+variable. For example:
+
+.. code-block:: bitbake
BB_HASHSERVE_UPSTREAM = "wss://hashserv.yoctoproject.org/ws"
@@ -101,7 +105,9 @@ This will make the local server pull hashes from the upstream server. The
To output debugging information on what is happening with Hash Equivalence when
builds are started, you can configure :term:`BitBake` logging as follows from a
-:term:`configuration file`::
+:term:`configuration file`:
+
+.. code-block:: bitbake
BB_LOGCONFIG = "hashequiv.json"
diff --git a/documentation/dev-manual/init-manager.rst b/documentation/dev-manual/init-manager.rst
index c9d344a88bf3..51644df2dd51 100644
--- a/documentation/dev-manual/init-manager.rst
+++ b/documentation/dev-manual/init-manager.rst
@@ -54,7 +54,9 @@ Using SysVinit with udev
=========================
SysVinit with the udev device manager corresponds to the
-default setting in :term:`Poky`. This corresponds to setting::
+default setting in :term:`Poky`. This corresponds to setting:
+
+.. code-block:: bitbake
INIT_MANAGER = "sysvinit"
@@ -63,7 +65,9 @@ Using BusyBox init with BusyBox mdev
BusyBox init with BusyBox mdev is the simplest and lightest solution
for small root filesystems. All you need is BusyBox, which most systems
-have anyway::
+have anyway:
+
+.. code-block:: bitbake
INIT_MANAGER = "mdev-busybox"
@@ -72,7 +76,9 @@ Using systemd
The last option is to use systemd together with the udev device
manager. This is the most powerful and versatile solution, especially
-for more complex systems::
+for more complex systems:
+
+.. code-block:: bitbake
INIT_MANAGER = "systemd"
@@ -103,7 +109,9 @@ Using systemd-journald without a traditional syslog daemon
Counter-intuitively, ``systemd-journald`` is not a syslog runtime or provider,
and the proper way to use ``systemd-journald`` as your sole logging mechanism is to
effectively disable syslog entirely by setting these variables in your distribution
-configuration file::
+configuration file:
+
+.. code-block:: bitbake
VIRTUAL-RUNTIME_syslog = ""
VIRTUAL-RUNTIME_base-utils-syslog = ""
diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index 3937c54ad2cc..a15fce6b93ba 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -212,7 +212,9 @@ following list:
machine "one". To do so, you use an append file named
``base-files.bbappend`` and create a dependency on "foo" by
altering the :term:`DEPENDS`
- variable::
+ variable:
+
+ .. code-block:: bitbake
DEPENDS = "foo"
@@ -225,12 +227,16 @@ following list:
``foo``.
To make sure your changes apply only when building machine "one",
- use a machine override with the :term:`DEPENDS` statement::
+ use a machine override with the :term:`DEPENDS` statement:
+
+ .. code-block:: bitbake
DEPENDS:one = "foo"
You should follow the same strategy when using ``:append``
- and ``:prepend`` operations::
+ and ``:prepend`` operations:
+
+ .. code-block:: bitbake
DEPENDS:append:one = " foo"
DEPENDS:prepend:one = "foo "
@@ -238,7 +244,9 @@ following list:
As an actual example, here's a
snippet from the generic kernel include file ``linux-yocto.inc``,
wherein the kernel compile and link options are adjusted in the
- case of a subset of the supported architectures::
+ case of a subset of the supported architectures:
+
+ .. code-block:: bitbake
DEPENDS:append:aarch64 = " libgcc"
KERNEL_CC:append:aarch64 = " ${TOOLCHAIN_OPTIONS}"
@@ -260,7 +268,9 @@ following list:
file, you can use an append file to cause the build to use your
own version of the file. For example, an append file in your layer
at ``meta-one/recipes-core/base-files/base-files.bbappend`` could
- extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows::
+ extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${BPN}:"
@@ -571,7 +581,9 @@ during the build.
Here is the append file, which is named ``formfactor_0.0.bbappend``
and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The
-file is in the layer at ``recipes-bsp/formfactor``::
+file is in the layer at ``recipes-bsp/formfactor``:
+
+.. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
@@ -619,7 +631,9 @@ As another example, consider the main ``xserver-xf86-config`` recipe and a
corresponding ``xserver-xf86-config`` append file both from
:term:`OpenEmbedded-Core (OE-Core)`. Here is the main ``xserver-xf86-config`` recipe, which is named
``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at
-``meta/recipes-graphics/xorg-xserver``::
+``meta/recipes-graphics/xorg-xserver``:
+
+.. code-block:: bitbake
SUMMARY = "X.Org X server configuration file"
HOMEPAGE = "http://www.x.org"
@@ -645,7 +659,9 @@ corresponding ``xserver-xf86-config`` append file both from
Here is the append file, which is named ``xserver-xf86-config_%.bbappend``
and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The
-file is in the layer at ``recipes-graphics/xorg-xserver``::
+file is in the layer at ``recipes-graphics/xorg-xserver``:
+
+.. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
@@ -685,7 +701,9 @@ build system to calculate it based on the layer's dependencies.
To specify the layer's priority manually, use the
:term:`BBFILE_PRIORITY`
-variable and append the layer's root name::
+variable and append the layer's root name:
+
+.. code-block:: bitbake
BBFILE_PRIORITY_mylayer = "1"
@@ -753,14 +771,18 @@ for the kernel only if our feature ``mylayer-kernel`` is part of the
PREFERRED_PROVIDER_virtual/kernel = "linux-custom"
-#. Provide a path to this include file in your ``layer.conf``::
+#. Provide a path to this include file in your ``layer.conf``:
+
+ .. code-block:: bitbake
META_MYLAYER_KERNEL_PROVIDER_PATH = "${LAYERDIR}/conf/distro/include/mylayer-kernel-provider.inc"
#. Create a new class in ``meta-mylayer/classes-global/``, for example a class
``meta-mylayer-cfg.bbclass``. Make it conditionally require the file
``mylayer-kernel-provider.inc`` defined above, using the variable
- ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``::
+ ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``:
+
+ .. code-block:: bitbake
require ${@bb.utils.contains('DISTRO_FEATURES', 'mylayer-kernel', '${META_MYLAYER_KERNEL_PROVIDER_PATH}', '', d)}
@@ -773,7 +795,9 @@ for the kernel only if our feature ``mylayer-kernel`` is part of the
``bb.utils.contains`` returns an empty string.
#. Back to your ``layer.conf`` file, add the class ``meta-mylayer-cfg`` class to
- the :term:`USER_CLASSES` variable::
+ the :term:`USER_CLASSES` variable:
+
+ .. code-block:: bitbake
USER_CLASSES:append = " meta-mylayer-cfg"
@@ -846,7 +870,9 @@ The following list describes the available commands:
variable values, you need to tidy these up yourself. Consider the
following example. Here, the ``bitbake-layers`` command adds the
line ``#### bbappended ...`` so that you know where the following
- lines originate::
+ lines originate:
+
+ .. code-block:: bitbake
...
DESCRIPTION = "A useful utility"
@@ -860,7 +886,9 @@ The following list describes the available commands:
EXTRA_OECONF += "--enable-somethingelse"
- Ideally, you would tidy up these utilities as follows::
+ Ideally, you would tidy up these utilities as follows:
+
+ .. code-block:: bitbake
...
DESCRIPTION = "Customized utility"
diff --git a/documentation/dev-manual/libraries.rst b/documentation/dev-manual/libraries.rst
index 160734729183..46ce2856158e 100644
--- a/documentation/dev-manual/libraries.rst
+++ b/documentation/dev-manual/libraries.rst
@@ -38,7 +38,9 @@ library files.
static library files through ``${PN}-dev``.
Here is a small part of the BitBake configuration file, where you can see
-how the static library files are defined::
+how the static library files are defined:
+
+.. code-block:: bitbake
PACKAGES = "${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}"
@@ -118,7 +120,9 @@ Using Multilib
After you have set up the recipes, you need to define the actual
combination of multiple libraries you want to build. You accomplish this
through your ``local.conf`` configuration file in the
-:term:`Build Directory`. An example configuration would be as follows::
+:term:`Build Directory`. An example configuration would be as follows:
+
+.. code-block:: bitbake
MACHINE = "qemux86-64"
require conf/multilib.conf
@@ -231,7 +235,9 @@ you have other recipes that depend on a given library, you need to use
the :term:`DEPENDS` variable to
create the dependency. Continuing with the same example, if you want to
have a recipe depend on the 1.8 version of the ``clutter`` library, use
-the following in your recipe::
+the following in your recipe:
+
+.. code-block:: bitbake
DEPENDS = "clutter-1.8"
diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst
index 774b5db23517..132a848b4660 100644
--- a/documentation/dev-manual/licenses.rst
+++ b/documentation/dev-manual/licenses.rst
@@ -28,7 +28,9 @@ Specifying the ``LIC_FILES_CHKSUM`` Variable
The :term:`LIC_FILES_CHKSUM` variable contains checksums of the license text
in the source code for the recipe. Here is an example of how to
-specify :term:`LIC_FILES_CHKSUM`::
+specify :term:`LIC_FILES_CHKSUM`:
+
+.. code-block:: bitbake
LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
@@ -51,7 +53,9 @@ variable as the default directory when searching files listed in
:term:`LIC_FILES_CHKSUM`. The previous example employs the default
directory.
-Consider this next example::
+Consider this next example:
+
+.. code-block:: bitbake
LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
md5=bb14ed3c4cda583abc85401304b5cd4e"
@@ -113,18 +117,24 @@ are defined on a recipe-by-recipe basis through the
:term:`LICENSE_FLAGS` variable
definition in the affected recipe. For instance, the
``meta/recipes-multimedia/gstreamer/gstreamer1.0-plugins-ugly`` recipe of
-:term:`OpenEmbedded-Core (OE-Core)` contains the following statement::
+:term:`OpenEmbedded-Core (OE-Core)` contains the following statement:
+
+.. code-block:: bitbake
LICENSE_FLAGS = "commercial"
Here is a
slightly more complicated example that contains both an explicit recipe
-name and version (after variable expansion)::
+name and version (after variable expansion):
+
+.. code-block:: bitbake
LICENSE_FLAGS = "license_${PN}_${PV}"
It is possible to give more details about a specific license
-using flags on the :term:`LICENSE_FLAGS_DETAILS` variable::
+using flags on the :term:`LICENSE_FLAGS_DETAILS` variable:
+
+.. code-block:: bitbake
LICENSE_FLAGS_DETAILS[my-eula-license] = "For further details, see https://example.com/eula."
@@ -142,7 +152,9 @@ could add either the string "commercial_gst-plugins-ugly" or the more
general string "commercial" to :term:`LICENSE_FLAGS_ACCEPTED`. See the
":ref:`dev-manual/licenses:license flag matching`" section for a full
explanation of how :term:`LICENSE_FLAGS` matching works. Here is the
-example::
+example:
+
+.. code-block:: bitbake
LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly"
@@ -150,7 +162,9 @@ Likewise, to additionally enable the package built from the recipe
containing ``LICENSE_FLAGS = "license_${PN}_${PV}"``, and assuming that
the actual recipe name was ``emgd_1.10.bb``, the following string would
enable that package as well as the original ``gst-plugins-ugly``
-package::
+package:
+
+.. code-block:: bitbake
LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly license_emgd_1.10"
@@ -162,7 +176,9 @@ or characters. A partial string will match any license that contains the
given string as the first portion of its license. For example, the
following value will also match both of the packages
previously mentioned as well as any other packages that have licenses
-starting with "commercial" or "license"::
+starting with "commercial" or "license":
+
+.. code-block:: bitbake
LICENSE_FLAGS_ACCEPTED = "commercial license"
@@ -207,7 +223,9 @@ For example, simply specifying the string "commercial" in the
"commercial" such as "commercial_foo" and "commercial_bar", which
are the strings the build system automatically generates for
hypothetical recipes named "foo" and "bar" assuming those recipes simply
-specify the following::
+specify the following:
+
+.. code-block:: bitbake
LICENSE_FLAGS = "commercial"
@@ -245,13 +263,17 @@ Other Variables Related to Commercial Licenses
There are other helpful variables related to commercial license handling,
defined in the
-``meta/conf/distro/include/default-distrovars.inc`` file in :term:`OpenEmbedded-Core (OE-Core)`::
+``meta/conf/distro/include/default-distrovars.inc`` file in :term:`OpenEmbedded-Core (OE-Core)`:
+
+.. code-block:: bitbake
COMMERCIAL_AUDIO_PLUGINS ?= ""
COMMERCIAL_VIDEO_PLUGINS ?= ""
If you want to enable these components, you can do so by making sure you have
-statements similar to the following in your ``local.conf`` configuration file::
+statements similar to the following in your ``local.conf`` configuration file:
+
+.. code-block:: bitbake
COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
gst-plugins-ugly-mpegaudioparse"
@@ -262,7 +284,9 @@ statements similar to the following in your ``local.conf`` configuration file::
Of course, you could also create a matching list for those components using the
more general "commercial" string in the :term:`LICENSE_FLAGS_ACCEPTED` variable,
but that would also enable all the other packages with :term:`LICENSE_FLAGS`
-containing "commercial", which you may or may not want::
+containing "commercial", which you may or may not want:
+
+.. code-block:: bitbake
LICENSE_FLAGS_ACCEPTED = "commercial"
@@ -361,7 +385,9 @@ create them with various levels of compliance in mind.
One way of doing this (but certainly not the only way) is to release
just the source as a tarball. You can do this by adding the following to
-the ``local.conf`` file found in the :term:`Build Directory`::
+the ``local.conf`` file found in the :term:`Build Directory`:
+
+.. code-block:: bitbake
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
@@ -417,7 +443,9 @@ One requirement that is often overlooked is inclusion of license text.
This requirement also needs to be dealt with prior to generating the
final image. Some licenses require the license text to accompany the
binary. You can achieve this by adding the following to your
-``local.conf`` file::
+``local.conf`` file:
+
+.. code-block:: bitbake
COPY_LIC_MANIFEST = "1"
COPY_LIC_DIRS = "1"
@@ -528,7 +556,9 @@ variable. Using this variable also avoids QA errors when you use a
non-common, non-CLOSED license in a recipe.
Here is an example that uses the ``LICENSE.Abilis.txt`` file as
-the license from the fetched source::
+the license from the fetched source:
+
+.. code-block:: bitbake
NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
diff --git a/documentation/dev-manual/limiting-resources.rst b/documentation/dev-manual/limiting-resources.rst
index 9b3db0a59514..8101a9d1ea3b 100644
--- a/documentation/dev-manual/limiting-resources.rst
+++ b/documentation/dev-manual/limiting-resources.rst
@@ -38,7 +38,9 @@ details.
If you want to have a different limit from the rest of the build for a
recipe, it is also possible to achieve with the following line added to your
- ``local.conf`` :term:`configuration file`::
+ ``local.conf`` :term:`configuration file`:
+
+ .. code-block:: bitbake
PARALLEL_MAKE:pn-linux-yocto = "-j4"
diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst
index 71fe542efbbd..356dcb768def 100644
--- a/documentation/dev-manual/multiconfig.rst
+++ b/documentation/dev-manual/multiconfig.rst
@@ -61,7 +61,9 @@ Follow these steps to set up and execute multiple configuration builds:
Here is an example showing the minimal statements needed in a
:term:`configuration file` named ``qemux86.conf`` for a ``qemux86`` target
- whose temporary build directory is ``tmp-qemux86``::
+ whose temporary build directory is ``tmp-qemux86``:
+
+ .. code-block:: bitbake
MACHINE = "qemux86"
TMPDIR .= "-${BB_CURRENT_MC}"
@@ -77,7 +79,9 @@ Follow these steps to set up and execute multiple configuration builds:
variable in your ``conf/local.conf`` configuration file to specify
each multiconfig. Continuing with the example from the previous
figure, the :term:`BBMULTICONFIG` variable needs to enable two
- multiconfigs: "x86" and "arm" by specifying each configuration file::
+ multiconfigs: "x86" and "arm" by specifying each configuration file:
+
+ .. code-block:: bitbake
BBMULTICONFIG = "x86 arm"
@@ -134,13 +138,17 @@ essentially that the
To enable dependencies in a multiple configuration build, you must
declare the dependencies in the recipe using the following statement
-form::
+form:
+
+.. code-block:: bitbake
task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend"
To better show how to use this statement, consider the example scenario
from the first paragraph of this section. The following statement needs
-to be added to the recipe that builds the ``core-image-sato`` image::
+to be added to the recipe that builds the ``core-image-sato`` image:
+
+.. code-block:: bitbake
do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs"
@@ -161,7 +169,9 @@ dependency, BitBake also executes through the :ref:`ref-tasks-rootfs` task for t
Having a recipe depend on the root filesystem of another build might not
seem that useful. Consider this change to the statement in the
-``core-image-sato`` recipe::
+``core-image-sato`` recipe:
+
+.. code-block:: bitbake
do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image"
@@ -192,7 +202,9 @@ Suggested best practices
the deployed item based on :term:`TMPDIR`.
The :ref:`ref-tasks-install` and :ref:`ref-tasks-deploy` tasks should look
- like this::
+ like this:
+
+ .. code-block:: bitbake
do_install() {
install -m 0644 ${TMPDIR}-<multiconfig>/tmp/deploy/images/<machine>/somefile ${D}/some/path
@@ -234,7 +246,9 @@ Configuration Build`, each multiconfig will require a separate
:term:`TMPDIR` for our baremetal firmware build configuration.
For example, we will define a new ``conf/multiconfig/baremetal-firmware.conf``
-as follows::
+as follows:
+
+.. code-block:: bitbake
TMPDIR .= "-${BB_CURRENT_MC}"
TCLIBC = "newlib"
@@ -272,7 +286,9 @@ Using a ``mcdepend``, a recipe belonging to the Linux build can trigger the
build of ``my-firmware``. For example, let's consider that our Linux build needs
to assemble a "special" firmware that uses the output of our ``my-firmware``
recipe - let's call it ``my-parent-firmware.bb``. Then, we should specify this
-dependency in ``my-parent-firmware.bb`` with::
+dependency in ``my-parent-firmware.bb`` with:
+
+.. code-block:: bitbake
do_compile[mcdepends] = "mc::baremetal-firmware:my-firmware:do_deploy"
@@ -287,7 +303,9 @@ After ``my-firmware`` recipe has deployed ``my-firmware.elf``, we need to use
the output in some way. We can make a series of assumptions, based on the
default Yocto Project variables in order to get the binary for packaging.
-First, we can set the following in ``my-parent-firmware.bb``::
+First, we can set the following in ``my-parent-firmware.bb``:
+
+.. code-block:: bitbake
FIRMWARE_FILE ??= "${TMPDIR}-baremetal-firmware/deploy/images/<machine>/my-firmware.elf"
FIRMWARE_FILE[vardepsexclude] += "TMPDIR"
@@ -302,7 +320,9 @@ cache <overview-manual/concepts:shared state cache>`.
Additionally, ``<machine>`` should be replaced by the :term:`MACHINE` for which
we are building in the baremetal-firmware context.
-We can then add a :ref:`ref-tasks-install` task to ``my-parent-firmware``::
+We can then add a :ref:`ref-tasks-install` task to ``my-parent-firmware``:
+
+.. code-block:: bitbake
do_install() {
install -Dm 0644 ${FIRMWARE_FILE} ${D}/lib/firmware/my-firmware.elf
diff --git a/documentation/dev-manual/new-machine.rst b/documentation/dev-manual/new-machine.rst
index b4d29027be12..c08e359a2e64 100644
--- a/documentation/dev-manual/new-machine.rst
+++ b/documentation/dev-manual/new-machine.rst
@@ -77,7 +77,9 @@ of adding a suitable ``defconfig`` file. The file needs to be added into
a location similar to ``defconfig`` files used for other machines in a
given kernel recipe. A possible way to do this is by listing the file in
the :term:`SRC_URI` and adding the machine to the expression in
-:term:`COMPATIBLE_MACHINE`::
+:term:`COMPATIBLE_MACHINE`:
+
+.. code-block:: bitbake
COMPATIBLE_MACHINE = '(qemux86|qemumips)'
diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index d1c863117259..27e9065d5f4c 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -147,7 +147,9 @@ get started. Here are some points on both methods:
- *Use and modify the following skeleton recipe:* If for some reason
you do not want to use ``recipetool`` and you cannot find an existing
recipe that is close to meeting your needs, you can use the following
- structure to provide the fundamental areas of a new recipe::
+ structure to provide the fundamental areas of a new recipe:
+
+ .. code-block:: bitbake
DESCRIPTION = ""
HOMEPAGE = ""
@@ -170,7 +172,9 @@ the recipe.
recipe through the layer's ``conf/layer.conf`` file and the
:term:`BBFILES` variable. This
variable sets up a path from which the build system can locate
- recipes. Here is the typical use::
+ recipes. Here is the typical use:
+
+ .. code-block:: bitbake
BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
${LAYERDIR}/recipes-*/*/*.bbappend"
@@ -289,7 +293,9 @@ recipe to match the new version.
Here is a simple example from the
:oe_git:`strace recipe </openembedded-core/tree/meta/recipes-devtools/strace>`
where the source comes from a single tarball. Notice the use of the
-:term:`PV` variable::
+:term:`PV` variable:
+
+.. code-block:: bitbake
SRC_URI = "${GITHUB_BASE_URI}/download/v${PV}/strace-${PV}.tar.xz \
@@ -303,7 +309,9 @@ another example that specifies these types of files, see the
Another way of specifying source is from an SCM. For Git repositories,
you must specify :term:`SRCREV` and you should specify :term:`PV` to include
a ``+`` sign in its definition. Here is an example from the recipe
-:oe_git:`l3afpad_git.bb </openembedded-core/tree/meta/recipes-sato/l3afpad/l3afpad_git.bb>`::
+:oe_git:`l3afpad_git.bb </openembedded-core/tree/meta/recipes-sato/l3afpad/l3afpad_git.bb>`:
+
+.. code-block:: bitbake
SRC_URI = "git://github.com/stevenhoneyman/l3afpad.git;branch=master;protocol=https"
@@ -329,7 +337,9 @@ If your :term:`SRC_URI` variable points to more than a single URL (excluding
SCM URLs), you need to provide the ``sha256`` checksum for each URL. For these
cases, you provide a name for each URL as part of the :term:`SRC_URI` and then
reference that name in the subsequent checksum statements. Here is an example
-combining lines from the files ``git.inc`` and ``git_2.24.1.bb``::
+combining lines from the files ``git.inc`` and ``git_2.24.1.bb``:
+
+.. code-block:: bitbake
SRC_URI = "${KERNELORG_MIRROR}/software/scm/git/git-${PV}.tar.gz;name=tarball \
${KERNELORG_MIRROR}/software/scm/git/git-manpages-${PV}.tar.gz;name=manpages"
@@ -360,7 +370,9 @@ paste them into your recipe and then run the build again to continue.
This final example is a bit more complicated and is from the
:oe_git:`rxvt-unicode </openembedded-core/tree/meta/recipes-sato/rxvt-unicode>`
recipe. The example's :term:`SRC_URI` statement identifies multiple files as the source
-files for the recipe: a tarball, a patch file, a desktop file, and an icon::
+files for the recipe: a tarball, a patch file, a desktop file, and an icon:
+
+.. code-block:: bitbake
SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \
file://xwc.patch \
@@ -396,7 +408,9 @@ Limiting the Number of Parallel Connections
Some users are behind firewalls or use servers where the number of parallel
connections is limited. In such cases, you can limit the number of fetch
tasks being run in parallel by adding the following to your ``local.conf``
-file::
+file:
+
+.. code-block:: bitbake
do_fetch[number_threads] = "4"
@@ -644,7 +658,9 @@ standard mainline kernel, not your own custom one.
When you use custom kernel headers you need to get them from
:term:`STAGING_KERNEL_DIR`,
which is the directory with kernel headers that are required to build
-out-of-tree modules. Your recipe will also need the following::
+out-of-tree modules. Your recipe will also need the following:
+
+.. code-block:: bitbake
do_configure[depends] += "virtual/kernel:do_shared_workdir"
@@ -675,7 +691,9 @@ Here are some common issues that cause failures.
To fix the problem, you need to either satisfy the missing dependency
in the Makefile or whatever script produced the Makefile, or (as a
- workaround) set :term:`PARALLEL_MAKE` to an empty string::
+ workaround) set :term:`PARALLEL_MAKE` to an empty string:
+
+ .. code-block:: bitbake
PARALLEL_MAKE = ""
@@ -784,7 +802,9 @@ installed correctly.
can result in race conditions. If you experience intermittent failures
during :ref:`ref-tasks-install`, you might be able to work around them by
disabling parallel Makefile installs by adding the following to the
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
PARALLEL_MAKEINST = ""
@@ -895,7 +915,9 @@ take. The following list describes the process:
:term:`MACHINE` value is passed
into the configure script or a patch is applied only for a particular
machine), you should mark them as such by adding the following to the
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
PACKAGE_ARCH = "${MACHINE_ARCH}"
@@ -903,7 +925,9 @@ take. The following list describes the process:
contain anything specific to the target machine or architecture at
all (e.g. recipes that simply package script files or configuration
files), you should use the :ref:`ref-classes-allarch` class to
- do this for you by adding this to your recipe::
+ do this for you by adding this to your recipe:
+
+ .. code-block:: bitbake
inherit allarch
@@ -947,7 +971,9 @@ used by the :ref:`ref-tasks-populate_sysroot` task as defined by the
:term:`SYSROOT_DIRS` variable to automatically populate the sysroot. It
is possible to modify the list of directories that populate the sysroot.
The following example shows how you could add the ``/opt`` directory to
-the list of directories within a recipe::
+the list of directories within a recipe:
+
+.. code-block:: bitbake
SYSROOT_DIRS += "/opt"
@@ -974,7 +1000,9 @@ recipe. Suppose you have three kernel recipes whose :term:`PN` values map to
``kernel-big``, ``kernel-mid``, and ``kernel-small``. Furthermore, each of
these recipes in some way uses a :term:`PROVIDES` statement that essentially
identifies itself as being able to provide ``virtual/kernel``. Here is one way
-through the :ref:`ref-classes-kernel` class::
+through the :ref:`ref-classes-kernel` class:
+
+.. code-block:: bitbake
PROVIDES += "virtual/kernel"
@@ -996,7 +1024,9 @@ relevant line from that include file::
When you use a virtual provider, you do not have to "hard code" a recipe
name as a build dependency. You can use the
:term:`DEPENDS` variable to state the
-build is dependent on ``virtual/kernel`` for example::
+build is dependent on ``virtual/kernel`` for example:
+
+.. code-block:: bitbake
DEPENDS = "virtual/kernel"
@@ -1053,7 +1083,9 @@ build system and package managers, so the resulting packages will not
correctly trigger an upgrade.
In order to ensure the versions compare properly, the recommended
-convention is to use a tilde (``~``) character as follows::
+convention is to use a tilde (``~``) character as follows:
+
+.. code-block:: bitbake
PV = 0.8.16~rc1
@@ -1158,7 +1190,9 @@ Building an application from a single file that is stored locally (e.g. under
variable. Additionally, you need to manually write the :ref:`ref-tasks-compile`
and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the
directory containing the source code, which is set to :term:`UNPACKDIR` in this
-case --- the directory BitBake uses for the build::
+case --- the directory BitBake uses for the build:
+
+.. code-block:: bitbake
SUMMARY = "Simple helloworld application"
SECTION = "examples"
@@ -1198,11 +1232,15 @@ empty :ref:`ref-tasks-install` task by default.
Some applications might require extra parameters to be passed to the
compiler. For example, the application might need an additional header
path. You can accomplish this by adding to the :term:`CFLAGS` variable. The
-following example shows this::
+following example shows this:
+
+.. code-block:: bitbake
CFLAGS:prepend = "-I ${S}/include "
-In the following example, ``lz4`` is a makefile-based package::
+In the following example, ``lz4`` is a makefile-based package:
+
+.. code-block:: bitbake
SUMMARY = "Extremely Fast Compression algorithm"
DESCRIPTION = "LZ4 is a very fast lossless compression algorithm, providing compression speed at 400 MB/s per core, scalable with multi-cores CPU. It also features an extremely fast decoder, with speed in multiple GB/s per core, typically reaching RAM speed limits on multi-core systems."
@@ -1242,7 +1280,9 @@ inherit the :ref:`ref-classes-autotools` class, which contains the definitions
of all the steps needed to build an Autotool-based application. The result of
the build is automatically packaged. And, if the application uses NLS for
localization, packages with local information are generated (one package per
-language). Here is one example: (``hello_2.3.bb``)::
+language). Here is one example: (``hello_2.3.bb``):
+
+.. code-block:: bitbake
SUMMARY = "GNU Helloworld application"
SECTION = "examples"
@@ -1268,7 +1308,9 @@ just need a recipe that has sources described in :term:`SRC_URI` and inherits
the :ref:`ref-classes-meson` class.
The :oe_git:`ipcalc recipe </meta-openembedded/tree/meta-networking/recipes-support/ipcalc>`
-is a simple example of an application without dependencies::
+is a simple example of an application without dependencies:
+
+.. code-block:: bitbake
SUMMARY = "Tool to assist in network address calculations for IPv4 and IPv6."
HOMEPAGE = "https://gitlab.com/ipcalc/ipcalc"
@@ -1296,7 +1338,9 @@ application into multiple packages.
Here is an example that uses the ``libxpm`` recipe. By default,
this recipe generates a single package that contains the library along
with a few binaries. You can modify the recipe to split the binaries
-into separate packages::
+into separate packages:
+
+.. code-block:: bitbake
require xorg-lib-common.inc
@@ -1385,7 +1429,9 @@ doing the following:
that replaces :ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` with custom
versions, then you can use the
``[``\ :ref:`noexec <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
- flag to turn the tasks into no-ops, as follows::
+ flag to turn the tasks into no-ops, as follows:
+
+ .. code-block:: bitbake
do_configure[noexec] = "1"
do_compile[noexec] = "1"
@@ -1409,7 +1455,9 @@ As a basic example of a :ref:`ref-classes-bin-package`-style recipe, consider
this snippet from the
:oe_git:`wireless-regdb </openembedded-core/tree/meta/recipes-kernel/wireless-regdb>`
recipe file, which fetches a single tarball of binary content and manually
-installs with no need for any configuration or compilation::
+installs with no need for any configuration or compilation:
+
+.. code-block:: bitbake
SRC_URI = "https://www.kernel.org/pub/software/network/${BPN}/${BP}.tar.xz"
SRC_URI[sha256sum] = "57f8e7721cf5a880c13ae0c202edbb21092a060d45f9e9c59bcd2a8272bfa456"
@@ -1454,7 +1502,9 @@ chapter of the BitBake User Manual.
supported.
The following example shows some of the ways you can use variables in
- recipes::
+ recipes:
+
+ .. code-block:: bitbake
S = "${UNPACKDIR}/postfix-${PV}"
CFLAGS += "-DNO_ASM"
@@ -1467,7 +1517,9 @@ chapter of the BitBake User Manual.
syntax, although access to OpenEmbedded variables and internal
methods are also available.
- Here is an example function from the ``sed`` recipe::
+ Here is an example function from the ``sed`` recipe:
+
+ .. code-block:: bitbake
do_install () {
autotools_do_install
@@ -1490,7 +1542,9 @@ chapter of the BitBake User Manual.
from other files (``include`` and ``require``) and export variables
to the environment (``export``).
- The following example shows the use of some of these keywords::
+ The following example shows the use of some of these keywords:
+
+ .. code-block:: bitbake
export POSTCONF = "${STAGING_BINDIR}/postconf"
inherit autoconf
@@ -1509,7 +1563,9 @@ in the BitBake User Manual.
- *Line Continuation (\\):* Use the backward slash (``\``) character to
split a statement over multiple lines. Place the slash character at
- the end of the line that is to be continued on the next line::
+ the end of the line that is to be continued on the next line:
+
+ .. code-block:: bitbake
VAR = "A really long \
line"
@@ -1520,7 +1576,9 @@ in the BitBake User Manual.
slash character.
- *Using Variables (${VARNAME}):* Use the ``${VARNAME}`` syntax to
- access the contents of a variable::
+ access the contents of a variable:
+
+ .. code-block:: bitbake
SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
@@ -1540,7 +1598,9 @@ in the BitBake User Manual.
when you make the assignment, but this is not generally needed.
- *Quote All Assignments ("value"):* Use double quotes around values in
- all variable assignments (e.g. ``"value"``). Here is an example::
+ all variable assignments (e.g. ``"value"``). Here is an example:
+
+ .. code-block:: bitbake
VAR1 = "${OTHERVAR}"
VAR2 = "The version is ${PV}"
@@ -1554,11 +1614,15 @@ in the BitBake User Manual.
Here is an example where ``VAR1`` is set to "New value" if it is
currently empty. However, if ``VAR1`` has already been set, it
- remains unchanged::
+ remains unchanged:
+
+ .. code-block:: bitbake
VAR1 ?= "New value"
- In this next example, ``VAR1`` is left with the value "Original value"::
+ In this next example, ``VAR1`` is left with the value "Original value":
+
+ .. code-block:: bitbake
VAR1 = "Original value"
VAR1 ?= "New value"
@@ -1571,7 +1635,9 @@ in the BitBake User Manual.
This operator adds a space between the existing content of the
variable and the new content.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
SRC_URI += "file://fix-makefile.patch"
@@ -1583,7 +1649,9 @@ in the BitBake User Manual.
This operator adds a space between the new content and the
existing content of the variable.
- Here is an example::
+ Here is an example:
+
+ .. code-block:: bitbake
VAR =+ "Starts"
@@ -1597,13 +1665,17 @@ in the BitBake User Manual.
The following example shows the space being explicitly added to the
start to ensure the appended value is not merged with the existing
- value::
+ value:
+
+ .. code-block:: bitbake
CFLAGS:append = " --enable-important-feature"
You can also use
the ``:append`` operator with overrides, which results in the actions
- only being performed for the specified target or machine::
+ only being performed for the specified target or machine:
+
+ .. code-block:: bitbake
CFLAGS:append:sh4 = " --enable-important-sh4-specific-feature"
@@ -1615,13 +1687,17 @@ in the BitBake User Manual.
The following example shows the space being explicitly added to the
end to ensure the prepended value is not merged with the existing
- value::
+ value:
+
+ .. code-block:: bitbake
CFLAGS:prepend = "-I${S}/myincludes "
You can also use the
``:prepend`` operator with overrides, which results in the actions
- only being performed for the specified target or machine::
+ only being performed for the specified target or machine:
+
+ .. code-block:: bitbake
CFLAGS:prepend:sh4 = "-I${S}/myincludes "
@@ -1631,7 +1707,9 @@ in the BitBake User Manual.
value to "standard/base" for any target
:term:`MACHINE`, except for
qemuarm where it should be set to "standard/arm-versatile-926ejs",
- you would do the following::
+ you would do the following:
+
+ .. code-block:: bitbake
KBRANCH = "standard/base"
KBRANCH:qemuarm = "standard/arm-versatile-926ejs"
@@ -1654,7 +1732,9 @@ in the BitBake User Manual.
search and replacement on a variable).
You indicate Python code using the ``${@python_code}`` syntax for the
- variable assignment::
+ variable assignment:
+
+ .. code-block:: bitbake
SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst
index c75584c936bf..16ce82606007 100644
--- a/documentation/dev-manual/packages.rst
+++ b/documentation/dev-manual/packages.rst
@@ -163,7 +163,9 @@ be consistent and correct with the latest changes.
The simplest form for a PR Service is for a single host development system
that builds the package feed (building system). For this scenario, you can
enable a local PR Service by setting :term:`PRSERV_HOST` in your
-``local.conf`` file in the :term:`Build Directory`::
+``local.conf`` file in the :term:`Build Directory`:
+
+.. code-block:: bitbake
PRSERV_HOST = "localhost:0"
@@ -248,13 +250,17 @@ the specific source code revision from which to build. You set the
:term:`SRCREV` variable to
:term:`AUTOREV` to cause the
OpenEmbedded build system to automatically use the latest revision of
-the software::
+the software:
+
+.. code-block:: bitbake
SRCREV = "${AUTOREV}"
Furthermore, you need to include a ``+`` sign in :term:`PV` in order to
automatically update the version whenever the revision of the source
-code changes. Here is an example::
+code changes. Here is an example:
+
+.. code-block:: bitbake
PV = "1.0+git"
@@ -338,7 +344,9 @@ package for each one it finds by appending to the
:term:`PACKAGES` variable and
setting the appropriate values for ``FILES:packagename``,
``RDEPENDS:packagename``, ``DESCRIPTION:packagename``, and so forth.
-Here is an example from the ``lighttpd`` recipe::
+Here is an example from the ``lighttpd`` recipe:
+
+.. code-block:: bitbake
python populate_packages:prepend () {
lighttpd_libdir = d.expand('${libdir}')
@@ -470,7 +478,9 @@ any dependencies on optional modules from other recipes are satisfied by
your recipe. You can be sure these dependencies are satisfied by using
the :term:`PACKAGES_DYNAMIC`
variable. Here is an example that continues with the ``lighttpd`` recipe
-shown earlier::
+shown earlier:
+
+.. code-block:: bitbake
PACKAGES_DYNAMIC = "lighttpd-module-.*"
@@ -561,7 +571,9 @@ variable to specify the format:
#. Open the ``local.conf`` file inside your :term:`Build Directory` (e.g.
``bitbake-builds/build/conf/local.conf``).
-#. Select the desired package format as follows::
+#. Select the desired package format as follows:
+
+ .. code-block:: bitbake
PACKAGE_CLASSES ?= "package_packageformat"
@@ -837,11 +849,15 @@ Signing RPM Packages
To enable signing RPM packages, you must modify the ``rpm``
recipe configuration to include support for OpenPGP signing.
-That may be done either in a ``.bbappend`` for the ``rpm`` recipe::
+That may be done either in a ``.bbappend`` for the ``rpm`` recipe:
+
+.. code-block:: bitbake
PACKAGECONFIG:append = " sequoia"
-or in a :term:`Configuration File`::
+or in a :term:`Configuration File`:
+
+.. code-block:: bitbake
PACKAGECONFIG:append:pn-rpm-native = " sequoia"
PACKAGECONFIG:append:pn-rpm = " sequoia"
@@ -878,7 +894,9 @@ signed package feeds for IPK and RPM packages.
The steps you need to take to enable signed package feed use are similar
to the steps used to sign RPM packages. You must define the following in
-your ``local.config`` or ``distro.config`` file::
+your ``local.config`` or ``distro.config`` file:
+
+.. code-block:: bitbake
INHERIT += "sign_package_feed"
PACKAGE_FEED_GPG_NAME = "key_name"
@@ -1115,7 +1133,9 @@ command::
$ devtool add https://github.com/martinaglv/cute-files.git
The recipe this command generates is very similar to the recipe created in
-the previous section. However, the :term:`SRC_URI` looks like the following::
+the previous section. However, the :term:`SRC_URI` looks like the following:
+
+.. code-block:: bitbake
SRC_URI = " \
git://github.com/martinaglv/cute-files.git;protocol=https;branch=master \
@@ -1167,7 +1187,9 @@ by the literal sequence '\\n'. The separator can be redefined using the
variable flag ``separator``.
Here is an example that adds two custom fields for ipk
-packages::
+packages:
+
+.. code-block:: bitbake
PACKAGE_ADD_METADATA_IPK = "Vendor: CustomIpk\nGroup:Applications/Spreadsheets"
diff --git a/documentation/dev-manual/poky-manual-setup.rst b/documentation/dev-manual/poky-manual-setup.rst
index 833e1631ee50..f2287c25c339 100644
--- a/documentation/dev-manual/poky-manual-setup.rst
+++ b/documentation/dev-manual/poky-manual-setup.rst
@@ -119,7 +119,9 @@ an entire Linux distribution, including the toolchain, from source.
can download these artifacts faster than you would be able to build them.
To use such mirrors, uncomment the below lines in your ``conf/local.conf``
- file in the :term:`Build Directory`::
+ file in the :term:`Build Directory`:
+
+ .. code-block:: bitbake
BB_HASHSERVE_UPSTREAM = "wss://hashserv.yoctoproject.org/ws"
SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH"
diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst
index 9cc8bd2d9dee..8eb4d5023b17 100644
--- a/documentation/dev-manual/prebuilt-libraries.rst
+++ b/documentation/dev-manual/prebuilt-libraries.rst
@@ -149,7 +149,9 @@ triggers a QA warning that a non-symlink library is in a ``-dev`` package,
and binaries in the same recipe link to the library in ``${PN}-dev``,
which triggers more QA warnings. To solve this problem, you need to package the
unversioned library into ``${PN}`` where it belongs. The abridged
-default :term:`FILES` variables in ``bitbake.conf`` are::
+default :term:`FILES` variables in ``bitbake.conf`` are:
+
+.. code-block:: bitbake
SOLIBS = ".so.*"
SOLIBSDEV = ".so"
@@ -162,7 +164,9 @@ default :term:`FILES` variables in ``bitbake.conf`` are::
variables are then used in ``FILES:${PN}`` and ``FILES:${PN}-dev``, which puts
the real libraries into ``${PN}`` and the unversioned symbolic link into ``${PN}-dev``.
To package unversioned libraries, you need to modify the variables in the recipe
-as follows::
+as follows:
+
+.. code-block:: bitbake
SOLIBS = ".so"
FILES_SOLIBSDEV = ""
@@ -186,7 +190,9 @@ The example below installs an unversioned x86-64 pre-built library named
x86-64 architecture while the :term:`INSANE_SKIP`, :term:`INHIBIT_PACKAGE_STRIP`
and :term:`INHIBIT_SYSROOT_STRIP` variables are all set as in the above
versioned library example. The "magic" is setting the :term:`SOLIBS` and
-:term:`FILES_SOLIBSDEV` variables as explained above::
+:term:`FILES_SOLIBSDEV` variables as explained above:
+
+.. code-block:: bitbake
SUMMARY = "libfoo sample recipe"
SECTION = "libs"
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index 514a72fc528a..eead23f67376 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -434,7 +434,9 @@ command line:
(or the next free ports). Specific forwarding rules can be configured
by setting ``QB_SLIRP_OPT`` as environment variable or in ``qemuboot.conf``
in the :term:`Build Directory` ``deploy/image`` directory.
- Examples::
+ Examples:
+
+ .. code-block:: bitbake
QB_SLIRP_OPT = "-netdev user,id=net0,hostfwd=tcp::8080-:80"
diff --git a/documentation/dev-manual/quilt.rst b/documentation/dev-manual/quilt.rst
index 59240705ad99..2173d86981db 100644
--- a/documentation/dev-manual/quilt.rst
+++ b/documentation/dev-manual/quilt.rst
@@ -83,7 +83,9 @@ Follow these general steps:
that holds the recipe (``.bb``) file or the append (``.bbappend``)
file. Placing the patch here guarantees that the OpenEmbedded build
system will find the patch. Next, add the patch into the :term:`SRC_URI`
- of the recipe. Here is an example::
+ of the recipe. Here is an example:
+
+ .. code-block:: bitbake
SRC_URI += "file://my_changes.patch"
diff --git a/documentation/dev-manual/sbom.rst b/documentation/dev-manual/sbom.rst
index 45b63ed8edea..aff328423287 100644
--- a/documentation/dev-manual/sbom.rst
+++ b/documentation/dev-manual/sbom.rst
@@ -27,7 +27,9 @@ assessments, as all the components used in the Software Supply Chain are listed.
The OpenEmbedded build system generates such information by default (by
inheriting the :ref:`ref-classes-create-spdx` class in :term:`INHERIT_DISTRO`).
-If needed, it can be disabled from a :term:`configuration file`::
+If needed, it can be disabled from a :term:`configuration file`:
+
+.. code-block:: bitbake
INHERIT_DISTRO:remove = "create-spdx"
diff --git a/documentation/dev-manual/speeding-up-build.rst b/documentation/dev-manual/speeding-up-build.rst
index 262935313a19..a6930fc41642 100644
--- a/documentation/dev-manual/speeding-up-build.rst
+++ b/documentation/dev-manual/speeding-up-build.rst
@@ -90,7 +90,9 @@ that can help you speed up the build:
- Disable static library generation for recipes derived from
``autoconf`` or ``libtool``: Here is an example showing how to
disable static libraries and still provide an override to handle
- exceptions::
+ exceptions:
+
+ .. code-block:: bitbake
STATICLIBCONF = "--disable-static"
STATICLIBCONF:sqlite3-native = ""
diff --git a/documentation/dev-manual/sstate-mirrors-setup.rst b/documentation/dev-manual/sstate-mirrors-setup.rst
index e69aa00d1cc6..a0c6e7d579fc 100644
--- a/documentation/dev-manual/sstate-mirrors-setup.rst
+++ b/documentation/dev-manual/sstate-mirrors-setup.rst
@@ -86,7 +86,9 @@ Client Configuration
Configuring clients to this server happens through a :term:`configuration file`,
for example, the :ref:`site.conf <structure-build-conf-site.conf>` file. Only
-the :term:`SSTATE_MIRRORS` variable is needed to setup the connection::
+the :term:`SSTATE_MIRRORS` variable is needed to setup the connection:
+
+.. code-block:: bitbake
SSTATE_MIRRORS = "file://.* http://127.0.0.1:8000/PATH;downloadfilename=PATH"
@@ -134,7 +136,9 @@ Going Further
Another method to configure the username and password is from the
URL in :term:`SSTATE_MIRRORS` directly, with the ``user`` and ``pswd``
- parameters::
+ parameters:
+
+ .. code-block:: bitbake
SSTATE_MIRRORS ?= "\
file://.* https://someserver.tld/share/sstate/PATH;user=<user>;pswd=<password>;downloadfilename=PATH \
@@ -146,7 +150,9 @@ Going Further
mirror as an exception.
- Multiple shared state sources can be specified in the :term:`SSTATE_MIRRORS`
- variable. For example::
+ variable. For example:
+
+ .. code-block:: bitbake
SSTATE_MIRRORS = "\
file://.* https://someserver.com/PATH;downloadfilename=PATH \
@@ -158,7 +164,9 @@ Going Further
- Fetching the shared state artifacts from a local directory, such as an
:wikipedia:`NFS <Network_File_System>`-mounted directory, is also possible
- using the ``file://`` fetcher::
+ using the ``file://`` fetcher:
+
+ .. code-block:: bitbake
SSTATE_MIRRORS = "file://.* file:///path/to/shared-state/PATH;downloadfilename=PATH"
diff --git a/documentation/dev-manual/temporary-source-code.rst b/documentation/dev-manual/temporary-source-code.rst
index cb27d22070ef..a2f6b6ef40d5 100644
--- a/documentation/dev-manual/temporary-source-code.rst
+++ b/documentation/dev-manual/temporary-source-code.rst
@@ -16,7 +16,9 @@ During a build, the unpacked temporary source code used by recipes to
build packages is available in the :term:`Build Directory` as defined by the
:term:`S` variable. Below is the default value for the :term:`S` variable as
defined in the ``meta/conf/bitbake.conf`` configuration file in
-:term:`OpenEmbedded-Core (OE-Core)`::
+:term:`OpenEmbedded-Core (OE-Core)`:
+
+.. code-block:: bitbake
S = "${UNPACKDIR}/${BP}"
@@ -26,7 +28,9 @@ You should be aware that many recipes override the
.. note::
The :term:`BP` represents the base recipe name, which consists of the name
- and version::
+ and version:
+
+ .. code-block:: bitbake
BP = "${BPN}-${PV}"
diff --git a/documentation/dev-manual/upgrading-recipes.rst b/documentation/dev-manual/upgrading-recipes.rst
index cc984bbccbeb..fdbe630393a7 100644
--- a/documentation/dev-manual/upgrading-recipes.rst
+++ b/documentation/dev-manual/upgrading-recipes.rst
@@ -103,7 +103,9 @@ The following steps describe how to set up the AUH utility:
- If you want to enable :ref:`Build
History <dev-manual/build-quality:maintaining build output quality with \`\`buildhistory\`\`>`,
which is optional, you need the following lines in the
- ``conf/local.conf`` file::
+ ``conf/local.conf`` file:
+
+ .. code-block:: bitbake
INHERIT =+ "buildhistory"
BUILDHISTORY_COMMIT = "1"
@@ -115,14 +117,18 @@ The following steps describe how to set up the AUH utility:
- If you want to enable testing through the :ref:`ref-classes-testimage`
class, which is optional, you need to have the following set in
- your ``conf/local.conf`` file::
+ your ``conf/local.conf`` file:
+
+ .. code-block:: bitbake
IMAGE_CLASSES += "testimage"
.. note::
If your distro does not enable by default ptest, which :term:`Poky`
- does, you need the following in your ``local.conf`` file::
+ does, you need the following in your ``local.conf`` file:
+
+ .. code-block:: bitbake
DISTRO_FEATURES:append = " ptest"
diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst
index 18d1bfb0a608..510bc2bcfd91 100644
--- a/documentation/dev-manual/wayland.rst
+++ b/documentation/dev-manual/wayland.rst
@@ -48,7 +48,9 @@ Wayland with Kernel Mode Setting
(`KMS <https://wiki.archlinux.org/index.php/Kernel_Mode_Setting>`__)
support, include the "wayland" flag in the
:term:`DISTRO_FEATURES`
-statement in your ``local.conf`` file::
+statement in your ``local.conf`` file:
+
+.. code-block:: bitbake
DISTRO_FEATURES:append = " wayland"
@@ -63,7 +65,9 @@ Installing Wayland and Weston
To install the Wayland feature into an image, you must include the
following
:term:`CORE_IMAGE_EXTRA_INSTALL`
-statement in your ``local.conf`` file::
+statement in your ``local.conf`` file:
+
+.. code-block:: bitbake
CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
diff --git a/documentation/dev-manual/x32-psabi.rst b/documentation/dev-manual/x32-psabi.rst
index 0a19d28233d8..1bff33a34a3b 100644
--- a/documentation/dev-manual/x32-psabi.rst
+++ b/documentation/dev-manual/x32-psabi.rst
@@ -39,7 +39,9 @@ follows:
- There is support for large images.
To use the x32 psABI, you need to edit your ``conf/local.conf``
-configuration file as follows::
+configuration file as follows:
+
+.. code-block:: bitbake
MACHINE = "qemux86-64"
DEFAULTTUNE = "x86-64-x32"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 04/10] migration-guides: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (2 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 03/10] dev-manual: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 05/10] kernel-dev: " Trevor Woerner
` (8 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 79 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
.../migration-guides/migration-1.3.rst | 8 +++-
.../migration-guides/migration-1.6.rst | 12 +++--
.../migration-guides/migration-1.7.rst | 4 +-
.../migration-guides/migration-1.8.rst | 12 +++--
.../migration-guides/migration-2.0.rst | 8 +++-
.../migration-guides/migration-2.1.rst | 4 +-
.../migration-guides/migration-2.2.rst | 11 +++--
.../migration-guides/migration-2.3.rst | 12 +++--
.../migration-guides/migration-2.5.rst | 4 +-
.../migration-guides/migration-2.6.rst | 12 +++--
.../migration-guides/migration-3.0.rst | 4 +-
.../migration-guides/migration-3.1.rst | 12 +++--
.../migration-guides/migration-3.2.rst | 8 +++-
.../migration-guides/migration-3.3.rst | 8 +++-
.../migration-guides/migration-3.4.rst | 16 +++++--
.../migration-guides/migration-4.0.rst | 12 +++--
.../migration-guides/migration-4.1.rst | 8 +++-
.../migration-guides/migration-4.2.rst | 12 +++--
.../migration-guides/migration-5.1.rst | 12 +++--
.../migration-guides/migration-5.2.rst | 24 +++++++---
.../migration-guides/migration-5.3.rst | 36 +++++++++++----
.../migration-guides/migration-6.0.rst | 44 ++++++++++++++-----
.../migration-guides/migration-6.1.rst | 12 +++--
.../migration-guides/release-notes-4.0.rst | 4 +-
.../migration-guides/release-notes-4.3.rst | 4 +-
.../migration-guides/release-notes-5.0.rst | 4 +-
.../migration-guides/release-notes-5.3.rst | 8 +++-
27 files changed, 236 insertions(+), 79 deletions(-)
diff --git a/documentation/migration-guides/migration-1.3.rst b/documentation/migration-guides/migration-1.3.rst
index 594320d5e1c3..23f54dca96e7 100644
--- a/documentation/migration-guides/migration-1.3.rst
+++ b/documentation/migration-guides/migration-1.3.rst
@@ -29,7 +29,9 @@ location (either local or remote) and then point to it in
:term:`SSTATE_MIRRORS`, you need to append "PATH"
to the end of the mirror URL so that the path used by BitBake before the
mirror substitution is appended to the path used to access the mirror.
-Here is an example::
+Here is an example:
+
+.. code-block:: bitbake
SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
@@ -178,7 +180,9 @@ Linux Kernel Naming
-------------------
The naming scheme for kernel output binaries has been changed to now
-include :term:`PE` as part of the filename::
+include :term:`PE` as part of the filename:
+
+.. code-block:: bitbake
KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
diff --git a/documentation/migration-guides/migration-1.6.rst b/documentation/migration-guides/migration-1.6.rst
index b052a43a3125..aef0b5bce284 100644
--- a/documentation/migration-guides/migration-1.6.rst
+++ b/documentation/migration-guides/migration-1.6.rst
@@ -54,7 +54,9 @@ Matching Branch Requirement for Git Fetching
When fetching source from a Git repository using
:term:`SRC_URI`, BitBake will now validate the
:term:`SRCREV` value against the branch. You can specify
-the branch using the following form::
+the branch using the following form:
+
+.. code-block:: bitbake
SRC_URI = "git://server.name/repository;branch=branchname"
@@ -207,7 +209,9 @@ functions to call and not arbitrary shell commands:
For
migration purposes, you can simply wrap shell commands in a shell
-function and then call the function. Here is an example::
+function and then call the function. Here is an example:
+
+.. code-block:: bitbake
my_postprocess_function() {
echo "hello" > ${IMAGE_ROOTFS}/hello.txt
@@ -247,7 +251,9 @@ the :ref:`ref-classes-autotools` or ``autotools_stage`` classes.
``qemu-native`` now builds without SDL-based graphical output support by
default. The following additional lines are needed in your
-``local.conf`` to enable it::
+``local.conf`` to enable it:
+
+.. code-block:: bitbake
PACKAGECONFIG_pn-qemu-native = "sdl"
ASSUME_PROVIDED += "libsdl-native"
diff --git a/documentation/migration-guides/migration-1.7.rst b/documentation/migration-guides/migration-1.7.rst
index 1a5704fd4da6..c686f6dab10b 100644
--- a/documentation/migration-guides/migration-1.7.rst
+++ b/documentation/migration-guides/migration-1.7.rst
@@ -17,7 +17,9 @@ optional features. The method used to set defaults for these options
means that existing ``local.conf`` files will need to be modified to
append to :term:`PACKAGECONFIG` for ``qemu-native`` and ``nativesdk-qemu``
instead of setting it. In other words, to enable graphical output for
-QEMU, you should now have these lines in ``local.conf``::
+QEMU, you should now have these lines in ``local.conf``:
+
+.. code-block:: bitbake
PACKAGECONFIG_append_pn-qemu-native = " sdl"
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
diff --git a/documentation/migration-guides/migration-1.8.rst b/documentation/migration-guides/migration-1.8.rst
index 5cc5f8a047d8..e7e43fd64e55 100644
--- a/documentation/migration-guides/migration-1.8.rst
+++ b/documentation/migration-guides/migration-1.8.rst
@@ -58,7 +58,9 @@ you can now remove them.
Additionally, a ``bluetooth`` class has been added to make selection of
the appropriate bluetooth support within a recipe a little easier. If
you wish to make use of this class in a recipe, add something such as
-the following::
+the following:
+
+.. code-block:: bitbake
inherit bluetooth
PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
@@ -85,7 +87,9 @@ where the ``linux.inc`` file in ``meta-oe`` was updated.
Recipes that rely on the kernel source code and do not inherit the
:ref:`module <ref-classes-module>` classes might need to add explicit
-dependencies on the :ref:`ref-tasks-shared_workdir` kernel task, for example::
+dependencies on the :ref:`ref-tasks-shared_workdir` kernel task, for example:
+
+.. code-block:: bitbake
do_configure[depends] += "virtual/kernel:do_shared_workdir"
@@ -131,7 +135,9 @@ One of the improvements is to attempt to run "make clean" during the
:ref:`ref-tasks-configure` task if a ``Makefile`` exists. Some software packages
do not provide a working clean target within their make files. If you
have such recipes, you need to set
-:term:`CLEANBROKEN` to "1" within the recipe, for example::
+:term:`CLEANBROKEN` to "1" within the recipe, for example:
+
+.. code-block:: bitbake
CLEANBROKEN = "1"
diff --git a/documentation/migration-guides/migration-2.0.rst b/documentation/migration-guides/migration-2.0.rst
index 13be9846dfb3..f8d14e44c136 100644
--- a/documentation/migration-guides/migration-2.0.rst
+++ b/documentation/migration-guides/migration-2.0.rst
@@ -27,7 +27,9 @@ and the porting guide at
https://gcc.gnu.org/gcc-5/porting_to.html.
Alternatively, you can switch back to GCC 4.9 or 4.8 by setting
-:term:`GCCVERSION` in your configuration, as follows::
+:term:`GCCVERSION` in your configuration, as follows:
+
+.. code-block:: bitbake
GCCVERSION = "4.9%"
@@ -200,7 +202,9 @@ changes.
Additionally, work directories for old versions of recipes are now
pruned. If you wish to disable pruning old work directories, you can set
-the following variable in your configuration::
+the following variable in your configuration:
+
+.. code-block:: bitbake
SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
diff --git a/documentation/migration-guides/migration-2.1.rst b/documentation/migration-guides/migration-2.1.rst
index 4d7aa15af565..bdbc7e4d289f 100644
--- a/documentation/migration-guides/migration-2.1.rst
+++ b/documentation/migration-guides/migration-2.1.rst
@@ -284,7 +284,9 @@ The following changes have been made for the Poky distribution:
Any recipe that needs to opt-out of having the ``--disable-static``
option specified on the configure command line either because it is
not a supported option for the configure script or because static
- libraries are needed should set the following variable::
+ libraries are needed should set the following variable:
+
+ .. code-block:: bitbake
DISABLE_STATIC = ""
diff --git a/documentation/migration-guides/migration-2.2.rst b/documentation/migration-guides/migration-2.2.rst
index 9d50dc62022b..20fe4ad3bfb2 100644
--- a/documentation/migration-guides/migration-2.2.rst
+++ b/documentation/migration-guides/migration-2.2.rst
@@ -224,7 +224,8 @@ follows and run ``runqemu``:
For command-line syntax, use ``runqemu help``.
-::
+
+.. code-block:: bitbake
IMAGE_CLASSES += "qemuboot"
@@ -241,7 +242,9 @@ recipes. You need to fix these recipes so that they use the expected
:term:`LDFLAGS`. Depending on how the software is built, the build system
used by the software (e.g. a Makefile) might need to be patched.
However, sometimes making this fix is as simple as adding the following
-to the recipe::
+to the recipe:
+
+.. code-block:: bitbake
TARGET_CC_ARCH += "${LDFLAGS}"
@@ -254,7 +257,9 @@ The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
:term:`KERNEL_IMAGETYPE` variable to create the
image's base name. Because the OpenEmbedded build system can now build
multiple kernel image types, this part of the kernel image base name as
-been removed leaving only the following::
+been removed leaving only the following:
+
+.. code-block:: bitbake
KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
diff --git a/documentation/migration-guides/migration-2.3.rst b/documentation/migration-guides/migration-2.3.rst
index 60340b9592f1..641be4deb328 100644
--- a/documentation/migration-guides/migration-2.3.rst
+++ b/documentation/migration-guides/migration-2.3.rst
@@ -452,11 +452,15 @@ The following miscellaneous changes have occurred:
tools.
- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
- :term:`DISTRO_FEATURES` feature. Distributions that previously set::
+ :term:`DISTRO_FEATURES` feature. Distributions that previously set:
+
+ .. code-block:: bitbake
USE_LDCONFIG = "0"
- should now instead use the following::
+ should now instead use the following:
+
+ .. code-block:: bitbake
DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
@@ -474,7 +478,9 @@ The following miscellaneous changes have occurred:
order to allow module packages from multiple kernel versions to
co-exist on a target system. If you wish to return to the previous
naming scheme that does not include the version suffix, use the
- following::
+ following:
+
+ .. code-block:: bitbake
KERNEL_MODULE_PACKAGE_SUFFIX = ""
diff --git a/documentation/migration-guides/migration-2.5.rst b/documentation/migration-guides/migration-2.5.rst
index 8e182cd2bc4a..165f15708fc0 100644
--- a/documentation/migration-guides/migration-2.5.rst
+++ b/documentation/migration-guides/migration-2.5.rst
@@ -165,7 +165,9 @@ one of the packages provided by the Python recipe. You can no longer run
``bitbake python-foo`` or have a
:term:`DEPENDS` on ``python-foo``,
but doing either of the following causes the package to work as
-expected::
+expected:
+
+.. code-block:: bitbake
IMAGE_INSTALL_append = " python-foo"
diff --git a/documentation/migration-guides/migration-2.6.rst b/documentation/migration-guides/migration-2.6.rst
index ecb559dd4c32..ac899b0a02b3 100644
--- a/documentation/migration-guides/migration-2.6.rst
+++ b/documentation/migration-guides/migration-2.6.rst
@@ -162,7 +162,9 @@ The following changes have been made:
allows easier and more direct changes.
The :term:`IMAGE_VERSION_SUFFIX` variable is set in the ``bitbake.conf``
- configuration file as follows::
+ configuration file as follows:
+
+ .. code-block:: bitbake
IMAGE_VERSION_SUFFIX = "-${DATETIME}"
@@ -385,7 +387,9 @@ If you wish to disable Python profile-guided optimization regardless of
the value of :term:`MACHINE_FEATURES`, then ensure that
:term:`PACKAGECONFIG` for the ``python3`` recipe
does not contain "pgo". You could accomplish the latter using the
-following at the configuration level::
+following at the configuration level:
+
+.. code-block:: bitbake
PACKAGECONFIG_remove_pn-python3 = "pgo"
@@ -402,7 +406,9 @@ The following miscellaneous changes occurred:
- Default to using the Thumb-2 instruction set for armv7a and above. If
you have any custom recipes that build software that needs to be
built with the ARM instruction set, change the recipe to set the
- instruction set as follows::
+ instruction set as follows:
+
+ .. code-block:: bitbake
ARM_INSTRUCTION_SET = "arm"
diff --git a/documentation/migration-guides/migration-3.0.rst b/documentation/migration-guides/migration-3.0.rst
index f5201dcac24c..5a991dd84367 100644
--- a/documentation/migration-guides/migration-3.0.rst
+++ b/documentation/migration-guides/migration-3.0.rst
@@ -261,7 +261,9 @@ The following miscellaneous changes have occurred.
- The ``gnome`` class has been removed because it now does very little.
You should update recipes that previously inherited this class to do
- the following::
+ the following:
+
+ .. code-block:: bitbake
inherit gnomebase gtk-icon-cache gconf mime
diff --git a/documentation/migration-guides/migration-3.1.rst b/documentation/migration-guides/migration-3.1.rst
index fdb959c4affa..ddb994c3ad2f 100644
--- a/documentation/migration-guides/migration-3.1.rst
+++ b/documentation/migration-guides/migration-3.1.rst
@@ -73,7 +73,9 @@ when building a simple image such as core-image-minimal. If you do not
need runtime tests enabled for core components, then it is recommended
that you remove "ptest" from
:term:`DISTRO_FEATURES` to save a significant
-amount of build time e.g. by adding the following in your configuration::
+amount of build time e.g. by adding the following in your configuration:
+
+.. code-block:: bitbake
DISTRO_FEATURES_remove = "ptest"
@@ -180,12 +182,16 @@ parameter instead of the earlier ``name`` which overlapped with the
generic ``name`` parameter. All recipes using the npm fetcher will need
to be changed as a result.
-An example of the new scheme::
+An example of the new scheme:
+
+.. code-block:: bitbake
SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
npmsw://${THISDIR}/npm-shrinkwrap.json"
-Another example where the sources are fetched from git rather than an npm repository::
+Another example where the sources are fetched from git rather than an npm repository:
+
+.. code-block:: bitbake
SRC_URI = "git://github.com/foo/bar.git;protocol=https \
npmsw://${THISDIR}/npm-shrinkwrap.json"
diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst
index 5cb958e75047..5313c4ebdda2 100644
--- a/documentation/migration-guides/migration-3.2.rst
+++ b/documentation/migration-guides/migration-3.2.rst
@@ -97,7 +97,9 @@ is prefixed on the package names in the dependencies, for example
RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}"
This also applies when conditionally adding packages to :term:`PACKAGES` where
-those packages have dependencies, for example (from the ``alsa-plugins`` recipe)::
+those packages have dependencies, for example (from the ``alsa-plugins`` recipe):
+
+.. code-block:: bitbake
PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
...
@@ -256,7 +258,9 @@ needs ``/etc/ld.so.conf`` to be present at image build time:
When some recipe installs libraries to a non-standard location, and
therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we
-need ``/etc/ld.so.conf`` containing::
+need ``/etc/ld.so.conf`` containing:
+
+.. code-block:: bitbake
include /etc/ld.so.conf.d/*.conf
diff --git a/documentation/migration-guides/migration-3.3.rst b/documentation/migration-guides/migration-3.3.rst
index d1e589d7b486..9c4d449eabb7 100644
--- a/documentation/migration-guides/migration-3.3.rst
+++ b/documentation/migration-guides/migration-3.3.rst
@@ -87,14 +87,18 @@ source tree. Previously this was handled in recipes by setting :term:`S` to
point to the subdirectory within the source where ``setup.py`` is located.
However with the recent :ref:`pseudo <overview-manual/concepts:fakeroot and pseudo>`
changes, some Python modules make changes to files beneath ``${S}``, for
-example::
+example:
+
+.. code-block:: bitbake
S = "${WORKDIR}/git/python/pythonmodule"
then in ``setup.py`` it works with source code in a relative fashion, such
as ``../../src``. This causes pseudo to fail as it isn't able to track
the paths properly. This release introduces a new ``DISTUTILS_SETUP_PATH``
-variable so that recipes can specify it explicitly, for example::
+variable so that recipes can specify it explicitly, for example:
+
+.. code-block:: bitbake
S = "${WORKDIR}/git"
DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
diff --git a/documentation/migration-guides/migration-3.4.rst b/documentation/migration-guides/migration-3.4.rst
index e9cb3a109ea9..4f970b9d4663 100644
--- a/documentation/migration-guides/migration-3.4.rst
+++ b/documentation/migration-guides/migration-3.4.rst
@@ -11,16 +11,22 @@ Override syntax changes
In this release, the ``:`` character replaces the use of ``_`` to
refer to an override, most commonly when making a conditional assignment
-of a variable. This means that an entry like::
+of a variable. This means that an entry like:
+
+.. code-block:: bitbake
SRC_URI_qemux86 = "file://somefile"
-now becomes::
+now becomes:
+
+.. code-block:: bitbake
SRC_URI:qemux86 = "file://somefile"
since ``qemux86`` is an override. This applies to any use of override
-syntax, so the following::
+syntax, so the following:
+
+.. code-block:: bitbake
SRC_URI_append = " file://somefile"
SRC_URI_append_qemux86 = " file://somefile2"
@@ -32,7 +38,9 @@ syntax, so the following::
SRCREV_pn-bash = "abc"
BB_TASK_NICE_LEVEL_task-testimage = '0'
-would now become::
+would now become:
+
+.. code-block:: bitbake
SRC_URI:append = " file://somefile"
SRC_URI:append:qemux86 = " file://somefile2"
diff --git a/documentation/migration-guides/migration-4.0.rst b/documentation/migration-guides/migration-4.0.rst
index c8c2b856d91c..89bc24e7669b 100644
--- a/documentation/migration-guides/migration-4.0.rst
+++ b/documentation/migration-guides/migration-4.0.rst
@@ -74,7 +74,9 @@ Fetching changes
- Because of the uncertainty in future default branch names in git repositories,
it is now required to add a branch name to all URLs described
- by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example::
+ by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example:
+
+ .. code-block:: bitbake
SRC_URI = "git://git.denx.de/u-boot.git;branch=master"
@@ -91,7 +93,9 @@ Fetching changes
- Network access from tasks is now disabled by default on kernels which support
this feature (on most recent distros such as CentOS 8 and Debian 11 onwards).
This means that tasks accessing the network need to be marked as such with the ``network``
- flag. For example::
+ flag. For example:
+
+ .. code-block:: bitbake
do_mytask[network] = "1"
@@ -216,7 +220,9 @@ Miscellaneous changes
- ``blacklist.bbclass`` is removed and the functionality moved to the
:ref:`ref-classes-base` class with a more descriptive
``varflag`` variable named :term:`SKIP_RECIPE` which will use the `bb.parse.SkipRecipe()`
- function. The usage remains the same, for example::
+ function. The usage remains the same, for example:
+
+ .. code-block:: bitbake
SKIP_RECIPE[my-recipe] = "Reason for skipping recipe"
diff --git a/documentation/migration-guides/migration-4.1.rst b/documentation/migration-guides/migration-4.1.rst
index 86721b9873d0..635c08821238 100644
--- a/documentation/migration-guides/migration-4.1.rst
+++ b/documentation/migration-guides/migration-4.1.rst
@@ -88,12 +88,16 @@ Other than knowing where to look when manually browsing the class files, this is
not likely to require any changes to your configuration. However, if in your
configuration you were using some classes in the incorrect context, you will now
receive an error during parsing. For example, the following in ``local.conf`` will
-now cause an error::
+now cause an error:
+
+.. code-block:: bitbake
INHERIT += "testimage"
Since :ref:`ref-classes-testimage` is a class intended solely to
-affect image recipes, this would be correctly specified as::
+affect image recipes, this would be correctly specified as:
+
+.. code-block:: bitbake
IMAGE_CLASSES += "testimage"
diff --git a/documentation/migration-guides/migration-4.2.rst b/documentation/migration-guides/migration-4.2.rst
index f5f12c88710a..6a4de4d8f01c 100644
--- a/documentation/migration-guides/migration-4.2.rst
+++ b/documentation/migration-guides/migration-4.2.rst
@@ -184,7 +184,9 @@ release we limit qemu port forwarding to localhost (127.0.0.1).
However, if you need the qemu machine to be reachable from the
network, then it can be enabled via ``conf/local.conf`` or machine
-config variable ``QB_SLIRP_OPT``::
+config variable ``QB_SLIRP_OPT``:
+
+.. code-block:: bitbake
QB_SLIRP_OPT = "-netdev user,id=net0,hostfwd=tcp::2222-:22"
@@ -233,7 +235,9 @@ Miscellaneous changes
- The :term:`IMAGE_NAME` variable is now set based on :term:`IMAGE_LINK_NAME`. This
means that if you are setting :term:`IMAGE_LINK_NAME` to "" to disable unversioned
image symlink creation, you also now need to set :term:`IMAGE_NAME` to still have
- a reasonable value e.g.::
+ a reasonable value e.g.:
+
+ .. code-block:: bitbake
IMAGE_LINK_NAME = ""
IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
@@ -271,6 +275,8 @@ Miscellaneous changes
scons in order to fix an issue with scons and command line lengths when ccache is
enabled. However, some recipes may be using older scons versions which don't support
this argument. If that is the case you can set the following in the recipe in order
- to disable this::
+ to disable this:
+
+ .. code-block:: bitbake
SCONS_MAXLINELENGTH = ""
diff --git a/documentation/migration-guides/migration-5.1.rst b/documentation/migration-guides/migration-5.1.rst
index 70e034bc846f..9ea68d8d5aca 100644
--- a/documentation/migration-guides/migration-5.1.rst
+++ b/documentation/migration-guides/migration-5.1.rst
@@ -18,7 +18,9 @@ S = ${WORKDIR} no longer supported
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If a recipe has :term:`S` set to be :term:`WORKDIR`, this is no longer
-supported, and an error will be issued. The recipe should be changed to::
+supported, and an error will be issued. The recipe should be changed to:
+
+.. code-block:: bitbake
S = "${UNPACKDIR}"
@@ -59,7 +61,9 @@ longer the case. This means the check in ``do_unpack_qa`` triggers where
:term:`S` is not created by a recipe while it didn't happen before. This can
require to add an :term:`S` definition to a recipe that only uses
``file://`` :term:`SRC_URI` entries. To be consistent, the following pattern is
-recommended::
+recommended:
+
+.. code-block:: bitbake
S = "${UNPACKDIR}"
@@ -105,7 +109,9 @@ Go language changes
- After dropping the custom :ref:`ref-tasks-unpack` from the
:ref:`ref-classes-go` class, go recipes should now add
``destsuffix=${GO_SRCURI_DESTSUFFIX}`` to their :term:`SRC_URI` to extract
- them in the appropriate path. An example would be::
+ them in the appropriate path. An example would be:
+
+ .. code-block:: bitbake
SRC_URI = "git://go.googlesource.com/example;branch=master;protocol=https;destsuffix=${GO_SRCURI_DESTSUFFIX}"
diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
index 77a11fe27047..c30f4097aac1 100644
--- a/documentation/migration-guides/migration-5.2.rst
+++ b/documentation/migration-guides/migration-5.2.rst
@@ -29,7 +29,9 @@ should be manually added to the :term:`IMAGE_FEATURES` variable. These are:
- ``empty-root-password``
- ``post-install-logging``
-Such a statement would be::
+Such a statement would be:
+
+.. code-block:: bitbake
IMAGE_FEATURES += "allow-empty-password allow-root-login empty-root-password post-install-logging"
@@ -177,11 +179,15 @@ c++/binutils)" </openembedded-core/commit/?id=4ccc3bc8266c>` in
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :term:`UBOOT_ENTRYPOINT` variable should now be defined with a leading
-``0x`` to its value. For example, consider the following assignment::
+``0x`` to its value. For example, consider the following assignment:
+
+.. code-block:: bitbake
UBOOT_ENTRYPOINT ?= "20008000"
-This should now be replaced by::
+This should now be replaced by:
+
+.. code-block:: bitbake
UBOOT_ENTRYPOINT ?= "0x20008000"
@@ -191,7 +197,9 @@ Git fetcher: support for multiple revisions per URL removed
The support for having multiple Git revisions per URL in :term:`SRC_URI` was
removed from BitBake, which means the following syntax is not supported
-anymore::
+anymore:
+
+.. code-block:: bitbake
SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY"
SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
@@ -203,7 +211,9 @@ take care of the Git checkout. This removal simplifies the code logic in several
places.
If one of your recipes is using this mechanism, you can split the code source
-fetching into two separate entries::
+fetching into two separate entries:
+
+.. code-block:: bitbake
SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \
git://some.host/somepath;bareclone=1;branch=branchY;name=nameY"
@@ -214,7 +224,9 @@ Git fetcher: Branch parameter now required in :term:`SRC_URI`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``branch`` parameter is now required when specifying a Git repository in
-:term:`SRC_URI`, for example::
+:term:`SRC_URI`, for example:
+
+.. code-block:: bitbake
SRC_URI = "git://some.host/somepath;branch=branchX"
diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
index 38c7d6771667..d947a4de7a1a 100644
--- a/documentation/migration-guides/migration-5.3.rst
+++ b/documentation/migration-guides/migration-5.3.rst
@@ -50,7 +50,9 @@ in: https://lists.openembedded.org/g/openembedded-architecture/message/2179
If a recipe has :term:`S` set to be ``${``\ :term:`WORKDIR`\ ``}/something``,
this is no longer supported, and an error will be issued. The recipe should be
-changed to::
+changed to:
+
+.. code-block:: bitbake
S = "${UNPACKDIR}/something"
@@ -69,7 +71,9 @@ This location matches the default value of :term:`S` set by bitbake.conf, so :te
setting in recipes can and should be removed.
Note that when :term:`S` is set to a subdirectory of the git checkout, then it
-should be instead adjusted according to the previous point::
+should be instead adjusted according to the previous point:
+
+.. code-block:: bitbake
S = "${UNPACKDIR}/${BP}/something"
@@ -112,13 +116,17 @@ assignment in recipes::
<filename>:<line number> has a lack of whitespace around the assignment: '<assignment>'
-For example, the following assignments would print a warning::
+For example, the following assignments would print a warning:
+
+.. code-block:: bitbake
FOO="bar"
FOO= "bar"
FOO ="bar"
-These should be replaced by::
+These should be replaced by:
+
+.. code-block:: bitbake
FOO = "bar"
@@ -179,14 +187,18 @@ overview of the removed firmware.
The :term:`CPPFLAGS`, :term:`CFLAGS`, :term:`CXXFLAGS` and :term:`LDFLAGS`
variables used to have hard assignments in the :ref:`ref-classes-native` and
-:ref:`ref-classes-nativesdk` classes, respectively::
+:ref:`ref-classes-nativesdk` classes, respectively:
+
+.. code-block:: bitbake
CPPFLAGS = "${BUILD_CPPFLAGS}"
CFLAGS = "${BUILD_CFLAGS}"
CXXFLAGS = "${BUILD_CXXFLAGS}"
LDFLAGS = "${BUILD_LDFLAGS}"
-and::
+and:
+
+.. code-block:: bitbake
CPPFLAGS = "${BUILDSDK_CPPFLAGS}"
CFLAGS = "${BUILDSDK_CFLAGS}"
@@ -206,11 +218,15 @@ three**: target, :ref:`ref-classes-native` and :ref:`ref-classes-nativesdk`
contexts.
Recipes that unknowingly relied on this behavior should change these assignments
-to use ``TARGET_`` variables instead, for example::
+to use ``TARGET_`` variables instead, for example:
+
+.. code-block:: bitbake
CFLAGS += "something"
-to::
+to:
+
+.. code-block:: bitbake
TARGET_CFLAGS += "something"
@@ -305,7 +321,9 @@ The following classes have been removed in this release:
#. Make sure to include ``kernel-fit-extra-artifacts`` in your :term:`KERNEL_CLASSES`
variable to ensure the required files are exposed to the :term:`DEPLOY_DIR_IMAGE`
- directory::
+ directory:
+
+ .. code-block:: bitbake
KERNEL_CLASSES += "kernel-fit-extra-artifacts"
diff --git a/documentation/migration-guides/migration-6.0.rst b/documentation/migration-guides/migration-6.0.rst
index 5ad284600002..54323d5961aa 100644
--- a/documentation/migration-guides/migration-6.0.rst
+++ b/documentation/migration-guides/migration-6.0.rst
@@ -88,7 +88,9 @@ This does not change the default init manager of the :term:`Poky` distribution,
which remains :wikipedia:`SysVinit <UNIX_System_V>`.
Reverting to :wikipedia:`SysVinit <UNIX_System_V>` can be done by specifying the
-:term:`INIT_MANAGER` in your own :term:`DISTRO` configuration file::
+:term:`INIT_MANAGER` in your own :term:`DISTRO` configuration file:
+
+.. code-block:: bitbake
INIT_MANAGER = "sysvinit"
@@ -189,7 +191,9 @@ Previously, setting :term:`DEBUG_BUILD` to "1" globally would prevent the
changed so that only **target** binaries are stripped when this variable is set.
This change can be reverted by setting the two following lines in a
-:term:`configuration file`::
+:term:`configuration file`:
+
+.. code-block:: bitbake
INHIBIT_SYSROOT_STRIP:class-cross = "${@oe.utils.vartrue('DEBUG_BUILD', '1', '', d)}"
INHIBIT_SYSROOT_STRIP:class-native = "${@oe.utils.vartrue('DEBUG_BUILD', '1', '', d)}"
@@ -202,13 +206,17 @@ U-Boot configuration flow changes (:ref:`ref-classes-uboot-config`)
-------------------------------------------------------------------
Declaring multiple U-Boot configurations used to be entirely defined by
-one :term:`UBOOT_CONFIG` variable flag per configuration, e.g.::
+one :term:`UBOOT_CONFIG` variable flag per configuration, e.g.:
+
+.. code-block:: bitbake
UBOOT_CONFIG ??= "foo bar"
UBOOT_CONFIG[foo] = "config,images,binary"
UBOOT_CONFIG[bar] = "config2,images2,binary2"
-This has now been split into more variable flags, e.g.::
+This has now been split into more variable flags, e.g.:
+
+.. code-block:: bitbake
UBOOT_CONFIG ??= "foo bar"
UBOOT_CONFIG[foo] = "config"
@@ -233,7 +241,9 @@ See commit :oecore_rev:`cd9e7304481b24b27df61c03ad73496d18e4d47c` for more infor
.. note::
Single configuration builds have not changed and are still declared using the
- following statements::
+ following statements:
+
+ .. code-block:: bitbake
UBOOT_MACHINE = "config"
UBOOT_BINARY = "u-boot.bin"
@@ -249,7 +259,9 @@ Variables to the Environment>` directive.
These ``export`` statements have been moved to the :ref:`ref-classes-pkgconfig`
class, meaning recipes using these variables that not yet inheriting the
-:ref:`ref-classes-pkgconfig` class should now inherit it with::
+:ref:`ref-classes-pkgconfig` class should now inherit it with:
+
+.. code-block:: bitbake
inherit pkgconfig
@@ -322,11 +334,15 @@ The ``cve-check`` class was removed and replaced by the
Users currently using the ``cve-check`` class are advised to switch to
:ref:`ref-classes-sbom-cve-check`:
-- The following assignment::
+- The following assignment:
+
+ .. code-block:: bitbake
INHERIT += "cve-check"
- Should be removed and replaced by::
+ Should be removed and replaced by:
+
+ .. code-block:: bitbake
OE_FRAGMENTS += "core/yocto/sbom-cve-check"
@@ -345,7 +361,9 @@ Users currently using the ``cve-check`` class are advised to switch to
- The ``cve-check`` class output summary file (deployed in the
:term:`DEPLOY_DIR_IMAGE`) ending with ``.cve.txt`` is no longer
deployed by default but can be brought back by adding the following statement
- to a configuration file::
+ to a configuration file:
+
+ .. code-block:: bitbake
SBOM_CVE_CHECK_EXPORT_VARS:append = " SBOM_CVE_CHECK_EXPORT_SUMMARY"
@@ -395,11 +413,15 @@ the console when used::
Using the ``--sector-size`` command-line argument can be done through the
:term:`WIC_CREATE_EXTRA_ARGS` variable.
-For example, a previous assignment to :term:`WIC_SECTOR_SIZE`::
+For example, a previous assignment to :term:`WIC_SECTOR_SIZE`:
+
+.. code-block:: bitbake
WIC_SECTOR_SIZE = "4096"
-Should be replaced by::
+Should be replaced by:
+
+.. code-block:: bitbake
WIC_CREATE_EXTRA_ARGS += "--sector-size 4096"
diff --git a/documentation/migration-guides/migration-6.1.rst b/documentation/migration-guides/migration-6.1.rst
index 025b8f70926c..019a3495cc76 100644
--- a/documentation/migration-guides/migration-6.1.rst
+++ b/documentation/migration-guides/migration-6.1.rst
@@ -44,17 +44,23 @@ version 4.20. The same functionality provided by ``groupmems`` can be achieved
with the ``usermod`` command.
Assignments made to the :term:`GROUPMEMS_PARAM` variable can be converted to use
-:term:`USERMOD_PARAMS`, by replacing::
+:term:`USERMOD_PARAMS`, by replacing:
+
+.. code-block:: bitbake
GROUPMEMS_PARAM:${PN} = "--add user --group group1; \
--add user --group group2"
-With::
+With:
+
+.. code-block:: bitbake
USERMOD_PARAM:${PN} = "--append --groups group1 user; \
--append --groups group2 user"
-Or written more simply as::
+Or written more simply as:
+
+.. code-block:: bitbake
USERMOD_PARAM:${PN} = "--append --groups group1,group2 user"
diff --git a/documentation/migration-guides/release-notes-4.0.rst b/documentation/migration-guides/release-notes-4.0.rst
index e9e694952799..683873e94c70 100644
--- a/documentation/migration-guides/release-notes-4.0.rst
+++ b/documentation/migration-guides/release-notes-4.0.rst
@@ -21,7 +21,9 @@ New Features / Enhancements in 4.0
its autobuilder. If the network connection between our server and your
machine is faster than you would build recipes from source, you can
try to speed up your builds by using such Shared State and Hash
- Equivalence by setting::
+ Equivalence by setting:
+
+ .. code-block:: bitbake
BB_SIGNATURE_HANDLER = "OEEquivHash"
BB_HASHSERVE = "auto"
diff --git a/documentation/migration-guides/release-notes-4.3.rst b/documentation/migration-guides/release-notes-4.3.rst
index 76afd16e84fc..9ec3f3a0a2ad 100644
--- a/documentation/migration-guides/release-notes-4.3.rst
+++ b/documentation/migration-guides/release-notes-4.3.rst
@@ -45,7 +45,9 @@ New Features / Enhancements in 4.3
Code can now know which layer a recipe is coming from through the newly added :term:`FILE_LAYERNAME`
variable. This has been added as an override of the form ``layer-<layername>``. In particular,
- this means QA checks can now be layer specific, for example::
+ this means QA checks can now be layer specific, for example:
+
+ .. code-block:: bitbake
ERROR_QA:layer-core:append = " patch-status"
diff --git a/documentation/migration-guides/release-notes-5.0.rst b/documentation/migration-guides/release-notes-5.0.rst
index b802e7c1718e..29d53df58b97 100644
--- a/documentation/migration-guides/release-notes-5.0.rst
+++ b/documentation/migration-guides/release-notes-5.0.rst
@@ -195,7 +195,9 @@ New Features / Enhancements in 5.0
- New ``inherit_defer`` statement which works as
:ref:`inherit <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` directive>`
does, except that it is only evaluated at the end of parsing
- --- recommended where a conditional expression is used, e.g.::
+ --- recommended where a conditional expression is used, e.g.:
+
+ .. code-block:: bitbake
inherit_defer ${@bb.utils.contains('PACKAGECONFIG', 'python', 'python3targetconfig', '', d)}
diff --git a/documentation/migration-guides/release-notes-5.3.rst b/documentation/migration-guides/release-notes-5.3.rst
index ee9df424ee2e..8d098cd7fec8 100644
--- a/documentation/migration-guides/release-notes-5.3.rst
+++ b/documentation/migration-guides/release-notes-5.3.rst
@@ -92,7 +92,9 @@ New Features / Enhancements in |yocto-ver|
distro/... Sets DISTRO = ...
In the above example, this means that the :term:`MACHINE` of
- :term:`DISTRO` can be overridden with::
+ :term:`DISTRO` can be overridden with:
+
+ .. code-block:: bitbake
OE_FRAGMENTS += "machine/qemuarm64 distro/poky-bleeding"
@@ -928,7 +930,9 @@ New Features / Enhancements in |yocto-ver|
:ref:`qa-check-pep517-backend` QA check.
- The :ref:`ref-classes-ccache` class now supports using `Ccache` for native
- recipes when the local build configuration contains::
+ recipes when the local build configuration contains:
+
+ .. code-block:: bitbake
ASSUME_PROVIDED += "ccache-native"
HOSTTOOLS += "ccache"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 05/10] kernel-dev: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (3 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 04/10] migration-guides: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 06/10] test-manual: " Trevor Woerner
` (7 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 41 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
documentation/kernel-dev/advanced.rst | 48 +++++++++++----
documentation/kernel-dev/common.rst | 88 ++++++++++++++++++++-------
documentation/kernel-dev/faq.rst | 8 ++-
3 files changed, 108 insertions(+), 36 deletions(-)
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
index b36bea67ccd2..644fa2bd0a3d 100644
--- a/documentation/kernel-dev/advanced.rst
+++ b/documentation/kernel-dev/advanced.rst
@@ -66,7 +66,9 @@ to indicate the branch.
.. note::
You can use the :term:`KBRANCH` value to define an alternate branch typically
- with a machine override as shown here from the ``meta-yocto-bsp`` layer::
+ with a machine override as shown here from the ``meta-yocto-bsp`` layer:
+
+ .. code-block:: bitbake
KBRANCH:beaglebone-yocto = "standard/beaglebone"
@@ -103,13 +105,17 @@ You can use the
variable to include features (configuration fragments, patches, or both)
that are not already included by the :term:`KMACHINE` and
:term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a
-feature specified as "features/netfilter/netfilter.scc", specify::
+feature specified as "features/netfilter/netfilter.scc", specify:
+
+.. code-block:: bitbake
KERNEL_FEATURES += "features/netfilter/netfilter.scc"
To include a
feature called "cfg/sound.scc" just for the ``qemux86`` machine,
-specify::
+specify:
+
+.. code-block:: bitbake
KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc"
@@ -359,13 +365,17 @@ variable in the kernel recipe selects the kernel type. For example, in the
``linux-yocto_4.12.bb`` kernel recipe found in ``meta/recipes-kernel/linux``, a
:ref:`require <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>`
directive includes the ``meta/recipes-kernel/linux/linux-yocto.inc`` file,
-which has the following statement that defines the default kernel type::
+which has the following statement that defines the default kernel type:
+
+.. code-block:: bitbake
LINUX_KERNEL_TYPE ??= "standard"
Another example would be the real-time kernel (i.e.
``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel
-type as follows::
+type as follows:
+
+.. code-block:: bitbake
LINUX_KERNEL_TYPE = "preempt-rt"
@@ -514,7 +524,9 @@ description file match.
To separate your kernel policy from your hardware configuration, you
include a kernel type (``ktype``), such as "standard". In the previous
-example, this is done using the following::
+example, this is done using the following:
+
+.. code-block:: bitbake
include ktypes/standard/standard.scc
@@ -524,11 +536,15 @@ policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more
information.
To aggregate common configurations and features specific to the kernel
-for `mybsp`, use the following::
+for `mybsp`, use the following:
+
+.. code-block:: bitbake
include mybsp.scc
-You can see that in the BeagleBone example with the following::
+You can see that in the BeagleBone example with the following:
+
+.. code-block:: bitbake
include beaglebone.scc
@@ -713,7 +729,9 @@ value when changing the content of files not explicitly listed in the
If the BSP description is in recipe space, you cannot simply list the
``*.scc`` in the :term:`SRC_URI` statement. You need to use the following
-form from your kernel append file::
+form from your kernel append file:
+
+.. code-block:: bitbake
SRC_URI:append:myplatform = " \
file://myplatform;type=kmeta;destsuffix=myplatform \
@@ -739,7 +757,9 @@ reside in a separate repository. The OpenEmbedded build system adds the
Metadata to the build as a "type=kmeta" repository through the
:term:`SRC_URI` variable. As an
example, consider the following :term:`SRC_URI` statement from the
-``linux-yocto_5.15.bb`` kernel recipe::
+``linux-yocto_5.15.bb`` kernel recipe:
+
+.. code-block:: bitbake
SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \
git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https"
@@ -784,7 +804,9 @@ This is why a recipe-space BSP description must be delivered as a
:term:`SRC_URI` (see the
":ref:`kernel-dev/advanced:recipe-space metadata`" section). To have your
description discovered, place it in a ``type=kmeta`` directory and set
-:term:`KMACHINE` so the tools locate it::
+:term:`KMACHINE` so the tools locate it:
+
+.. code-block:: bitbake
KMACHINE:myplatform ?= "myplatform"
@@ -868,7 +890,9 @@ patches into a feature.
Once you have a new branch, you can set up your kernel Metadata to use
the branch a couple different ways. In the recipe, you can specify the
-new branch as the :term:`KBRANCH` to use for the board as follows::
+new branch as the :term:`KBRANCH` to use for the board as follows:
+
+.. code-block:: bitbake
KBRANCH = "mynewbranch"
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 948718433440..8b80a4afde59 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -60,7 +60,9 @@ section:
In this example we wish to build for qemux86 so we must set the
:term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
- As described we do this by appending to ``conf/local.conf``::
+ As described we do this by appending to ``conf/local.conf``:
+
+ .. code-block:: bitbake
MACHINE = "qemux86"
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
@@ -156,7 +158,9 @@ section:
In this example we wish to build for qemux86 so we must set the
:term:`MACHINE` variable to "qemux86" and also add the "kernel-modules".
- As described we do this by appending to ``conf/local.conf``::
+ As described we do this by appending to ``conf/local.conf``:
+
+ .. code-block:: bitbake
MACHINE = "qemux86"
MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
@@ -302,7 +306,9 @@ home directory:
``meta-mylayer/recipes-kernel/linux`` directory and create the
kernel's append file. This example uses the ``linux-yocto-4.12``
kernel. Thus, the name of the append file is
- ``linux-yocto_4.12.bbappend``::
+ ``linux-yocto_4.12.bbappend``:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
@@ -354,7 +360,9 @@ The append file should initially extend the
:term:`FILESPATH` search path by
prepending the directory that contains your files to the
:term:`FILESEXTRAPATHS`
-variable as follows::
+variable as follows:
+
+.. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
@@ -380,7 +388,9 @@ As an example, consider the following append file used by the BSPs in
Here are the contents of this file. Be aware that the actual commit ID
strings in this example listing might be different than the actual
-strings in the file from the ``meta-yocto-bsp`` layer upstream::
+strings in the file from the ``meta-yocto-bsp`` layer upstream:
+
+.. code-block:: bitbake
KBRANCH:genericx86 = "v6.1/standard/base"
KBRANCH:genericx86-64 = "v6.1/standard/base"
@@ -436,7 +446,9 @@ For example, suppose you had some configuration options in a file called
``network_configs.cfg``. You can place that file inside a directory
named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the
following to the append file. When the OpenEmbedded build system builds
-the kernel, the configuration options are picked up and applied::
+the kernel, the configuration options are picked up and applied:
+
+.. code-block:: bitbake
SRC_URI += "file://network_configs.cfg"
@@ -444,7 +456,9 @@ To group related configurations into multiple files, you perform a
similar procedure. Here is an example that groups separate
configurations specifically for Ethernet and graphics into their own
files and adds the configurations by using a :term:`SRC_URI` statement like
-the following in your append file::
+the following in your append file:
+
+.. code-block:: bitbake
SRC_URI += "file://myconfig.cfg \
file://eth.cfg \
@@ -488,7 +502,9 @@ reference them in :term:`SRC_URI`
statements.
For example, you can apply a three-patch series by adding the following
-lines to your linux-yocto ``.bbappend`` file in your layer::
+lines to your linux-yocto ``.bbappend`` file in your layer:
+
+.. code-block:: bitbake
SRC_URI += "file://0001-first-change.patch"
SRC_URI += "file://0002-second-change.patch"
@@ -518,7 +534,9 @@ If you have a complete, working Linux kernel ``.config`` file you want
to use for the configuration, as before, copy that file to the
appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux``
directory, and rename the copied file to "defconfig". Then, add the
-following lines to the linux-yocto ``.bbappend`` file in your layer::
+following lines to the linux-yocto ``.bbappend`` file in your layer:
+
+.. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://defconfig"
@@ -535,7 +553,9 @@ You can also use a regular ``defconfig`` file, as generated by the
task instead of a complete ``.config`` file. This only specifies the
non-default configuration values. You need to additionally set
:term:`KCONFIG_MODE`
-in the linux-yocto ``.bbappend`` file in your layer::
+in the linux-yocto ``.bbappend`` file in your layer:
+
+.. code-block:: bitbake
KCONFIG_MODE = "alldefconfig"
@@ -565,7 +585,9 @@ with the following content (without indentation)::
Next, include this
configuration fragment and extend the :term:`FILESPATH` variable in your
-``.bbappend`` file::
+``.bbappend`` file:
+
+.. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://8250.cfg"
@@ -584,7 +606,9 @@ It might be desirable to have kernel configuration fragment support
through a ``defconfig`` file that is pulled from the kernel source tree
for the configured machine. By default, the OpenEmbedded build system
looks for ``defconfig`` files in the layer used for Metadata, which is
-"out-of-tree", and then configures them using the following::
+"out-of-tree", and then configures them using the following:
+
+.. code-block:: bitbake
SRC_URI += "file://defconfig"
@@ -604,7 +628,9 @@ form::
Here is an example that assigns the :term:`KBUILD_DEFCONFIG` variable utilizing
an override for the "raspberrypi2" :term:`MACHINE` and provides the path to the
"in-tree" ``defconfig`` file to be used for a Raspberry Pi 2, which is based on
-the Broadcom 2708/2709 chipset::
+the Broadcom 2708/2709 chipset:
+
+.. code-block:: bitbake
KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig"
@@ -841,7 +867,9 @@ Section.
$ cd bitbake-builds/build/conf
- Add the following to the ``local.conf``::
+ Add the following to the ``local.conf``:
+
+ .. code-block:: bitbake
SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \
git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}"
@@ -912,7 +940,9 @@ Section.
the OpenEmbedded build system to find the patch. The append file
needs to be in your layer's ``recipes-kernel/linux`` directory and it
must be named ``linux-yocto_4.12.bbappend`` and have the following
- contents::
+ contents:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch"
@@ -1087,7 +1117,9 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied
file to "defconfig" (e.g.
``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then,
add the following lines to the linux-yocto ``.bbappend`` file in your
-layer::
+layer:
+
+.. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://defconfig"
@@ -1197,7 +1229,9 @@ options in a file called ``myconfig.cfg``. If you put that file inside a
directory named ``linux-yocto`` that resides in the same directory as
the kernel's append file within your layer and then add the following
statements to the kernel's append file, those configuration options will
-be picked up and applied when the kernel is built::
+be picked up and applied when the kernel is built:
+
+.. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://myconfig.cfg"
@@ -1206,7 +1240,9 @@ As mentioned earlier, you can group related configurations into multiple
files and name them all in the :term:`SRC_URI` statement as well. For
example, you could group separate configurations specifically for
Ethernet and graphics into their own files and add those by using a
-:term:`SRC_URI` statement like the following in your append file::
+:term:`SRC_URI` statement like the following in your append file:
+
+.. code-block:: bitbake
SRC_URI += "file://myconfig.cfg \
file://eth.cfg \
@@ -1510,7 +1546,9 @@ Here are some basic steps you can use to work with your own sources:
triggers an explicit build failure. You must change it to match a
list of the machines that your new recipe supports. For example,
to support the ``qemux86`` and ``qemux86-64`` machines, use the
- following form::
+ following form:
+
+ .. code-block:: bitbake
COMPATIBLE_MACHINE = "qemux86|qemux86-64"
@@ -1622,7 +1660,9 @@ them appropriately for your machine configuration file:
- :term:`MACHINE_EXTRA_RRECOMMENDS`
Modules are often not required for boot and can be excluded from certain
-build configurations. The following allows for the most flexibility::
+build configurations. The following allows for the most flexibility:
+
+.. code-block:: bitbake
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
@@ -1769,7 +1809,9 @@ build.
a similarly named configuration fragment file ``test.cfg``.
#. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the
- recipe's :term:`SRC_URI` statement::
+ recipe's :term:`SRC_URI` statement:
+
+ .. code-block:: bitbake
SRC_URI += "file://test.scc"
@@ -1778,7 +1820,9 @@ build.
#. *Specify the Feature as a Kernel Feature:* Use the
:term:`KERNEL_FEATURES` statement to specify the feature as a kernel
- feature::
+ feature:
+
+ .. code-block:: bitbake
KERNEL_FEATURES += "test.scc"
diff --git a/documentation/kernel-dev/faq.rst b/documentation/kernel-dev/faq.rst
index 4dffa90dbd03..a5cd09dcfbaa 100644
--- a/documentation/kernel-dev/faq.rst
+++ b/documentation/kernel-dev/faq.rst
@@ -57,7 +57,9 @@ These other variables are useful for installing specific modules:
For example, set the following in the ``qemux86.conf`` file to include
the ``ab123`` kernel modules with images built for the ``qemux86``
-machine::
+machine:
+
+.. code-block:: bitbake
MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
@@ -70,7 +72,9 @@ How do I change the Linux kernel command line?
The Linux kernel command line is
typically specified in the machine config using the :term:`APPEND` variable.
For example, you can add some helpful debug information doing the
-following::
+following:
+
+.. code-block:: bitbake
APPEND += "printk.time=y initcall_debug debug"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 06/10] test-manual: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (4 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 05/10] kernel-dev: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 07/10] overview-manual: " Trevor Woerner
` (6 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 27 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
documentation/test-manual/intro.rst | 4 +-
documentation/test-manual/ptest.rst | 24 ++++++---
.../test-manual/reproducible-builds.rst | 8 ++-
documentation/test-manual/runtime-testing.rst | 52 ++++++++++++++-----
4 files changed, 66 insertions(+), 22 deletions(-)
diff --git a/documentation/test-manual/intro.rst b/documentation/test-manual/intro.rst
index 4ddc9851f824..614622daabfb 100644
--- a/documentation/test-manual/intro.rst
+++ b/documentation/test-manual/intro.rst
@@ -253,7 +253,9 @@ Tests map into the codebase as follows:
- The code for these tests resides in ``meta/lib/oeqa/runtime/cases/``.
- - You need to set the :term:`IMAGE_CLASSES` variable as follows::
+ - You need to set the :term:`IMAGE_CLASSES` variable as follows:
+
+ .. code-block:: bitbake
IMAGE_CLASSES += "testimage"
diff --git a/documentation/test-manual/ptest.rst b/documentation/test-manual/ptest.rst
index 2b86722145da..9c4b74f44c58 100644
--- a/documentation/test-manual/ptest.rst
+++ b/documentation/test-manual/ptest.rst
@@ -38,7 +38,9 @@ Adding package testing to your image is done in two steps:
#. Identify which of those ptest packages to add to your image.
First, in order to build all ptest packages, add the following line
-to a :term:`configuration file`::
+to a :term:`configuration file`:
+
+.. code-block:: bitbake
DISTRO_FEATURES:append = " ptest"
@@ -46,12 +48,16 @@ Note that this will cause all ptest packages to be built and packaged,
but will not add any of those packages to your image; that comes in
the next step. You can then add ptest packages to your image in one of two ways.
-#. If you want to add *all* of the generated ptest packages, add the line::
+#. If you want to add *all* of the generated ptest packages, add the line:
+
+ .. code-block:: bitbake
EXTRA_IMAGE_FEATURES += "ptest-pkgs"
#. On the other hand, if you want to add only a select few of the ptest
- packages, you can use some variation of::
+ packages, you can use some variation of:
+
+ .. code-block:: bitbake
IMAGE_INSTALL:append = " e2fsprogs-ptest zlib-ptest"
@@ -95,7 +101,9 @@ you need to prepare the recipes that build the packages you want to
test. Here is what you have to do for each recipe:
- *Be sure the recipe inherits the* :ref:`ref-classes-ptest` *class:*
- Include the following line in each recipe::
+ Include the following line in each recipe:
+
+ .. code-block:: bitbake
inherit ptest
@@ -148,7 +156,9 @@ test. Here is what you have to do for each recipe:
:term:`DEPENDS` and
:term:`RDEPENDS` variables in
your recipe in order for the package to meet the dependencies. Here
- is an example where the package has a runtime dependency on "make"::
+ is an example where the package has a runtime dependency on "make":
+
+ .. code-block:: bitbake
RDEPENDS:${PN}-ptest += "make"
@@ -169,7 +179,9 @@ test. Here is what you have to do for each recipe:
Regardless, you still must add a ``do_compile_ptest`` function to
build the test suite. Add a function similar to the following to your
- recipe::
+ recipe:
+
+ .. code-block:: bitbake
do_compile_ptest() {
oe_runmake buildtest-TESTS
diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst
index 84523ff13f9d..9e2502802390 100644
--- a/documentation/test-manual/reproducible-builds.rst
+++ b/documentation/test-manual/reproducible-builds.rst
@@ -95,7 +95,9 @@ This defaults to including a ``world`` build so, if other layers are added, it
would also run the tests for recipes in the additional layers. Different build
targets can be defined using the :term:`OEQA_REPRODUCIBLE_TEST_TARGET` variable
in ``local.conf``. For example, running reproducibility tests for only the
-``python3-numpy`` recipe can be done by setting::
+``python3-numpy`` recipe can be done by setting:
+
+.. code-block:: bitbake
OEQA_REPRODUCIBLE_TEST_TARGET = "python3-numpy"
@@ -150,7 +152,9 @@ Using :term:`OEQA_REPRODUCIBLE_TEST_* <OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS>` var
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to test the reproducibility of a set of recipes, you can define
-:term:`OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS`, in your local.conf::
+:term:`OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS`, in your local.conf:
+
+.. code-block:: bitbake
OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS = "my-recipe"
diff --git a/documentation/test-manual/runtime-testing.rst b/documentation/test-manual/runtime-testing.rst
index a64a97c80833..e1c1d3b85625 100644
--- a/documentation/test-manual/runtime-testing.rst
+++ b/documentation/test-manual/runtime-testing.rst
@@ -185,7 +185,9 @@ not need any information in this section. You can skip down to the
If you did set :term:`TEST_TARGET` to "SystemdbootTarget", you also need to
perform a one-time setup of your controller image by doing the following:
-#. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows::
+#. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows:
+
+ .. code-block:: bitbake
EFI_PROVIDER = "systemd-boot"
@@ -223,7 +225,9 @@ The final thing you need to do when setting :term:`TEST_TARGET` to
"SystemdbootTarget" is to set up the test image:
#. *Set up your local.conf file:* Make sure you have the following
- statements in your ``local.conf`` file::
+ statements in your ``local.conf`` file:
+
+ .. code-block:: bitbake
IMAGE_FSTYPES += "tar.gz"
IMAGE_CLASSES += "testimage"
@@ -244,7 +248,9 @@ power:
:term:`TEST_POWERCONTROL_EXTRA_ARGS` as a command that runs on the host
and does power cycling. The test code passes one argument to that
command: off, on or cycle (off then on). Here is an example that
- could appear in your ``local.conf`` file::
+ could appear in your ``local.conf`` file:
+
+ .. code-block:: bitbake
TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1"
@@ -277,7 +283,9 @@ wish to experiment with automated hardware testing, you can use the
the required power action. This script requires either KDialog or Zenity
to be installed. To use this script, set the
:term:`TEST_POWERCONTROL_CMD`
-variable as follows::
+variable as follows:
+
+.. code-block:: bitbake
TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control"
@@ -299,7 +307,9 @@ connecting to a remote console server. Regardless of the case, the
command simply needs to connect to the serial console and forward that
connection to standard input and output as any normal terminal program
does. For example, to use the picocom terminal program on serial device
-``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows::
+``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:
+
+.. code-block:: bitbake
TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
@@ -307,7 +317,9 @@ For local
devices where the serial port device disappears when the device reboots,
an additional "serdevtry" wrapper script is provided. To use this
wrapper, simply prefix the terminal command with
-``${COREBASE}/scripts/contrib/serdevtry``::
+``${COREBASE}/scripts/contrib/serdevtry``:
+
+.. code-block:: bitbake
TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b 115200 /dev/ttyUSB0"
@@ -319,7 +331,9 @@ You can start the tests automatically or manually:
- *Automatically running tests:* To run the tests automatically after the
OpenEmbedded build system successfully creates an image, first set the
:term:`TESTIMAGE_AUTO` variable to "1" in your ``local.conf`` file in the
- :term:`Build Directory`::
+ :term:`Build Directory`:
+
+ .. code-block:: bitbake
TESTIMAGE_AUTO = "1"
@@ -330,7 +344,9 @@ You can start the tests automatically or manually:
- *Manually running tests:* To manually run the tests, first globally
inherit the :ref:`ref-classes-testimage` class by editing your
- ``local.conf`` file::
+ ``local.conf`` file:
+
+ .. code-block:: bitbake
IMAGE_CLASSES += "testimage"
@@ -377,15 +393,21 @@ handling.
Here are some things to keep in mind when running tests:
-- The default tests for the image are defined as::
+- The default tests for the image are defined as:
+
+ .. code-block:: bitbake
DEFAULT_TEST_SUITES:pn-image = "ping ssh df connman syslog xorg scp vnc date rpm dnf dmesg"
-- Add your own test to the list of the by using the following::
+- Add your own test to the list of the by using the following:
+
+ .. code-block:: bitbake
TEST_SUITES:append = " mytest"
-- Run a specific list of tests as follows::
+- Run a specific list of tests as follows:
+
+ .. code-block:: bitbake
TEST_SUITES = "test1 test2 test3"
@@ -401,7 +423,9 @@ test execution off to a scheduler. You can only export tests that are
defined in :term:`TEST_SUITES`.
If your image is already built, make sure the following are set in your
-``local.conf`` file::
+``local.conf`` file:
+
+.. code-block:: bitbake
IMAGE_CLASSES += "testexport"
TEST_TARGET_IP = "IP-address-for-the-test-target"
@@ -427,7 +451,9 @@ You can now run the tests outside of the build environment::
hardware before you can run the tests.
Here is a complete example that shows IP addresses and uses the
-``core-image-sato`` image::
+``core-image-sato`` image:
+
+.. code-block:: bitbake
IMAGE_CLASSES += "testexport"
TEST_TARGET_IP = "192.168.7.2"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 07/10] overview-manual: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (5 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 06/10] test-manual: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 08/10] security-manual: " Trevor Woerner
` (5 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 18 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
documentation/overview-manual/concepts.rst | 68 ++++++++++++++++------
1 file changed, 51 insertions(+), 17 deletions(-)
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index d4530e97fed9..c82f26961a3c 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -894,7 +894,9 @@ the analysis and package splitting process use several areas:
Packages for a recipe are listed in the :term:`PACKAGES` variable. The
:oe_git:`bitbake.conf </openembedded-core/tree/meta/conf/bitbake.conf>`
-configuration file defines the following default list of packages::
+configuration file defines the following default list of packages:
+
+.. code-block:: bitbake
PACKAGES = "${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}"
@@ -902,7 +904,9 @@ Each of these packages contains a default list of files defined with the
:term:`FILES` variable. For example, the package ``${PN}-dev`` represents files
useful to the development of applications depending on ``${PN}``. The default
list of files for ``${PN}-dev``, also defined in :oe_git:`bitbake.conf
-</openembedded-core/tree/meta/conf/bitbake.conf>`, is defined as follows::
+</openembedded-core/tree/meta/conf/bitbake.conf>`, is defined as follows:
+
+.. code-block:: bitbake
FILES:${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \
${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
@@ -940,12 +944,16 @@ package.
To add a custom package variant of the ``${PN}`` recipe named
``${PN}-extra`` (name is arbitrary), one can add it to the
-:term:`PACKAGE_BEFORE_PN` variable::
+:term:`PACKAGE_BEFORE_PN` variable:
+
+.. code-block:: bitbake
PACKAGE_BEFORE_PN += "${PN}-extra"
Alternatively, a custom package can be added by adding it to the
-:term:`PACKAGES` variable using the prepend operator (``=+``)::
+:term:`PACKAGES` variable using the prepend operator (``=+``):
+
+.. code-block:: bitbake
PACKAGES =+ "${PN}-extra"
@@ -1661,7 +1669,9 @@ to the task.
Like the :term:`WORKDIR` case, there can be situations where dependencies should be
ignored. For these situations, you can instruct the build process to
-ignore a dependency by using a line like the following::
+ignore a dependency by using a line like the following:
+
+.. code-block:: bitbake
PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
@@ -1671,7 +1681,9 @@ reference it.
Equally, there are cases where you need to add dependencies BitBake is
not able to find. You can accomplish this by using a line like the
-following::
+following:
+
+.. code-block:: bitbake
PACKAGE_ARCHS[vardeps] = "MACHINE"
@@ -1701,7 +1713,9 @@ and the dependent task hashes can be influenced. Within the BitBake
configuration file, you can give BitBake some extra information to help
it construct the basehash. The following statement effectively results
in a list of global variable dependency excludes (i.e. variables never
-included in any checksum)::
+included in any checksum):
+
+.. code-block:: bitbake
BB_BASEHASH_IGNORE_VARS ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \\
SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \\
@@ -1722,7 +1736,9 @@ desired. This file defines the two basic signature generators
"OEBasicHash". By default, a dummy "noop" signature handler is enabled
in BitBake. This means that behavior is unchanged from previous
versions. OE-Core uses the "OEBasicHash" signature handler by default
-through this setting in the ``bitbake.conf`` file::
+through this setting in the ``bitbake.conf`` file:
+
+.. code-block:: bitbake
BB_SIGNATURE_HANDLER ?= "OEBasicHash"
@@ -1771,7 +1787,9 @@ directory tree such as the sysroot.
The Yocto Project team has tried to keep the details of the
implementation hidden in the :ref:`ref-classes-sstate` class. From a user's perspective,
adding shared state wrapping to a task is as simple as this
-:ref:`ref-tasks-deploy` example taken from the :ref:`ref-classes-deploy` class::
+:ref:`ref-tasks-deploy` example taken from the :ref:`ref-classes-deploy` class:
+
+.. code-block:: bitbake
DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
SSTATETASKS += "do_deploy"
@@ -1814,7 +1832,9 @@ The following list explains the previous example:
instead, skipping the :ref:`ref-tasks-deploy` task.
- The following task definition is glue logic needed to make the
- previous settings effective::
+ previous settings effective:
+
+ .. code-block:: bitbake
python do_deploy_setscene () {
sstate_setscene(d)
@@ -1846,7 +1866,9 @@ The following list explains the previous example:
In cases where ``sstate-inputdirs`` and ``sstate-outputdirs`` would be
the same, you can use ``sstate-plaindirs``. For example, to preserve the
${:term:`PKGD`} and ${:term:`PKGDEST`} output from the :ref:`ref-tasks-package`
- task, use the following::
+ task, use the following:
+
+ .. code-block:: bitbake
do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
@@ -1862,21 +1884,27 @@ The following list explains the previous example:
multiple directories. For example, the following declares
:term:`PKGDESTWORK` and ``SHLIBWORK`` as shared state input directories,
which populates the shared state cache, and :term:`PKGDATA_DIR` and
- ``SHLIBSDIR`` as the corresponding shared state output directories::
+ ``SHLIBSDIR`` as the corresponding shared state output directories:
+
+ .. code-block:: bitbake
do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
- These methods also include the ability to take a lockfile when
manipulating shared state directory structures, for cases where file
- additions or removals are sensitive::
+ additions or removals are sensitive:
+
+ .. code-block:: bitbake
do_package[sstate-lockfile] = "${PACKAGELOCK}"
Behind the scenes, the shared state code works by looking in
:term:`SSTATE_DIR` and
:term:`SSTATE_MIRRORS` for
-shared state files. Here is an example::
+shared state files. Here is an example:
+
+.. code-block:: bitbake
SSTATE_MIRRORS ?= "\
file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \
@@ -2024,13 +2052,17 @@ variables:
- :term:`bitbake:BB_SIGNATURE_HANDLER`, which must be set to ``OEEquivHash``.
Therefore, the default configuration in Poky corresponds to the
-below settings::
+below settings:
+
+.. code-block:: bitbake
BB_HASHSERVE = "auto"
BB_SIGNATURE_HANDLER = "OEEquivHash"
Rather than starting a local server, another possibility is to rely
-on a Hash Equivalence server on a network, by setting::
+on a Hash Equivalence server on a network, by setting:
+
+.. code-block:: bitbake
BB_HASHSERVE = "<HOSTNAME>:<PORT>"
@@ -2189,7 +2221,9 @@ accomplished using fakeroot.
under fakeroot. Otherwise, the task cannot run root-only operations,
and cannot see the fake file ownership and permissions set by the
other task. You need to also add a dependency on
- ``virtual/fakeroot-native:do_populate_sysroot``, giving the following::
+ ``virtual/fakeroot-native:do_populate_sysroot``, giving the following:
+
+ .. code-block:: bitbake
fakeroot do_mytask () {
...
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 08/10] security-manual: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (6 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 07/10] overview-manual: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 09/10] sdk-manual: " Trevor Woerner
` (4 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 16 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
.../security-manual/read-only-rootfs.rst | 8 +++--
.../security-manual/securing-images.rst | 8 +++--
.../security-manual/sstate-signing.rst | 16 +++++++---
.../security-manual/vulnerabilities.rst | 32 ++++++++++++++-----
4 files changed, 48 insertions(+), 16 deletions(-)
diff --git a/documentation/security-manual/read-only-rootfs.rst b/documentation/security-manual/read-only-rootfs.rst
index 251178ed5458..55eb853dc239 100644
--- a/documentation/security-manual/read-only-rootfs.rst
+++ b/documentation/security-manual/read-only-rootfs.rst
@@ -23,13 +23,17 @@ Creating the Root Filesystem
To create the read-only root filesystem, simply add the
"read-only-rootfs" feature to your image, normally in one of two ways.
The first way is to add the "read-only-rootfs" image feature in the
-image's recipe file via the :term:`IMAGE_FEATURES` variable::
+image's recipe file via the :term:`IMAGE_FEATURES` variable:
+
+.. code-block:: bitbake
IMAGE_FEATURES += "read-only-rootfs"
As an alternative, you can add the same feature
from within your :term:`Build Directory`'s ``local.conf`` file with the
-associated :term:`EXTRA_IMAGE_FEATURES` variable, as in::
+associated :term:`EXTRA_IMAGE_FEATURES` variable, as in:
+
+.. code-block:: bitbake
EXTRA_IMAGE_FEATURES = "read-only-rootfs"
diff --git a/documentation/security-manual/securing-images.rst b/documentation/security-manual/securing-images.rst
index 13ab63ddd8be..3c01c1f643bd 100644
--- a/documentation/security-manual/securing-images.rst
+++ b/documentation/security-manual/securing-images.rst
@@ -82,7 +82,9 @@ your build output more secure. The security flags are in the
Use the following line in your ``local.conf`` file or in your custom
distribution configuration file to enable the security compiler and
-linker flags for your build::
+linker flags for your build:
+
+.. code-block:: bitbake
require conf/distro/include/security_flags.inc
@@ -96,7 +98,9 @@ system to make your images more secure:
and allow the use of empty passwords or root logins. This is typically
done by adding the values "allow-empty-password", "allow-root-login", and
"empty-root-password" to your build's image features, commonly with the
- addition of the line::
+ addition of the line:
+
+ .. code-block:: bitbake
EXTRA_IMAGE_FEATURES = "allow-empty-password empty-root-password allow-root-login"
diff --git a/documentation/security-manual/sstate-signing.rst b/documentation/security-manual/sstate-signing.rst
index 74a5d6bf07da..565f51e843ab 100644
--- a/documentation/security-manual/sstate-signing.rst
+++ b/documentation/security-manual/sstate-signing.rst
@@ -86,7 +86,9 @@ they are generated. The generation of new artifacts is done once a task has
finished being executed.
For the following sections let's assume that the build system has the shared
-state directory location (:term:`SSTATE_DIR`) defined as follows::
+state directory location (:term:`SSTATE_DIR`) defined as follows:
+
+.. code-block:: bitbake
SSTATE_DIR = "${TOPDIR}/sstate-cache"
@@ -120,7 +122,9 @@ Enabling Shared State Signing
-----------------------------
Create a new :term:`configuration file` on your host **in a safe location** and
-add the two following statements::
+add the two following statements:
+
+.. code-block:: bitbake
SSTATE_VERIFY_SIG = "1"
SSTATE_SIG_KEY = "4049A47E3AAA99D0250966DC5B97632FA7F4E942"
@@ -196,7 +200,9 @@ you can verify them with the public key counterpart of the private key.
shared between multiple hosts.
From a :term:`configuration file` such as the :ref:`site configuration file
-<structure-build-conf-site.conf>`, include the following statements::
+<structure-build-conf-site.conf>`, include the following statements:
+
+.. code-block:: bitbake
SSTATE_VERIFY_SIG = "1"
SSTATE_VALID_SIGS = "5B97632FA7F4E942"
@@ -255,7 +261,9 @@ Let's verify that signature verification works:
.. note::
To make sure shared state verification is working, you can set a "fake"
- public key identifier in :term:`SSTATE_VALID_SIGS`::
+ public key identifier in :term:`SSTATE_VALID_SIGS`:
+
+ .. code-block:: bitbake
SSTATE_VALID_SIGS = "CAFECAFECAFECAFE"
diff --git a/documentation/security-manual/vulnerabilities.rst b/documentation/security-manual/vulnerabilities.rst
index 38fbd2c7e358..e3fc6fe768b8 100644
--- a/documentation/security-manual/vulnerabilities.rst
+++ b/documentation/security-manual/vulnerabilities.rst
@@ -35,7 +35,9 @@ Directory`:
$ bitbake-config-build enable-fragment core/yocto/sbom-cve-check
-Or add the following statement to a :term:`configuration file`::
+Or add the following statement to a :term:`configuration file`:
+
+.. code-block:: bitbake
OE_FRAGMENTS += "core/yocto/sbom-cve-check"
@@ -44,7 +46,9 @@ recommended settings to use it.
The CVE database contains some old incomplete entries which have been deemed not
to impact :term:`OpenEmbedded-Core (OE-Core)`. These CVE entries can be excluded
-from the check by adding the following statement::
+from the check by adding the following statement:
+
+.. code-block:: bitbake
include conf/distro/include/cve-extra-exclusions.inc
@@ -165,7 +169,9 @@ in the recipe name to CVE product mapping. These mapping issues can be fixed by
the :term:`CVE_PRODUCT` variable inside the recipe. This defines the name of the software component in the
upstream `NIST CVE database <https://nvd.nist.gov/>`__.
-The variable supports using vendor and product names like this::
+The variable supports using vendor and product names like this:
+
+.. code-block:: bitbake
CVE_PRODUCT = "flex_project:flex westes:flex"
@@ -200,7 +206,9 @@ version does or likely might introduce incompatibilities, extracting and
backporting patches is preferred.
Here is an example of fixing CVE security issues with patch files,
-an example from the :oe_layerindex:`ffmpeg recipe for dunfell </layerindex/recipe/122174>`::
+an example from the :oe_layerindex:`ffmpeg recipe for dunfell </layerindex/recipe/122174>`:
+
+.. code-block:: bitbake
SRC_URI = "https://www.ffmpeg.org/releases/${BP}.tar.xz \
file://mips64_cpu_detection.patch \
@@ -283,7 +291,9 @@ status to ``Patched`` in the generated reports.
If analysis shows that the CVE issue does not impact the recipe due to configuration, platform,
version or other reasons, the CVE can be marked as ``Ignored`` by using
the :term:`CVE_STATUS` variable flag with appropriate reason which is mapped to ``Ignored``.
-The entry should have the format like::
+The entry should have the format like:
+
+.. code-block:: bitbake
CVE_STATUS[CVE-2016-10642] = "cpe-incorrect: This is specific to the npm package that installs cmake, so isn't relevant to OpenEmbedded"
@@ -364,7 +374,9 @@ Example:
$ cd openembedded-core/meta/recipes-kernel/linux/
$ ./generate-cve-exclusions.py ~/cvelistV5 6.12.27 > ~/meta-custom/recipes-kernel/linux/cve-exclusion_6.12.inc
-Don't forget to update your kernel recipe with::
+Don't forget to update your kernel recipe with:
+
+.. code-block:: bitbake
include cve-exclusion_6.12.inc
@@ -396,7 +408,9 @@ build a binary. Therefore, it needs to be configured in the kernel to extract
the kernel compiled files.
If you are using the ``linux-yocto`` recipe, enable it by adding the following
-in a :term:`configuration file` or in a ``.bbappend``::
+in a :term:`configuration file` or in a ``.bbappend``:
+
+.. code-block:: bitbake
KERNEL_EXTRA_FEATURES:append = " features/debug/debug-kernel.scc"
@@ -413,7 +427,9 @@ The sources for the kernel are stored under
``tmp/pkgdata/<MACHINE>/debugsources/linux-yocto-debugsources.json.zstd``. In
order to include the information into the :term:`SPDX` file to filter out
source files that are not used to compile the kernel, add the following in a
-:term:`configuration file`::
+:term:`configuration file`:
+
+.. code-block:: bitbake
SPDX_INCLUDE_COMPILED_SOURCES:pn-linux-yocto = "1"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 09/10] sdk-manual: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (7 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 08/10] security-manual: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 1:34 ` [PATCH 10/10] docs-wide: " Trevor Woerner
` (3 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 9 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
.../sdk-manual/appendix-customizing-standard.rst | 4 +++-
.../sdk-manual/appendix-customizing.rst | 16 ++++++++--------
2 files changed, 11 insertions(+), 9 deletions(-)
diff --git a/documentation/sdk-manual/appendix-customizing-standard.rst b/documentation/sdk-manual/appendix-customizing-standard.rst
index 90b73dc20d7a..e0437270d1dd 100644
--- a/documentation/sdk-manual/appendix-customizing-standard.rst
+++ b/documentation/sdk-manual/appendix-customizing-standard.rst
@@ -27,7 +27,9 @@ Adding API Documentation to the Standard SDK
You can include API documentation as well as any other documentation
provided by recipes with the standard SDK by adding "api-documentation"
-to the :term:`DISTRO_FEATURES` variable::
+to the :term:`DISTRO_FEATURES` variable:
+
+.. code-block:: bitbake
DISTRO_FEATURES:append = " api-documentation"
diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst
index 467c5c10c32c..497db2fb9f50 100644
--- a/documentation/sdk-manual/appendix-customizing.rst
+++ b/documentation/sdk-manual/appendix-customizing.rst
@@ -149,7 +149,7 @@ The
class defines the default value of the :term:`SDK_TITLE` variable as
follows:
-.. code-block:: none
+.. code-block:: bitbake
SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
@@ -163,7 +163,7 @@ does the default "poky" distribution. If so, you could update the
``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
form:
-.. code-block:: none
+.. code-block:: bitbake
SDK_TITLE = "your_title"
@@ -220,7 +220,7 @@ within the
:ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
class as follows:
-.. code-block:: none
+.. code-block:: bitbake
SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
@@ -239,7 +239,7 @@ does the default "poky" distribution. If so, you could update the
``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following
form:
-.. code-block:: none
+.. code-block:: bitbake
SDKEXTPATH = "some_path_for_your_installed_sdk"
@@ -275,7 +275,7 @@ source, you need to do a number of things:
to find the configuration. The variable you need to set is
:term:`SSTATE_MIRRORS`:
- .. code-block:: none
+ .. code-block:: bitbake
SSTATE_MIRRORS = "file://.* https://example.com/some_path/sstate-cache/PATH"
@@ -290,7 +290,7 @@ source, you need to do a number of things:
configuration file. You can then pass the variable to the SDK by
adding the following:
- .. code-block:: none
+ .. code-block:: bitbake
ESDK_LOCALCONF_ALLOW = "SSTATE_MIRRORS"
@@ -315,7 +315,7 @@ more in size. If the size of this file causes a problem, you can build
an SDK that has just enough in it to install and provide access to the
``devtool command`` by setting the following in your configuration:
-.. code-block:: none
+.. code-block:: bitbake
SDK_EXT_TYPE = "minimal"
@@ -339,7 +339,7 @@ results.
To facilitate this wider range of information, you would need to set the
following:
-.. code-block:: none
+.. code-block:: bitbake
SDK_INCLUDE_PKGDATA = "1"
^ permalink raw reply related [flat|nested] 33+ messages in thread
* [PATCH 10/10] docs-wide: use the bitbake code-block language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (8 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 09/10] sdk-manual: " Trevor Woerner
@ 2026-08-26 1:34 ` Trevor Woerner
2026-08-26 11:56 ` [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Paul Barker
` (2 subsequent siblings)
12 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 1:34 UTC (permalink / raw)
To: docs
BitBake snippets here render as unhighlighted text. A reStructuredText
literal block carries no language, and Sphinx falls back to a default
that cannot recognise BitBake metadata.
Pygments 2.21 added a BitBake lexer, so tag these 19 blocks
explicitly. Variable names, assignment operators, override chains,
expansions and shell or Python task bodies are then highlighted.
Blocks that only look like BitBake are left alone, as are blocks
already tagged "none" where the content is deliberately unhighlighted.
This covers the remaining manuals, each with only a handful of snippets.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
documentation/brief-yoctoprojectqs/index.rst | 4 ++-
documentation/bsp-manual/bsp.rst | 28 ++++++++++++++-----
.../contributor-guide/recipe-style-guide.rst | 24 ++++++++++++----
documentation/profile-manual/intro.rst | 16 ++++++++---
4 files changed, 54 insertions(+), 18 deletions(-)
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index 4adec9714f2f..2dccff16c995 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -410,7 +410,9 @@ layer>`:
`Synaptics` license. See the :yocto_git:`ipcompliance.md
</meta-raspberrypi/tree/docs/ipcompliance.md>` document for more information.
Add the ``synaptics-killswitch`` value to the :term:`LICENSE_FLAGS_ACCEPTED`
- variable, in the ``conf/local.conf`` file of your build directory::
+ variable, in the ``conf/local.conf`` file of your build directory:
+
+ .. code-block:: bitbake
LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch"
diff --git a/documentation/bsp-manual/bsp.rst b/documentation/bsp-manual/bsp.rst
index 168d64e6ed5a..030464b74283 100644
--- a/documentation/bsp-manual/bsp.rst
+++ b/documentation/bsp-manual/bsp.rst
@@ -84,7 +84,9 @@ established after you run the OpenEmbedded build environment setup
script (i.e. :ref:`structure-core-script`).
Adding the root directory allows the :term:`OpenEmbedded Build System`
to recognize the BSP
-layer and from it build an image. Here is an example::
+layer and from it build an image. Here is an example:
+
+.. code-block:: bitbake
BBLAYERS ?= " \
/usr/local/src/yocto/meta \
@@ -112,7 +114,9 @@ are known as ":term:`container layers <Container Layer>`". An example of
this type of layer is OpenEmbedded's :oe_git:`meta-openembedded </meta-openembedded>`
layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers.
In cases like this, you need to include the names of the actual layers
-you want to work with, such as::
+you want to work with, such as:
+
+.. code-block:: bitbake
BBLAYERS ?= " \
/usr/local/src/yocto/meta \
@@ -603,7 +607,9 @@ For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``,
To use an include file, you simply include them in the machine
configuration file. For example, the Raspberry Pi BSP
-``raspberrypi3.conf`` contains the following statement::
+``raspberrypi3.conf`` contains the following statement:
+
+.. code-block:: bitbake
include conf/machine/include/rpi-base.inc
@@ -674,7 +680,9 @@ Suppose you are using the ``linux-yocto_6.12.bb`` recipe to build the
kernel. In other words, you have selected the kernel in your
``"bsp_root_name".conf`` file by adding
:term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION`
-statements as follows::
+statements as follows:
+
+.. code-block:: bitbake
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
PREFERRED_VERSION_linux-yocto ?= "6.12%"
@@ -1027,7 +1035,9 @@ BSP-specific configuration file named ``interfaces`` to the
also supports several other machines:
#. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the
- following::
+ following:
+
+ .. code-block:: bitbake
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
@@ -1383,7 +1393,9 @@ BSP Kernel Recipe Example
-------------------------
The kernel recipe used to build the kernel image for the BeagleBone
-device was established in the machine configuration::
+device was established in the machine configuration:
+
+.. code-block:: bitbake
PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
PREFERRED_VERSION_linux-yocto ?= "6.18%"
@@ -1394,7 +1406,9 @@ metadata used to build the kernel. In this case, a kernel append file
kernel recipe (i.e. ``linux-yocto_6.18.bb``), which is located in
:oe_git:`/openembedded-core/tree/meta/recipes-kernel/linux`.
-The contents of the append file are::
+The contents of the append file are:
+
+.. code-block:: bitbake
COMPATIBLE_MACHINE:genericarm64 = "genericarm64"
COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto"
diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst
index 84c6bb14e8b0..7cd3385787ee 100644
--- a/documentation/contributor-guide/recipe-style-guide.rst
+++ b/documentation/contributor-guide/recipe-style-guide.rst
@@ -48,7 +48,9 @@ Debian policy closely.
When a recipe references a git revision that does not correspond to a released
version of software (e.g. is not a tagged version), the :term:`PV` variable
should include the sign ``+``, so :term:`bitbake` automatically includes package
-version information during the packaging phase::
+version information during the packaging phase:
+
+.. code-block:: bitbake
PV = "<version>+git"
@@ -95,13 +97,17 @@ Variable Formatting
- When splitting a long variable over multiple lines, all continuation lines
should be indented (with spaces) to align with the start of the quote on the
- first line::
+ first line:
+
+ .. code-block:: bitbake
FOO = "this line is \
long \
"
- Instead of::
+ Instead of:
+
+ .. code-block:: bitbake
FOO = "this line is \
long \
@@ -190,7 +196,9 @@ used tasks this would be:
Custom tasks should be sorted similarly.
-Package specific variables are typically grouped together, e.g.::
+Package specific variables are typically grouped together, e.g.:
+
+.. code-block:: bitbake
RDEPENDS:${PN} = "foo"
RDEPENDS:${PN}-libs = "bar"
@@ -211,7 +219,9 @@ Recipes need to define both the :term:`LICENSE` and
include ``COPYING``, :term:`LICENSE`, and ``README`` files. You could
also find the information near the top of a source file. For example,
given a piece of software licensed under the GNU General Public
- License version 2, you would set :term:`LICENSE` as follows::
+ License version 2, you would set :term:`LICENSE` as follows:
+
+ .. code-block:: bitbake
LICENSE = "GPL-2.0-only"
@@ -255,7 +265,9 @@ Recipes need to define both the :term:`LICENSE` and
See the ":ref:`dev-manual/new-recipe:fetching code`" section for
additional information.
- Here is an example that assumes the software has a ``COPYING`` file::
+ Here is an example that assumes the software has a ``COPYING`` file:
+
+ .. code-block:: bitbake
LIC_FILES_CHKSUM = "file://COPYING;md5=xxx"
diff --git a/documentation/profile-manual/intro.rst b/documentation/profile-manual/intro.rst
index 31791255246e..24bbc952c9bd 100644
--- a/documentation/profile-manual/intro.rst
+++ b/documentation/profile-manual/intro.rst
@@ -41,7 +41,9 @@ an ``sdk`` image, perhaps one of::
$ bitbake core-image-rt-sdk
Alternatively, you can add ``tools-profile`` to the :term:`EXTRA_IMAGE_FEATURES` line in
-your ``local.conf`` file::
+your ``local.conf`` file:
+
+.. code-block:: bitbake
EXTRA_IMAGE_FEATURES:append = " tools-profile"
@@ -57,7 +59,9 @@ the tracing and profiling tools will be included in non-sdk images as well e.g.:
You can prevent that by setting the
:term:`INHIBIT_PACKAGE_STRIP`
- variable to "1" in your ``local.conf`` when you build the image::
+ variable to "1" in your ``local.conf`` when you build the image:
+
+ .. code-block:: bitbake
INHIBIT_PACKAGE_STRIP = "1"
@@ -67,11 +71,15 @@ If you've already built a stripped image, you can generate debug
packages (xxx-dbg) which you can manually install as needed.
To generate debug info for packages, you can add ``dbg-pkgs`` to
-:term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example::
+:term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example:
+
+.. code-block:: bitbake
EXTRA_IMAGE_FEATURES:append = " dbg-pkgs"
Additionally, in order to generate the right type of debug info, we also need to
-set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file::
+set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file:
+
+.. code-block:: bitbake
PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
^ permalink raw reply related [flat|nested] 33+ messages in thread
* Re: [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (9 preceding siblings ...)
2026-08-26 1:34 ` [PATCH 10/10] docs-wide: " Trevor Woerner
@ 2026-08-26 11:56 ` Paul Barker
2026-08-26 13:29 ` Trevor Woerner
2026-08-26 12:10 ` [docs] " Quentin Schulz
2026-08-27 8:38 ` Antonin Godard
12 siblings, 1 reply; 33+ messages in thread
From: Paul Barker @ 2026-08-26 11:56 UTC (permalink / raw)
To: Trevor Woerner, docs
Hi Trevor,
On Tue, 2026-08-25 at 21:34 -0400, Trevor Woerner wrote:
> Please do not apply this yet
It's easy to miss this when looking at the individual patches, you
should use `RFC` in the subject :)
Best regards,
--
Paul Barker
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (10 preceding siblings ...)
2026-08-26 11:56 ` [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Paul Barker
@ 2026-08-26 12:10 ` Quentin Schulz
2026-08-26 13:09 ` Antonin Godard
2026-08-27 8:38 ` Antonin Godard
12 siblings, 1 reply; 33+ messages in thread
From: Quentin Schulz @ 2026-08-26 12:10 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:
> Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say
> what they are instead of rendering as plain literal blocks. This tags
> the ones in yocto-docs.
>
> One patch per manual, which is also roughly one reviewable unit per
> patch. No prose changes, no reflowing, no reindenting - every hunk turns
> a literal-block introducer into a code-block directive and nothing else.
>
> Which blocks were converted was decided by reading, not by pattern
"by reading" following a paragraph definitely not written by you and
with all commits being AI-Generated is quite the stretch ;)
[...]
> Depends on
> ----------
>
> "docs: state the language of nine literal blocks explicitly", sent
Link to the ML please to make maintainers and reviewers job easier.
[...]
I think this is going the wrong direction. We should actually make
explicit the language of every :: that is NOT to be understood as
BitBake code and then make the default highlight language be BitBake.
The direct benefit is the ability to still backport whatever needs to be
backported without having to care about the highlight language being
explicitly bitbake (which won't be available in every branch but
master). The other benefit is that by default every new code snippet
will be understood as BitBake syntax, which is very likely what most of
the snippet should be, and if they aren't, then their language should be
made explicit. I'm thinking this could also maybe reduce the diff as I'm
hoping we have more BitBake syntax than shell/python/whatever else so
maybe easier to review as well. I believe
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-highlight_language
should be the way to do change the default highlight language (according
to
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
and
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block)?
Cheers,
Quentin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 12:10 ` [docs] " Quentin Schulz
@ 2026-08-26 13:09 ` Antonin Godard
2026-08-26 13:25 ` Trevor Woerner
2026-08-26 14:34 ` Quentin Schulz
0 siblings, 2 replies; 33+ messages in thread
From: Antonin Godard @ 2026-08-26 13:09 UTC (permalink / raw)
To: quentin.schulz, twoerner, docs
Hi,
On Wed Aug 26, 2026 at 2:10 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Trevor,
>
> On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:
>> Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say
>> what they are instead of rendering as plain literal blocks. This tags
>> the ones in yocto-docs.
>>
>> One patch per manual, which is also roughly one reviewable unit per
>> patch. No prose changes, no reflowing, no reindenting - every hunk turns
>> a literal-block introducer into a code-block directive and nothing else.
>>
>> Which blocks were converted was decided by reading, not by pattern
>
> "by reading" following a paragraph definitely not written by you and
> with all commits being AI-Generated is quite the stretch ;)
>
> [...]
>
>> Depends on
>> ----------
>>
>> "docs: state the language of nine literal blocks explicitly", sent
>
> Link to the ML please to make maintainers and reviewers job easier.
>
> [...]
>
> I think this is going the wrong direction. We should actually make
> explicit the language of every :: that is NOT to be understood as
> BitBake code and then make the default highlight language be BitBake.
But then this might get forgotten? How about having the default highlighted as
"none", and make _everything_ use explicit code-blocks?
Sure, this is more efforts and review time, but also this is how other markup
languages work - like markdown, where by default (when using ```...```) no
syntax highlighting is done.
This is maybe a more conservative approach but at least it doesn't leave room
for code blocks mistakenly highlighted with the bitbake lexer.
Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 13:09 ` Antonin Godard
@ 2026-08-26 13:25 ` Trevor Woerner
2026-08-26 14:45 ` Quentin Schulz
2026-08-26 14:34 ` Quentin Schulz
1 sibling, 1 reply; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 13:25 UTC (permalink / raw)
To: Antonin Godard; +Cc: quentin.schulz, docs
On Wed 2026-08-26 @ 03:09:23 PM, Antonin Godard wrote:
> Hi,
>
> On Wed Aug 26, 2026 at 2:10 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> > Hi Trevor,
> >
> > On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:
> >> Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say
> >> what they are instead of rendering as plain literal blocks. This tags
> >> the ones in yocto-docs.
> >>
> >> One patch per manual, which is also roughly one reviewable unit per
> >> patch. No prose changes, no reflowing, no reindenting - every hunk turns
> >> a literal-block introducer into a code-block directive and nothing else.
> >>
> >> Which blocks were converted was decided by reading, not by pattern
> >
> > "by reading" following a paragraph definitely not written by you and
> > with all commits being AI-Generated is quite the stretch ;)
When I asked AI to add explicit code-blocks with explicit language tags
I emphasized it should read the entire block before deciding. At work I
am the head of a massive project to convert some of our documentation
from wiki to reST and was caught a couple times by this.
Bitbake syntax has a tendency to sometimes look like bash, and sometimes
look like python, so I wanted to make sure AI was being careful about
the languages it was guessing.
In fact I pushed back on some of the choices when it selected python
instead of bitbake, but then it pushed back on me and said: "yes it's a
bitbake example, but this code snippet is entirely python" and in some
rare cases it was actually correct.
So this "by reading" statement was probably AI's way of saying: "i was
careful about the choices i made", rather than implying that "Trevor
read each one and decided".
> >
> > [...]
> >
> >> Depends on
> >> ----------
> >>
> >> "docs: state the language of nine literal blocks explicitly", sent
> >
> > Link to the ML please to make maintainers and reviewers job easier.
> >
> > [...]
> >
> > I think this is going the wrong direction. We should actually make
> > explicit the language of every :: that is NOT to be understood as
> > BitBake code and then make the default highlight language be BitBake.
>
> But then this might get forgotten? How about having the default highlighted as
> "none", and make _everything_ use explicit code-blocks?
>
> Sure, this is more efforts and review time, but also this is how other markup
> languages work - like markdown, where by default (when using ```...```) no
> syntax highlighting is done.
>
> This is maybe a more conservative approach but at least it doesn't leave room
> for code blocks mistakenly highlighted with the bitbake lexer.
Yes, I agree too. Personally I'm not fond of "hidden defaults".
By default a non-specified block will cause pygments to guess. So if I'm
looking at a lot of reST and seeing no tags, I'm going to assume the
authors have left pygments to guess. I would have to go looking in other
places to see if there's a default in place for non-specified code-block
tags, which I'm probably not going to think of doing, which will
sometimes probably cause more confusion before it becomes clear.
Maybe it's just me, but I prefer to see every example block using an
explicit code-block tag and specifying a language. That way the author's
intentions are unambiguous, and we have an expected output.
That's what I've enforced for our reST at work, and I've also
differentiated between "bash" (for actual shell programs) versus
"console" (for interactive work at a shell prompt, a shell most likely
to be bash).
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 11:56 ` [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Paul Barker
@ 2026-08-26 13:29 ` Trevor Woerner
0 siblings, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 13:29 UTC (permalink / raw)
To: Paul Barker; +Cc: docs
On Wed 2026-08-26 @ 12:56:32 PM, Paul Barker wrote:
> Hi Trevor,
>
> On Tue, 2026-08-25 at 21:34 -0400, Trevor Woerner wrote:
> > Please do not apply this yet
>
> It's easy to miss this when looking at the individual patches, you
> should use `RFC` in the subject :)
True. But Antonin had told me he could test with an updated environment,
and if this did "accidentally" land too early, the worst outcome would
be a lot of warning messages about an unknown lexer name "bitbake". I
don't believe this would cause a build failure, just warnings until the
environment would be updated, which I was told in another email would be
coming.
So _ideally_ don't apply yet, but no biggie if you do. I would have
RFC'ed it otherwise.
> Best regards,
>
> --
> Paul Barker
>
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 13:09 ` Antonin Godard
2026-08-26 13:25 ` Trevor Woerner
@ 2026-08-26 14:34 ` Quentin Schulz
2026-08-26 15:10 ` Antonin Godard
1 sibling, 1 reply; 33+ messages in thread
From: Quentin Schulz @ 2026-08-26 14:34 UTC (permalink / raw)
To: Antonin Godard, twoerner, docs
On 8/26/26 3:09 PM, Antonin Godard wrote:
> Hi,
>
> On Wed Aug 26, 2026 at 2:10 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>> Hi Trevor,
>>
>> On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:
>>> Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say
>>> what they are instead of rendering as plain literal blocks. This tags
>>> the ones in yocto-docs.
>>>
>>> One patch per manual, which is also roughly one reviewable unit per
>>> patch. No prose changes, no reflowing, no reindenting - every hunk turns
>>> a literal-block introducer into a code-block directive and nothing else.
>>>
>>> Which blocks were converted was decided by reading, not by pattern
>>
>> "by reading" following a paragraph definitely not written by you and
>> with all commits being AI-Generated is quite the stretch ;)
>>
>> [...]
>>
>>> Depends on
>>> ----------
>>>
>>> "docs: state the language of nine literal blocks explicitly", sent
>>
>> Link to the ML please to make maintainers and reviewers job easier.
>>
>> [...]
>>
>> I think this is going the wrong direction. We should actually make
>> explicit the language of every :: that is NOT to be understood as
>> BitBake code and then make the default highlight language be BitBake.
>
> But then this might get forgotten? How about having the default highlighted as
> "none", and make _everything_ use explicit code-blocks?
>
"""
The direct benefit is the ability to still backport whatever needs to be
backported without having to care about the highlight language being
explicitly bitbake (which won't be available in every branch but master).
"""
*exactly* the sentence after what you quoted.
It's bound to happen someone will want to backport a patch with
.. code-block:: bitbake
Either we'll forget during review and it'll break the docs build, or we
need to adapt each and every patch/commit for stable branches.
I'm usually the one trying to add friction to processes, but I don't
think the above is a good idea.
I'm trying to avoid having code-blocks set to use the bitbake lexer so
we can easily backport without having to care.
> Sure, this is more efforts and review time, but also this is how other markup
> languages work - like markdown, where by default (when using ```...```) no
> syntax highlighting is done.
> > This is maybe a more conservative approach but at least it doesn't
leave room
> for code blocks mistakenly highlighted with the bitbake lexer.
>
It's currently mistakenly highlighted in Python if it looks like Python
to pygments (the default).
It's the Yocto/Bitbake documentation, I'm assuming the overwhelming
majority of code-blocks should be BitBake code.
If you really want to require explicit lexers, then set
highlight_language = "please_specify_the_highlight_language_for_this_block"
in conf.py and then everybody will have to set one.
Again, if you explicitly use the bitbake lexer in master, you won't be
able to backport those patches to stable branches easily. Or you'll need
your users to update their build environments to use the new release of
pygments. Or maybe you want to write a custom bitbake lexer for stable
branches that is an alias to the "default" (the default value of
highlight_language) lexer, but only have it if the version of pygments
doesn't contain a bitbake lexer already.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 13:25 ` Trevor Woerner
@ 2026-08-26 14:45 ` Quentin Schulz
2026-08-26 19:56 ` Trevor Woerner
0 siblings, 1 reply; 33+ messages in thread
From: Quentin Schulz @ 2026-08-26 14:45 UTC (permalink / raw)
To: twoerner, Antonin Godard; +Cc: docs
On 8/26/26 3:25 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> On Wed 2026-08-26 @ 03:09:23 PM, Antonin Godard wrote:
>> Hi,
>>
>> On Wed Aug 26, 2026 at 2:10 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>> Hi Trevor,
>>>
>>> On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:[...]>>>
>>> [...]
>>>
>>>> Depends on
>>>> ----------
>>>>
>>>> "docs: state the language of nine literal blocks explicitly", sent
>>>
>>> Link to the ML please to make maintainers and reviewers job easier.
>>>
>>> [...]
>>>
>>> I think this is going the wrong direction. We should actually make
>>> explicit the language of every :: that is NOT to be understood as
>>> BitBake code and then make the default highlight language be BitBake.
>>
>> But then this might get forgotten? How about having the default highlighted as
>> "none", and make _everything_ use explicit code-blocks?
>>
>> Sure, this is more efforts and review time, but also this is how other markup
>> languages work - like markdown, where by default (when using ```...```) no
>> syntax highlighting is done.
>>
>> This is maybe a more conservative approach but at least it doesn't leave room
>> for code blocks mistakenly highlighted with the bitbake lexer.
>
> Yes, I agree too. Personally I'm not fond of "hidden defaults".
>
There's already one.
> By default a non-specified block will cause pygments to guess. So if I'm
Sphinx explicitly states that Python will be tried and if there are
highlights warnings, none will be used. c.f.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples
> looking at a lot of reST and seeing no tags, I'm going to assume the
> authors have left pygments to guess. I would have to go looking in other
> places to see if there's a default in place for non-specified code-block
> tags, which I'm probably not going to think of doing, which will
> sometimes probably cause more confusion before it becomes clear.
>
This is the Yocto/BitBake docs, we're documenting that project, which
uses BitBake syntax. Would you want to write
.. code-block:: rust
for every code-block in the Rust documentation?
> Maybe it's just me, but I prefer to see every example block using an
> explicit code-block tag and specifying a language. That way the author's
> intentions are unambiguous, and we have an expected output.
>
You won't be able to backport patches with
.. code-block:: bitbake
which is what I would like to avoid. But I'm not the one sending patches
to the stable branches nor the maintainer(s) handling stable, so maybe I
shouldn't care.
> That's what I've enforced for our reST at work, and I've also
> differentiated between "bash" (for actual shell programs) versus
> "console" (for interactive work at a shell prompt, a shell most likely
> to be bash).
>
We differentiate console and shell in these docs here too. If you're
seeing one that is using the wrong lexer, please fix it.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 14:34 ` Quentin Schulz
@ 2026-08-26 15:10 ` Antonin Godard
2026-08-26 15:43 ` Quentin Schulz
0 siblings, 1 reply; 33+ messages in thread
From: Antonin Godard @ 2026-08-26 15:10 UTC (permalink / raw)
To: quentin.schulz, twoerner, docs
Hi,
On Wed Aug 26, 2026 at 4:34 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>
>
> On 8/26/26 3:09 PM, Antonin Godard wrote:
[...]
>>> I think this is going the wrong direction. We should actually make
>>> explicit the language of every :: that is NOT to be understood as
>>> BitBake code and then make the default highlight language be BitBake.
>>
>> But then this might get forgotten? How about having the default highlighted as
>> "none", and make _everything_ use explicit code-blocks?
>>
>
> """
> The direct benefit is the ability to still backport whatever needs to be
> backported without having to care about the highlight language being
> explicitly bitbake (which won't be available in every branch but master).
> """
>
> *exactly* the sentence after what you quoted.
>
> It's bound to happen someone will want to backport a patch with
>
> .. code-block:: bitbake
>
> Either we'll forget during review and it'll break the docs build, or we
> need to adapt each and every patch/commit for stable branches.
>
> I'm usually the one trying to add friction to processes, but I don't
> think the above is a good idea.
>
> I'm trying to avoid having code-blocks set to use the bitbake lexer so
> we can easily backport without having to care.
Our current active releases where we backport patches are Wrynose and Scarthgap.
Both use the same buildtools tarball on the Autobuilder, and contain the same
version of pygments, so backporting patches that use the bitbake lexer won't be
an issue (from an Autobuilder perspective).
>> Sure, this is more efforts and review time, but also this is how other markup
>> languages work - like markdown, where by default (when using ```...```) no
>> syntax highlighting is done.
>> > This is maybe a more conservative approach but at least it doesn't
> leave room
>> for code blocks mistakenly highlighted with the bitbake lexer.
>>
>
> It's currently mistakenly highlighted in Python if it looks like Python
> to pygments (the default).
>
> It's the Yocto/Bitbake documentation, I'm assuming the overwhelming
> majority of code-blocks should be BitBake code.
>
> If you really want to require explicit lexers, then set
>
> highlight_language = "please_specify_the_highlight_language_for_this_block"
>
> in conf.py and then everybody will have to set one.
>
> Again, if you explicitly use the bitbake lexer in master, you won't be
> able to backport those patches to stable branches easily. Or you'll need
> your users to update their build environments to use the new release of
> pygments.
We can add a requirement on pygments:
diff --git a/documentation/tools/host_packages_scripts/pip3_docs.sh b/documentation/tools/host_packages_scripts/pip3_docs.sh
index 852845783..d7a983731 100644
--- a/documentation/tools/host_packages_scripts/pip3_docs.sh
+++ b/documentation/tools/host_packages_scripts/pip3_docs.sh
@@ -1,3 +1,3 @@
python3 -m venv --clear ./yocto-docs-venv
. ./yocto-docs-venv/bin/activate
-python3 -m pip install sphinx sphinx_rtd_theme pyyaml sphinx-copybutton 'sphinxcontrib-svg2pdfconverter>=2.0.0'
+python3 -m pip install sphinx sphinx_rtd_theme pyyaml sphinx-copybutton 'sphinxcontrib-svg2pdfconverter>=2.0.0' 'pygments>=2.21.0'
And backport it to Wrynose/Scarthgap?
> Or maybe you want to write a custom bitbake lexer for stable
> branches that is an alias to the "default" (the default value of
> highlight_language) lexer, but only have it if the version of pygments
> doesn't contain a bitbake lexer already.
This could be an alternative, yes.
Quoting your other email (https://lore.kernel.org/r/66624f77-ae0d-4670-bd99-c6ea9d2b2a54@cherry.de):
> Sphinx explicitly states that Python will be tried and if there are
> highlights warnings, none will be used. c.f.
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples
This is interesting! If it behaves the same way with whatever highlight_language
you set in conf.py, then this would be less of an issue I guess.
Thanks,
Antonin
^ permalink raw reply related [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 15:10 ` Antonin Godard
@ 2026-08-26 15:43 ` Quentin Schulz
2026-08-27 8:02 ` Antonin Godard
0 siblings, 1 reply; 33+ messages in thread
From: Quentin Schulz @ 2026-08-26 15:43 UTC (permalink / raw)
To: Antonin Godard, twoerner, docs
On 8/26/26 5:10 PM, Antonin Godard wrote:
> Hi,
>
> On Wed Aug 26, 2026 at 4:34 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>
>>
>> On 8/26/26 3:09 PM, Antonin Godard wrote:
> [...]
>>>> I think this is going the wrong direction. We should actually make
>>>> explicit the language of every :: that is NOT to be understood as
>>>> BitBake code and then make the default highlight language be BitBake.
>>>
>>> But then this might get forgotten? How about having the default highlighted as
>>> "none", and make _everything_ use explicit code-blocks?
>>>
>>
>> """
>> The direct benefit is the ability to still backport whatever needs to be
>> backported without having to care about the highlight language being
>> explicitly bitbake (which won't be available in every branch but master).
>> """
>>
>> *exactly* the sentence after what you quoted.
>>
>> It's bound to happen someone will want to backport a patch with
>>
>> .. code-block:: bitbake
>>
>> Either we'll forget during review and it'll break the docs build, or we
>> need to adapt each and every patch/commit for stable branches.
>>
>> I'm usually the one trying to add friction to processes, but I don't
>> think the above is a good idea.
>>
>> I'm trying to avoid having code-blocks set to use the bitbake lexer so
>> we can easily backport without having to care.
>
> Our current active releases where we backport patches are Wrynose and Scarthgap.
> Both use the same buildtools tarball on the Autobuilder, and contain the same
But should they? Aren't we supposed to build the docs with an SDK we
build from the same branch as the one from the docs?
> version of pygments, so backporting patches that use the bitbake lexer won't be
> an issue (from an Autobuilder perspective).
>
>>> Sure, this is more efforts and review time, but also this is how other markup
>>> languages work - like markdown, where by default (when using ```...```) no
>>> syntax highlighting is done.
>>>> This is maybe a more conservative approach but at least it doesn't
>> leave room
>>> for code blocks mistakenly highlighted with the bitbake lexer.
>>>
>>
>> It's currently mistakenly highlighted in Python if it looks like Python
>> to pygments (the default).
>>
>> It's the Yocto/Bitbake documentation, I'm assuming the overwhelming
>> majority of code-blocks should be BitBake code.
>>
>> If you really want to require explicit lexers, then set
>>
>> highlight_language = "please_specify_the_highlight_language_for_this_block"
>>
>> in conf.py and then everybody will have to set one.
>>
>> Again, if you explicitly use the bitbake lexer in master, you won't be
>> able to backport those patches to stable branches easily. Or you'll need
>> your users to update their build environments to use the new release of
>> pygments.
>
> We can add a requirement on pygments:
>
> diff --git a/documentation/tools/host_packages_scripts/pip3_docs.sh b/documentation/tools/host_packages_scripts/pip3_docs.sh
> index 852845783..d7a983731 100644
> --- a/documentation/tools/host_packages_scripts/pip3_docs.sh
> +++ b/documentation/tools/host_packages_scripts/pip3_docs.sh
> @@ -1,3 +1,3 @@
> python3 -m venv --clear ./yocto-docs-venv
> . ./yocto-docs-venv/bin/activate
> -python3 -m pip install sphinx sphinx_rtd_theme pyyaml sphinx-copybutton 'sphinxcontrib-svg2pdfconverter>=2.0.0'
> +python3 -m pip install sphinx sphinx_rtd_theme pyyaml sphinx-copybutton 'sphinxcontrib-svg2pdfconverter>=2.0.0' 'pygments>=2.21.0'
>
> And backport it to Wrynose/Scarthgap?
>
/me shrugs
>> Or maybe you want to write a custom bitbake lexer for stable
>> branches that is an alias to the "default" (the default value of
>> highlight_language) lexer, but only have it if the version of pygments
>> doesn't contain a bitbake lexer already.
>
> This could be an alternative, yes.
>
> Quoting your other email (https://lore.kernel.org/r/66624f77-ae0d-4670-bd99-c6ea9d2b2a54@cherry.de):
>
>> Sphinx explicitly states that Python will be tried and if there are
>> highlights warnings, none will be used. c.f.
>> https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples
>
> This is interesting! If it behaves the same way with whatever highlight_language
> you set in conf.py, then this would be less of an issue I guess.
>
I don't know for sure without looking at Sphinx's source code but my
reading of the docs says "no", this is specific to "default"
(highlight_language = "default", which is the default value if absent).
highlight_block() in sphinx/highlighting.py has a check when there's a
parsing error to use none if the language is currently "default".
Reading a bit further down, there's a check on the force flag. I'm
assuming this comes from :force: from rST, so I'm not sure whether we
can actually pass it by default (and in any case, we would still have a
big fat warning, which we don't with the "default" value).
"default" seems to be a synonym of Python in get_lexer() as well, so not
sure we can simply decide "actually, no rather bitbake instead of python
lexer".
I haven't had a deeper look than that into Sphinx source code.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 14:45 ` Quentin Schulz
@ 2026-08-26 19:56 ` Trevor Woerner
2026-08-27 14:33 ` Quentin Schulz
0 siblings, 1 reply; 33+ messages in thread
From: Trevor Woerner @ 2026-08-26 19:56 UTC (permalink / raw)
To: Quentin Schulz; +Cc: Antonin Godard, docs
On Wed 2026-08-26 @ 04:45:33 PM, Quentin Schulz wrote:
>
>
> On 8/26/26 3:25 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > On Wed 2026-08-26 @ 03:09:23 PM, Antonin Godard wrote:
> > > Hi,
> > >
> > > On Wed Aug 26, 2026 at 2:10 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
> > > > Hi Trevor,
> > > >
> > > > On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:[...]>>>
> > > > [...]
> > > >
> > > > > Depends on
> > > > > ----------
> > > > >
> > > > > "docs: state the language of nine literal blocks explicitly", sent
> > > >
> > > > Link to the ML please to make maintainers and reviewers job easier.
> > > >
> > > > [...]
> > > >
> > > > I think this is going the wrong direction. We should actually make
> > > > explicit the language of every :: that is NOT to be understood as
> > > > BitBake code and then make the default highlight language be BitBake.
> > >
> > > But then this might get forgotten? How about having the default highlighted as
> > > "none", and make _everything_ use explicit code-blocks?
> > >
> > > Sure, this is more efforts and review time, but also this is how other markup
> > > languages work - like markdown, where by default (when using ```...```) no
> > > syntax highlighting is done.
> > >
> > > This is maybe a more conservative approach but at least it doesn't leave room
> > > for code blocks mistakenly highlighted with the bitbake lexer.
> >
> > Yes, I agree too. Personally I'm not fond of "hidden defaults".
> >
>
> There's already one.
True. So the choice is between:
- guessing python
- guessing bitbake
- or having the author state the expected language of every code-block
Personally my preference would be for every block to state it's expected
language. I don't think that's either too onerous or redundant. We put
".bb" and ".bbclass" at the end of every bitbake and bitbake class file
even though it's obvious what they are by virtue of where the live or
what the contain. In general we put ".html" at the end of html files and
".txt" at the end of text files.
But assuming I can't convince everyone that the language should be
explicit on each block, (and that each such item should have an explicit
"code-block:: <lang>" tag) the discussion devolves into: which default
is wrong least often :-) So i asked AI to measure it across all
currently untagged blocks:
lexed correct wrong unclass plain visibly
(known) (known) wrong
━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━ ━━━━━━━━ ━━━━━━━ ━━━━━━━━ ━━━━━━ ━━━━━━━
yocto-docs
bitbake 1502 841 9 652 0 96
python (today) 782 5 635 142 720 777
none 0 0 0 0 1502 0
───────────────────────── ─────── ──────── ─────── ──────── ────── ───────
BitBake user manual
bitbake 299 193 6 100 0 16
python (today) 182 6 148 28 117 176
none 0 0 0 0 299 0
───────────────────────── ─────── ──────── ─────── ──────── ────── ───────
both
bitbake 1801 1034 15 752 0 112
python (today) 964 11 783 170 837 953
none 0 0 0 0 1801 0
Setting the default to bitbake would be a real improvement on what we
have today. But it doesn't get us to correct. Across both repos it is
still wrong on 15 blocks we can name, it has no opinion at all about
another 752, and 112 end up visibly wrong. Those 752 won't be right
regardless of which default we choose.
Assuming your proposal is to set bitbake as the default, then tag
everything else. That _sounds_ good:
untagged bitbake still need % of
blocks a tag untagged
━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━ ━━━━━━━━ ━━━━━━━━━━ ━━━━━━━━━━
yocto-docs 1502 841 661 44%
───────────────────────── ──────── ──────── ────────── ──────────
BitBake user manual 299 193 106 35%
───────────────────────── ──────── ──────── ────────── ──────────
both 1801 1034 767 43%
Under "default bitbake, mark the exceptions" we would still have to
explicitly tag 661 blocks in yocto-docs and 106 in the bitbake manual:
767 by hand. Tagging everything is 1801. So we are marking hundreds of
blocks either way. 43% is not an "exception".
Which leaves how each scheme fails when somebody forgets. With bitbake as
the default a missed block renders as bitbake - confidently and silently
wrong. With none as the default it renders plain: bare, but it doesn't
claim anything untrue. Given we're tagging hundreds of blocks regardless,
I'd rather the mistakes look unstyled than look wrong.
That matters more here than it would in most projects, because bitbake is
a genuinely bad language to guess mechanically. Shell sessions,
TEMPLATECONF= environment assignments and buildhistory output all share
bitbake's NAME = value shape, so they pick up variable-assignment
colouring without being bitbake at all. In a lot of places our snippets
look like console, or bash, or python - or maybe bitbake.
> > By default a non-specified block will cause pygments to guess. So if I'm
>
> Sphinx explicitly states that Python will be tried and if there are
> highlights warnings, none will be used. c.f. https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples
>
> > looking at a lot of reST and seeing no tags, I'm going to assume the
> > authors have left pygments to guess. I would have to go looking in other
> > places to see if there's a default in place for non-specified code-block
> > tags, which I'm probably not going to think of doing, which will
> > sometimes probably cause more confusion before it becomes clear.
> >
>
> This is the Yocto/BitBake docs, we're documenting that project, which uses
> BitBake syntax. Would you want to write
>
> .. code-block:: rust
>
> for every code-block in the Rust documentation?
Yes.
First off, not all blocks are going to be rust, just as not all of ours
are bitbake:
Total blocks BitBake of all of untagged
━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━ ━━━━━━━━━ ━━━━━━━━ ━━━━━━━━━━━━━
yocto-docs 1929 841 44% 56%
───────────────────── ────────────── ───────── ──────── ─────────────
BitBake user manual 334 193 58% 65%
You might also be suspicious of an LLM's ability to judge what language
a block is. So am I. So the classification isn't what the numbers rest
on: every block that got tagged was then fed to BitBake's own parser,
using the regexes out of ConfHandler and BBHandler, and anything the
parser rejected was re-examined. That's how a Makefile, three U-Boot FIT
source blocks, five Python unittest classes and five kernel .scc files
got caught and pulled back out of an earlier version of this series.
The counts above come from parsing the built HTML.
> > Maybe it's just me, but I prefer to see every example block using an
> > explicit code-block tag and specifying a language. That way the author's
> > intentions are unambiguous, and we have an expected output.
> >
>
> You won't be able to backport patches with
>
> .. code-block:: bitbake
>
> which is what I would like to avoid. But I'm not the one sending patches to
> the stable branches nor the maintainer(s) handling stable, so maybe I
> shouldn't care.
For everything going back to scarthgap, the auto-builder uses the same
tarball for building the docs, regardless of branch. Therefore backports
amongst everything from scarthgap to master would be fine, once that
tarball is updated.
For backports to branches earlier than scarthgap the AB doesn't use the
-W flag, so those would simply emit a warning and render the blocks
plain. I checked this against the actual pairing in the older tarball,
sphinx 5.1.1 with pygments 2.13.0:
WARNING: Pygments lexer name 'bitbake' is not known
build succeeded, 1 warning.
with the block rendering plain. So that's not breakage, it's plain
presentation.
And it's arguably better than what those branches show today. Of the 841
blocks this series tags as bitbake, 632 currently render *highlighted
as python* and only 209 render plain. So on an older branch a backport
would be trading incorrect highlighting for none, rather than losing
anything.
> > That's what I've enforced for our reST at work, and I've also
> > differentiated between "bash" (for actual shell programs) versus
> > "console" (for interactive work at a shell prompt, a shell most likely
> > to be bash).
> >
>
> We differentiate console and shell in these docs here too. If you're seeing
> one that is using the wrong lexer, please fix it.
>
> Cheers,
> Quentin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 15:43 ` Quentin Schulz
@ 2026-08-27 8:02 ` Antonin Godard
0 siblings, 0 replies; 33+ messages in thread
From: Antonin Godard @ 2026-08-27 8:02 UTC (permalink / raw)
To: quentin.schulz, twoerner, docs
On Wed Aug 26, 2026 at 5:43 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>
>
> On 8/26/26 5:10 PM, Antonin Godard wrote:
>> Hi,
>>
>> On Wed Aug 26, 2026 at 4:34 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>>
>>>
>>> On 8/26/26 3:09 PM, Antonin Godard wrote:
>> [...]
>>>>> I think this is going the wrong direction. We should actually make
>>>>> explicit the language of every :: that is NOT to be understood as
>>>>> BitBake code and then make the default highlight language be BitBake.
>>>>
>>>> But then this might get forgotten? How about having the default highlighted as
>>>> "none", and make _everything_ use explicit code-blocks?
>>>>
>>>
>>> """
>>> The direct benefit is the ability to still backport whatever needs to be
>>> backported without having to care about the highlight language being
>>> explicitly bitbake (which won't be available in every branch but master).
>>> """
>>>
>>> *exactly* the sentence after what you quoted.
>>>
>>> It's bound to happen someone will want to backport a patch with
>>>
>>> .. code-block:: bitbake
>>>
>>> Either we'll forget during review and it'll break the docs build, or we
>>> need to adapt each and every patch/commit for stable branches.
>>>
>>> I'm usually the one trying to add friction to processes, but I don't
>>> think the above is a good idea.
>>>
>>> I'm trying to avoid having code-blocks set to use the bitbake lexer so
>>> we can easily backport without having to care.
>>
>> Our current active releases where we backport patches are Wrynose and Scarthgap.
>> Both use the same buildtools tarball on the Autobuilder, and contain the same
>
> But should they? Aren't we supposed to build the docs with an SDK we
> build from the same branch as the one from the docs?
It's been like this for a while now, and has not caused issues. I'm afraid
maintaining several SDKs for each branch would be a bit painful, although it's
probably the "right" thing to do.
[...]
>> This is interesting! If it behaves the same way with whatever highlight_language
>> you set in conf.py, then this would be less of an issue I guess.
>>
>
> I don't know for sure without looking at Sphinx's source code but my
> reading of the docs says "no", this is specific to "default"
> (highlight_language = "default", which is the default value if absent).
>
> highlight_block() in sphinx/highlighting.py has a check when there's a
> parsing error to use none if the language is currently "default".
> Reading a bit further down, there's a check on the force flag. I'm
> assuming this comes from :force: from rST, so I'm not sure whether we
> can actually pass it by default (and in any case, we would still have a
> big fat warning, which we don't with the "default" value).
>
> "default" seems to be a synonym of Python in get_lexer() as well, so not
> sure we can simply decide "actually, no rather bitbake instead of python
> lexer".
>
> I haven't had a deeper look than that into Sphinx source code.
I've tested it directly: setting highlight_language to "bitbake" would produce
errors in case Sphinx fails to highlight a code-block.
Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
` (11 preceding siblings ...)
2026-08-26 12:10 ` [docs] " Quentin Schulz
@ 2026-08-27 8:38 ` Antonin Godard
2026-08-27 11:34 ` Trevor Woerner
12 siblings, 1 reply; 33+ messages in thread
From: Antonin Godard @ 2026-08-27 8:38 UTC (permalink / raw)
To: twoerner, docs
Hi,
On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
[...]
> Not included
> ------------
>
> Six blocks in ref-manual/ trip a defect in the released BitBake lexer,
> fixed upstream but not yet in a release. They are a separate patch, held
> until that release, so the rest is not blocked behind them.
Would it make sense to apply a patch to Pygments in OE-Core to fix these issues
until a new version of Pygments is released?
Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-27 8:38 ` Antonin Godard
@ 2026-08-27 11:34 ` Trevor Woerner
2026-08-27 12:16 ` Antonin Godard
0 siblings, 1 reply; 33+ messages in thread
From: Trevor Woerner @ 2026-08-27 11:34 UTC (permalink / raw)
To: Antonin Godard; +Cc: docs
On Thu 2026-08-27 @ 10:38:58 AM, Antonin Godard wrote:
> Hi,
>
> On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> [...]
> > Not included
> > ------------
> >
> > Six blocks in ref-manual/ trip a defect in the released BitBake lexer,
> > fixed upstream but not yet in a release. They are a separate patch, held
> > until that release, so the rest is not blocked behind them.
>
> Would it make sense to apply a patch to Pygments in OE-Core to fix these issues
> until a new version of Pygments is released?
It would be very easy for me to provide a patch that would fix these
things locally until (if) upstream pygments picks up my updates:
https://github.com/pygments/pygments/pull/3284
I had wanted to add such a patch when I first developed the bitbake
lexer for pygments but the last time I proposed adding a temporary,
local pygments update it was decided we should wait for upstream.
Therefore I stopped short of doing that here.
I would also like to add a lexer for some other smaller stuff such as
SCC files. This lexer is very unlikely to be picked up by the upstream
pygments project; their own documentation says so explicitly:
https://pygments.org/docs/contributing/#language-support
But I think it would be nice if we had a highlighting scheme for it.
I'm more than happy to write it, but it is a plugin we would have to
carry ourselves.
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-27 11:34 ` Trevor Woerner
@ 2026-08-27 12:16 ` Antonin Godard
2026-08-27 14:23 ` Quentin Schulz
0 siblings, 1 reply; 33+ messages in thread
From: Antonin Godard @ 2026-08-27 12:16 UTC (permalink / raw)
To: Trevor Woerner; +Cc: docs
Hi,
On Thu Aug 27, 2026 at 1:34 PM CEST, Trevor Woerner wrote:
> On Thu 2026-08-27 @ 10:38:58 AM, Antonin Godard wrote:
>> Hi,
>>
>> On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
>> [...]
>> > Not included
>> > ------------
>> >
>> > Six blocks in ref-manual/ trip a defect in the released BitBake lexer,
>> > fixed upstream but not yet in a release. They are a separate patch, held
>> > until that release, so the rest is not blocked behind them.
>>
>> Would it make sense to apply a patch to Pygments in OE-Core to fix these issues
>> until a new version of Pygments is released?
>
> It would be very easy for me to provide a patch that would fix these
> things locally until (if) upstream pygments picks up my updates:
>
> https://github.com/pygments/pygments/pull/3284
>
> I had wanted to add such a patch when I first developed the bitbake
> lexer for pygments but the last time I proposed adding a temporary,
> local pygments update it was decided we should wait for upstream.
> Therefore I stopped short of doing that here.
I think you misunderstood me :) What I meant is that we could patch
python3-pygments in *OE-Core* (*not* provide the lexer from yocto-docs)
temporarily, until your above pull request is merged, and we drop the
patches in OE-Core after an update.
> I would also like to add a lexer for some other smaller stuff such as
> SCC files. This lexer is very unlikely to be picked up by the upstream
> pygments project; their own documentation says so explicitly:
>
> https://pygments.org/docs/contributing/#language-support
>
> But I think it would be nice if we had a highlighting scheme for it.
> I'm more than happy to write it, but it is a plugin we would have to
> carry ourselves.
Sure, I am open to small additional lexers in the documentation (as long as
they're small and simple enough to be maintainable), especially if upstream
refuses additional small lexer like this one.
Thanks,
Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-27 12:16 ` Antonin Godard
@ 2026-08-27 14:23 ` Quentin Schulz
0 siblings, 0 replies; 33+ messages in thread
From: Quentin Schulz @ 2026-08-27 14:23 UTC (permalink / raw)
To: antonin.godard, Trevor Woerner; +Cc: docs
Hi Antonin,
On 8/27/26 2:16 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Hi,
>
> On Thu Aug 27, 2026 at 1:34 PM CEST, Trevor Woerner wrote:
>> On Thu 2026-08-27 @ 10:38:58 AM, Antonin Godard wrote:
>>> Hi,
>>>
>>> On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
>>> [...]
>>>> Not included
>>>> ------------
>>>>
>>>> Six blocks in ref-manual/ trip a defect in the released BitBake lexer,
>>>> fixed upstream but not yet in a release. They are a separate patch, held
>>>> until that release, so the rest is not blocked behind them.
>>>
>>> Would it make sense to apply a patch to Pygments in OE-Core to fix these issues
>>> until a new version of Pygments is released?
>>
>> It would be very easy for me to provide a patch that would fix these
>> things locally until (if) upstream pygments picks up my updates:
>>
>> https://github.com/pygments/pygments/pull/3284
>>
>> I had wanted to add such a patch when I first developed the bitbake
>> lexer for pygments but the last time I proposed adding a temporary,
>> local pygments update it was decided we should wait for upstream.
>> Therefore I stopped short of doing that here.
>
> I think you misunderstood me :) What I meant is that we could patch
> python3-pygments in *OE-Core* (*not* provide the lexer from yocto-docs)
> temporarily, until your above pull request is merged, and we drop the
> patches in OE-Core after an update.
>
Please don't, otherwise people will be forced to use the buildtools to
build the docs.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-26 19:56 ` Trevor Woerner
@ 2026-08-27 14:33 ` Quentin Schulz
2026-08-31 9:01 ` Antonin Godard
0 siblings, 1 reply; 33+ messages in thread
From: Quentin Schulz @ 2026-08-27 14:33 UTC (permalink / raw)
To: Trevor Woerner; +Cc: Antonin Godard, docs
Hi Trevor,
On 8/26/26 9:56 PM, Trevor Woerner wrote:
> On Wed 2026-08-26 @ 04:45:33 PM, Quentin Schulz wrote:
>>
>>
>> On 8/26/26 3:25 PM, Trevor Woerner via lists.yoctoproject.org wrote:
>>> On Wed 2026-08-26 @ 03:09:23 PM, Antonin Godard wrote:
>>>> Hi,
>>>>
>>>> On Wed Aug 26, 2026 at 2:10 PM CEST, Quentin Schulz via lists.yoctoproject.org wrote:
>>>>> Hi Trevor,
>>>>>
>>>>> On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:[...]>>>
>>>>> [...]
>>>>>
>>>>>> Depends on
>>>>>> ----------
>>>>>>
>>>>>> "docs: state the language of nine literal blocks explicitly", sent
>>>>>
>>>>> Link to the ML please to make maintainers and reviewers job easier.
>>>>>
>>>>> [...]
>>>>>
>>>>> I think this is going the wrong direction. We should actually make
>>>>> explicit the language of every :: that is NOT to be understood as
>>>>> BitBake code and then make the default highlight language be BitBake.
>>>>
>>>> But then this might get forgotten? How about having the default highlighted as
>>>> "none", and make _everything_ use explicit code-blocks?
>>>>
>>>> Sure, this is more efforts and review time, but also this is how other markup
>>>> languages work - like markdown, where by default (when using ```...```) no
>>>> syntax highlighting is done.
>>>>
>>>> This is maybe a more conservative approach but at least it doesn't leave room
>>>> for code blocks mistakenly highlighted with the bitbake lexer.
>>>
>>> Yes, I agree too. Personally I'm not fond of "hidden defaults".
>>>
>>
>> There's already one.
>
> True. So the choice is between:
> - guessing python
> - guessing bitbake
> - or having the author state the expected language of every code-block
>
> Personally my preference would be for every block to state it's expected
> language. I don't think that's either too onerous or redundant. We put
> ".bb" and ".bbclass" at the end of every bitbake and bitbake class file
> even though it's obvious what they are by virtue of where the live or
> what the contain. In general we put ".html" at the end of html files and
> ".txt" at the end of text files.
>
> But assuming I can't convince everyone that the language should be
> explicit on each block, (and that each such item should have an explicit
> "code-block:: <lang>" tag) the discussion devolves into: which default
> is wrong least often :-) So i asked AI to measure it across all
> currently untagged blocks:
>
>
> lexed correct wrong unclass plain visibly
> (known) (known) wrong
> ━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━ ━━━━━━━━ ━━━━━━━ ━━━━━━━━ ━━━━━━ ━━━━━━━
> yocto-docs
> bitbake 1502 841 9 652 0 96
> python (today) 782 5 635 142 720 777
> none 0 0 0 0 1502 0
> ───────────────────────── ─────── ──────── ─────── ──────── ────── ───────
> BitBake user manual
> bitbake 299 193 6 100 0 16
> python (today) 182 6 148 28 117 176
> none 0 0 0 0 299 0
> ───────────────────────── ─────── ──────── ─────── ──────── ────── ───────
> both
> bitbake 1801 1034 15 752 0 112
> python (today) 964 11 783 170 837 953
> none 0 0 0 0 1801 0
>
>
> Setting the default to bitbake would be a real improvement on what we
> have today. But it doesn't get us to correct. Across both repos it is
> still wrong on 15 blocks we can name, it has no opinion at all about
> another 752, and 112 end up visibly wrong. Those 752 won't be right
> regardless of which default we choose.
>
> Assuming your proposal is to set bitbake as the default, then tag
> everything else. That _sounds_ good:
>
> untagged bitbake still need % of
> blocks a tag untagged
> ━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━ ━━━━━━━━ ━━━━━━━━━━ ━━━━━━━━━━
> yocto-docs 1502 841 661 44%
> ───────────────────────── ──────── ──────── ────────── ──────────
> BitBake user manual 299 193 106 35%
> ───────────────────────── ──────── ──────── ────────── ──────────
> both 1801 1034 767 43%
>
>
> Under "default bitbake, mark the exceptions" we would still have to
> explicitly tag 661 blocks in yocto-docs and 106 in the bitbake manual:
> 767 by hand. Tagging everything is 1801. So we are marking hundreds of
> blocks either way. 43% is not an "exception".
>
> Which leaves how each scheme fails when somebody forgets. With bitbake as
> the default a missed block renders as bitbake - confidently and silently
> wrong. With none as the default it renders plain: bare, but it doesn't
> claim anything untrue. Given we're tagging hundreds of blocks regardless,
> I'd rather the mistakes look unstyled than look wrong.
>
Just to be clear, we do not use none today. We use "default", which uses
Python except if there are warnings, in which case it falls back to none.
> That matters more here than it would in most projects, because bitbake is
> a genuinely bad language to guess mechanically. Shell sessions,
> TEMPLATECONF= environment assignments and buildhistory output all share
> bitbake's NAME = value shape, so they pick up variable-assignment
> colouring without being bitbake at all. In a lot of places our snippets
> look like console, or bash, or python - or maybe bitbake.
>
>>> By default a non-specified block will cause pygments to guess. So if I'm
>>
>> Sphinx explicitly states that Python will be tried and if there are
>> highlights warnings, none will be used. c.f. https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples
>>
>>> looking at a lot of reST and seeing no tags, I'm going to assume the
>>> authors have left pygments to guess. I would have to go looking in other
>>> places to see if there's a default in place for non-specified code-block
>>> tags, which I'm probably not going to think of doing, which will
>>> sometimes probably cause more confusion before it becomes clear.
>>>
>>
>> This is the Yocto/BitBake docs, we're documenting that project, which uses
>> BitBake syntax. Would you want to write
>>
>> .. code-block:: rust
>>
>> for every code-block in the Rust documentation?
>
> Yes.
>
I find this very unnecessary but I guess we can agree to disagree :)
> First off, not all blocks are going to be rust, just as not all of ours
> are bitbake:
>
> Total blocks BitBake of all of untagged
> ━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━ ━━━━━━━━━ ━━━━━━━━ ━━━━━━━━━━━━━
> yocto-docs 1929 841 44% 56%
> ───────────────────── ────────────── ───────── ──────── ─────────────
> BitBake user manual 334 193 58% 65%
>
>
> You might also be suspicious of an LLM's ability to judge what language
> a block is. So am I. So the classification isn't what the numbers rest
> on: every block that got tagged was then fed to BitBake's own parser,
> using the regexes out of ConfHandler and BBHandler, and anything the
> parser rejected was re-examined. That's how a Makefile, three U-Boot FIT
> source blocks, five Python unittest classes and five kernel .scc files
> got caught and pulled back out of an earlier version of this series.
> The counts above come from parsing the built HTML.
>
I actually forced a code block to be Python and attempted to make it
syntactically wrong, the lexer still happily chugged along. So I'm not
sure any tool will get the numbers right.
>>> Maybe it's just me, but I prefer to see every example block using an
>>> explicit code-block tag and specifying a language. That way the author's
>>> intentions are unambiguous, and we have an expected output.
>>>
>>
>> You won't be able to backport patches with
>>
>> .. code-block:: bitbake
>>
>> which is what I would like to avoid. But I'm not the one sending patches to
>> the stable branches nor the maintainer(s) handling stable, so maybe I
>> shouldn't care.
>
> For everything going back to scarthgap, the auto-builder uses the same
> tarball for building the docs, regardless of branch. Therefore backports
> amongst everything from scarthgap to master would be fine, once that
> tarball is updated.
>
This is looked at through the autobuilder scope, the docs are still
supposed to be somewhat buildable without buildtools or autobuilders.
but fine.
> For backports to branches earlier than scarthgap the AB doesn't use the
> -W flag, so those would simply emit a warning and render the blocks
> plain. I checked this against the actual pairing in the older tarball,
> sphinx 5.1.1 with pygments 2.13.0:
>
> WARNING: Pygments lexer name 'bitbake' is not known
> build succeeded, 1 warning.
>
> with the block rendering plain. So that's not breakage, it's plain
> presentation.
>
I'm not sure saying warnings are fine is something the project wants to
get behind. But maybe it is fine, I don't have much power there :)
> And it's arguably better than what those branches show today. Of the 841
> blocks this series tags as bitbake, 632 currently render *highlighted
> as python* and only 209 render plain. So on an older branch a backport
> would be trading incorrect highlighting for none, rather than losing
> anything.
>
>
>>> That's what I've enforced for our reST at work, and I've also
>>> differentiated between "bash" (for actual shell programs) versus
>>> "console" (for interactive work at a shell prompt, a shell most likely
>>> to be bash).
>>>
>>
>> We differentiate console and shell in these docs here too. If you're seeing
>> one that is using the wrong lexer, please fix it.
>>
>> Cheers,
>> Quentin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-27 14:33 ` Quentin Schulz
@ 2026-08-31 9:01 ` Antonin Godard
2026-08-31 13:18 ` Trevor Woerner
2026-08-31 14:16 ` Trevor Woerner
0 siblings, 2 replies; 33+ messages in thread
From: Antonin Godard @ 2026-08-31 9:01 UTC (permalink / raw)
To: Quentin Schulz, Trevor Woerner; +Cc: docs
Hi Quentin, Trevor,
After having thought about this a bit more, I think there are pros and cons to
both approaches, but I'm leaning towards Quentin's approach. The other approach
may feel "safe", and doesn't leave room to errors, but I'm afraid that 1. most
contributors will forget about it and 2. it might make the process more painful
for them.
So here what we should do:
- set `hightlight_language = "bitbake"` in conf.py.
- remove file-wide lexer enforcing (.. highlight:: directive at the top of the
file) (in a separate patch)
- use the appropriate lexer for each code-block that is _not_ bitbake code.
- fix any parsing error from the bitbake lexer (I did have some when trying it).
If this happens, use "none" and *add a identifiable comment* above it to
explain that there's an issue with the lexer. This way we can track them and
fix them when Pygments gets an update.
- document this way of proceeding in standards.md.
If you think of anything else we should do here, please share your thoughts :)
Trevor, if you want to send another version of your series, please rebase on
*master-next* as it contains cleanups to the conf.py file at the moment (+ some
possible additional code-blocks).
Thanks both for sharing your thoughts on this!
Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-31 9:01 ` Antonin Godard
@ 2026-08-31 13:18 ` Trevor Woerner
2026-08-31 14:16 ` Trevor Woerner
1 sibling, 0 replies; 33+ messages in thread
From: Trevor Woerner @ 2026-08-31 13:18 UTC (permalink / raw)
To: Antonin Godard; +Cc: Quentin Schulz, docs
On Mon 2026-08-31 @ 11:01:44 AM, Antonin Godard wrote:
> Hi Quentin, Trevor,
>
> After having thought about this a bit more, I think there are pros and cons to
> both approaches, but I'm leaning towards Quentin's approach. The other approach
> may feel "safe", and doesn't leave room to errors, but I'm afraid that 1. most
> contributors will forget about it and 2. it might make the process more painful
> for them.
>
> So here what we should do:
>
> - set `hightlight_language = "bitbake"` in conf.py.
>
> - remove file-wide lexer enforcing (.. highlight:: directive at the top of the
> file) (in a separate patch)
>
> - use the appropriate lexer for each code-block that is _not_ bitbake code.
>
> - fix any parsing error from the bitbake lexer (I did have some when trying it).
> If this happens, use "none" and *add a identifiable comment* above it to
> explain that there's an issue with the lexer. This way we can track them and
> fix them when Pygments gets an update.
>
> - document this way of proceeding in standards.md.
Excellent! It is fantastic having this nailed down.
> If you think of anything else we should do here, please share your thoughts :)
>
> Trevor, if you want to send another version of your series, please rebase on
> *master-next* as it contains cleanups to the conf.py file at the moment (+ some
> possible additional code-blocks).
>
> Thanks both for sharing your thoughts on this!
>
> Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-31 9:01 ` Antonin Godard
2026-08-31 13:18 ` Trevor Woerner
@ 2026-08-31 14:16 ` Trevor Woerner
2026-08-31 15:19 ` Antonin Godard
1 sibling, 1 reply; 33+ messages in thread
From: Trevor Woerner @ 2026-08-31 14:16 UTC (permalink / raw)
To: Antonin Godard; +Cc: Quentin Schulz, docs
On Mon 2026-08-31 @ 11:01:44 AM, Antonin Godard wrote:
> Hi Quentin, Trevor,
>
> After having thought about this a bit more, I think there are pros and cons to
> both approaches, but I'm leaning towards Quentin's approach. The other approach
> may feel "safe", and doesn't leave room to errors, but I'm afraid that 1. most
> contributors will forget about it and 2. it might make the process more painful
> for them.
>
> So here what we should do:
>
> - set `hightlight_language = "bitbake"` in conf.py.
>
> - remove file-wide lexer enforcing (.. highlight:: directive at the top of the
> file) (in a separate patch)
>
> - use the appropriate lexer for each code-block that is _not_ bitbake code.
>
> - fix any parsing error from the bitbake lexer (I did have some when trying it).
> If this happens, use "none" and *add a identifiable comment* above it to
> explain that there's an issue with the lexer. This way we can track them and
> fix them when Pygments gets an update.
The pygments releases occur on a rather slow timeline, I predict the next
release will probably be in Dec if not Jan 2027, if history is any
indicator.
There's a problem (Quentin mentioned it in one of his replies): users
don't use the tarball that the AB uses (in general, I assume) and
versions are not pinned. So users are free to use whatever is on their
system but hopefully have created a venv. But even if they're using a
venv there's no guarantee that they're updating their tools regularly.
So we're left with the following situation:
- the AB has to wait until the tarball is updated
- users might be using older versions of pygments
And then on top of that you layer on the situation of trying to generate
docs for older releases not to mention backports.
However, I can add a shim so that everything works out of the box
today. The shim can be smart enough to examine the bitbake support
independently (at runtime) and only load itself when it is needed
(either an older version of pygments that has no support, or the 2.21.0
version that needs additional support). If/when pygments is updated
(after the next release and either because the user has updated their
tools or the tarball has been updated) the shim will not load itself.
Carrying a bitbake language shim in the docs repository itself:
- the AB doesn't have to wait for an update, bitbake works today on all
valid snippets
- backports can start working today too, since tooling doesn't have to
be updated, the shim knows how to highlight bitbake independent of
tools or versions
- we don't have to wait for the next release (5-6 months) for all
the bitbake snippets to parse correctly
The nice thing about the shim (the way I've designed it) is it is
dynamic. It will look for any bitbake support in the currently used
tools. After running a tiny bit of testing it will load itself only:
- if there is no bitbake support
- if the bitbake support is incomplete
Otherwise it won't load and won't interfere.
Even once the next release of pygments occurs and full bitbake support
exists, it will still be a good idea to carry the shim so that older
docs, users with older tools, and the AB doesn't have to wait for a new
tarball to get full bitbake highlighting.
Also, this way we don't have to skip the non-working snippets today
with a comments, all snippets will highlight today, no need to go back
and fix things up in 6 months if someone remembers, etc. Full bitbake
highlighting for everyone under any circumstance starting today and
available forever across all versions of docs and tools.
>
> - document this way of proceeding in standards.md.
>
> If you think of anything else we should do here, please share your thoughts :)
>
> Trevor, if you want to send another version of your series, please rebase on
> *master-next* as it contains cleanups to the conf.py file at the moment (+ some
> possible additional code-blocks).
>
> Thanks both for sharing your thoughts on this!
>
> Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-31 14:16 ` Trevor Woerner
@ 2026-08-31 15:19 ` Antonin Godard
2026-08-31 15:55 ` Trevor Woerner
0 siblings, 1 reply; 33+ messages in thread
From: Antonin Godard @ 2026-08-31 15:19 UTC (permalink / raw)
To: Trevor Woerner; +Cc: Quentin Schulz, docs
On Mon Aug 31, 2026 at 4:16 PM CEST, Trevor Woerner wrote:
> On Mon 2026-08-31 @ 11:01:44 AM, Antonin Godard wrote:
>> Hi Quentin, Trevor,
>>
>> After having thought about this a bit more, I think there are pros and cons to
>> both approaches, but I'm leaning towards Quentin's approach. The other approach
>> may feel "safe", and doesn't leave room to errors, but I'm afraid that 1. most
>> contributors will forget about it and 2. it might make the process more painful
>> for them.
>>
>> So here what we should do:
>>
>> - set `hightlight_language = "bitbake"` in conf.py.
>>
>> - remove file-wide lexer enforcing (.. highlight:: directive at the top of the
>> file) (in a separate patch)
>>
>> - use the appropriate lexer for each code-block that is _not_ bitbake code.
>>
>> - fix any parsing error from the bitbake lexer (I did have some when trying it).
>> If this happens, use "none" and *add a identifiable comment* above it to
>> explain that there's an issue with the lexer. This way we can track them and
>> fix them when Pygments gets an update.
>
> The pygments releases occur on a rather slow timeline, I predict the next
> release will probably be in Dec if not Jan 2027, if history is any
> indicator.
>
> There's a problem (Quentin mentioned it in one of his replies): users
> don't use the tarball that the AB uses (in general, I assume) and
> versions are not pinned. So users are free to use whatever is on their
> system but hopefully have created a venv. But even if they're using a
> venv there's no guarantee that they're updating their tools regularly.
We can pin the version required to build the docs in
documentation/tools/host_packages_scripts/pip3_docs.sh. This will become the
minimum version of Pygments required to build the docs.
> So we're left with the following situation:
> - the AB has to wait until the tarball is updated
> - users might be using older versions of pygments
>
> And then on top of that you layer on the situation of trying to generate
> docs for older releases not to mention backports.
The change in conf.py will not impact older releases, so they should be safe to
build, even if Pygments is updated with the bitbake lexer: it simply won't be
used, because highlight_language is still "default" on these.
Note: I think this change is big enough that I don't consider it candidate for
backport on stable branches.
> However, I can add a shim so that everything works out of the box
> today. The shim can be smart enough to examine the bitbake support
> independently (at runtime) and only load itself when it is needed
> (either an older version of pygments that has no support, or the 2.21.0
> version that needs additional support). If/when pygments is updated
> (after the next release and either because the user has updated their
> tools or the tarball has been updated) the shim will not load itself.
>
> Carrying a bitbake language shim in the docs repository itself:
> - the AB doesn't have to wait for an update, bitbake works today on all
> valid snippets
> - backports can start working today too, since tooling doesn't have to
> be updated, the shim knows how to highlight bitbake independent of
> tools or versions
> - we don't have to wait for the next release (5-6 months) for all
> the bitbake snippets to parse correctly
>
> The nice thing about the shim (the way I've designed it) is it is
> dynamic. It will look for any bitbake support in the currently used
> tools. After running a tiny bit of testing it will load itself only:
> - if there is no bitbake support
> - if the bitbake support is incomplete
> Otherwise it won't load and won't interfere.
>
> Even once the next release of pygments occurs and full bitbake support
> exists, it will still be a good idea to carry the shim so that older
> docs, users with older tools, and the AB doesn't have to wait for a new
> tarball to get full bitbake highlighting.
>
> Also, this way we don't have to skip the non-working snippets today
> with a comments, all snippets will highlight today, no need to go back
> and fix things up in 6 months if someone remembers, etc. Full bitbake
> highlighting for everyone under any circumstance starting today and
> available forever across all versions of docs and tools.
Considering what I've said above, do you really think that's necessary? To me it
feels like increased complexity considering we'll only add this feature on
master, and it should be straightforward from there to fix future stable
releases with backport patches when Pygments gets updated.
Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-31 15:19 ` Antonin Godard
@ 2026-08-31 15:55 ` Trevor Woerner
2026-09-01 7:31 ` Antonin Godard
0 siblings, 1 reply; 33+ messages in thread
From: Trevor Woerner @ 2026-08-31 15:55 UTC (permalink / raw)
To: Antonin Godard; +Cc: Quentin Schulz, docs
On Mon 2026-08-31 @ 05:19:37 PM, Antonin Godard wrote:
> On Mon Aug 31, 2026 at 4:16 PM CEST, Trevor Woerner wrote:
> > On Mon 2026-08-31 @ 11:01:44 AM, Antonin Godard wrote:
> >> Hi Quentin, Trevor,
> >>
> >> After having thought about this a bit more, I think there are pros and cons to
> >> both approaches, but I'm leaning towards Quentin's approach. The other approach
> >> may feel "safe", and doesn't leave room to errors, but I'm afraid that 1. most
> >> contributors will forget about it and 2. it might make the process more painful
> >> for them.
> >>
> >> So here what we should do:
> >>
> >> - set `hightlight_language = "bitbake"` in conf.py.
> >>
> >> - remove file-wide lexer enforcing (.. highlight:: directive at the top of the
> >> file) (in a separate patch)
> >>
> >> - use the appropriate lexer for each code-block that is _not_ bitbake code.
> >>
> >> - fix any parsing error from the bitbake lexer (I did have some when trying it).
> >> If this happens, use "none" and *add a identifiable comment* above it to
> >> explain that there's an issue with the lexer. This way we can track them and
> >> fix them when Pygments gets an update.
> >
> > The pygments releases occur on a rather slow timeline, I predict the next
> > release will probably be in Dec if not Jan 2027, if history is any
> > indicator.
> >
> > There's a problem (Quentin mentioned it in one of his replies): users
> > don't use the tarball that the AB uses (in general, I assume) and
> > versions are not pinned. So users are free to use whatever is on their
> > system but hopefully have created a venv. But even if they're using a
> > venv there's no guarantee that they're updating their tools regularly.
>
> We can pin the version required to build the docs in
> documentation/tools/host_packages_scripts/pip3_docs.sh. This will become the
> minimum version of Pygments required to build the docs.
>
> > So we're left with the following situation:
> > - the AB has to wait until the tarball is updated
> > - users might be using older versions of pygments
> >
> > And then on top of that you layer on the situation of trying to generate
> > docs for older releases not to mention backports.
>
> The change in conf.py will not impact older releases, so they should be safe to
> build, even if Pygments is updated with the bitbake lexer: it simply won't be
> used, because highlight_language is still "default" on these.
If we set:
highlight_language = "bitbake"
in conf.py right now, anyone who is not running pygments 2.21.0 will get
warnings which translate to build failures via the Makefile's -W
setting.
> Note: I think this change is big enough that I don't consider it candidate for
> backport on stable branches.
>
> > However, I can add a shim so that everything works out of the box
> > today. The shim can be smart enough to examine the bitbake support
> > independently (at runtime) and only load itself when it is needed
> > (either an older version of pygments that has no support, or the 2.21.0
> > version that needs additional support). If/when pygments is updated
> > (after the next release and either because the user has updated their
> > tools or the tarball has been updated) the shim will not load itself.
> >
> > Carrying a bitbake language shim in the docs repository itself:
> > - the AB doesn't have to wait for an update, bitbake works today on all
> > valid snippets
> > - backports can start working today too, since tooling doesn't have to
> > be updated, the shim knows how to highlight bitbake independent of
> > tools or versions
> > - we don't have to wait for the next release (5-6 months) for all
> > the bitbake snippets to parse correctly
> >
> > The nice thing about the shim (the way I've designed it) is it is
> > dynamic. It will look for any bitbake support in the currently used
> > tools. After running a tiny bit of testing it will load itself only:
> > - if there is no bitbake support
> > - if the bitbake support is incomplete
> > Otherwise it won't load and won't interfere.
> >
> > Even once the next release of pygments occurs and full bitbake support
> > exists, it will still be a good idea to carry the shim so that older
> > docs, users with older tools, and the AB doesn't have to wait for a new
> > tarball to get full bitbake highlighting.
> >
> > Also, this way we don't have to skip the non-working snippets today
> > with a comments, all snippets will highlight today, no need to go back
> > and fix things up in 6 months if someone remembers, etc. Full bitbake
> > highlighting for everyone under any circumstance starting today and
> > available forever across all versions of docs and tools.
>
> Considering what I've said above, do you really think that's necessary? To me it
> feels like increased complexity considering we'll only add this feature on
> master, and it should be straightforward from there to fix future stable
> releases with backport patches when Pygments gets updated.
What's the complexity? The shim is written, it's done, it works
regardless of which pygments version anyone (AB, users) are using and it
doesn't install if the conditions are met. No waiting, everyone gets all
bitbake highlighted today.
If anything not adding the shim *is* where the complexity lies. Once you
accept the default conf.py patch the AB must be using the new pygments,
and users will see build errors, and report them, until we point out
they have to update their tools.
> Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
* Re: [docs] [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language
2026-08-31 15:55 ` Trevor Woerner
@ 2026-09-01 7:31 ` Antonin Godard
0 siblings, 0 replies; 33+ messages in thread
From: Antonin Godard @ 2026-09-01 7:31 UTC (permalink / raw)
To: Trevor Woerner; +Cc: Quentin Schulz, docs
On Mon Aug 31, 2026 at 5:55 PM CEST, Trevor Woerner wrote:
> On Mon 2026-08-31 @ 05:19:37 PM, Antonin Godard wrote:
>> On Mon Aug 31, 2026 at 4:16 PM CEST, Trevor Woerner wrote:
>> > On Mon 2026-08-31 @ 11:01:44 AM, Antonin Godard wrote:
>> >> Hi Quentin, Trevor,
>> >>
>> >> After having thought about this a bit more, I think there are pros and cons to
>> >> both approaches, but I'm leaning towards Quentin's approach. The other approach
>> >> may feel "safe", and doesn't leave room to errors, but I'm afraid that 1. most
>> >> contributors will forget about it and 2. it might make the process more painful
>> >> for them.
>> >>
>> >> So here what we should do:
>> >>
>> >> - set `hightlight_language = "bitbake"` in conf.py.
>> >>
>> >> - remove file-wide lexer enforcing (.. highlight:: directive at the top of the
>> >> file) (in a separate patch)
>> >>
>> >> - use the appropriate lexer for each code-block that is _not_ bitbake code.
>> >>
>> >> - fix any parsing error from the bitbake lexer (I did have some when trying it).
>> >> If this happens, use "none" and *add a identifiable comment* above it to
>> >> explain that there's an issue with the lexer. This way we can track them and
>> >> fix them when Pygments gets an update.
>> >
>> > The pygments releases occur on a rather slow timeline, I predict the next
>> > release will probably be in Dec if not Jan 2027, if history is any
>> > indicator.
>> >
>> > There's a problem (Quentin mentioned it in one of his replies): users
>> > don't use the tarball that the AB uses (in general, I assume) and
>> > versions are not pinned. So users are free to use whatever is on their
>> > system but hopefully have created a venv. But even if they're using a
>> > venv there's no guarantee that they're updating their tools regularly.
>>
>> We can pin the version required to build the docs in
>> documentation/tools/host_packages_scripts/pip3_docs.sh. This will become the
>> minimum version of Pygments required to build the docs.
>>
>> > So we're left with the following situation:
>> > - the AB has to wait until the tarball is updated
>> > - users might be using older versions of pygments
>> >
>> > And then on top of that you layer on the situation of trying to generate
>> > docs for older releases not to mention backports.
>>
>> The change in conf.py will not impact older releases, so they should be safe to
>> build, even if Pygments is updated with the bitbake lexer: it simply won't be
>> used, because highlight_language is still "default" on these.
>
> If we set:
>
> highlight_language = "bitbake"
>
> in conf.py right now, anyone who is not running pygments 2.21.0 will get
> warnings which translate to build failures via the Makefile's -W
> setting.
We're on the master branch, having such changes is acceptable, and we can state
the version of pygments needed in our requirements.
>> Note: I think this change is big enough that I don't consider it candidate for
>> backport on stable branches.
>>
>> > However, I can add a shim so that everything works out of the box
>> > today. The shim can be smart enough to examine the bitbake support
>> > independently (at runtime) and only load itself when it is needed
>> > (either an older version of pygments that has no support, or the 2.21.0
>> > version that needs additional support). If/when pygments is updated
>> > (after the next release and either because the user has updated their
>> > tools or the tarball has been updated) the shim will not load itself.
>> >
>> > Carrying a bitbake language shim in the docs repository itself:
>> > - the AB doesn't have to wait for an update, bitbake works today on all
>> > valid snippets
>> > - backports can start working today too, since tooling doesn't have to
>> > be updated, the shim knows how to highlight bitbake independent of
>> > tools or versions
>> > - we don't have to wait for the next release (5-6 months) for all
>> > the bitbake snippets to parse correctly
>> >
>> > The nice thing about the shim (the way I've designed it) is it is
>> > dynamic. It will look for any bitbake support in the currently used
>> > tools. After running a tiny bit of testing it will load itself only:
>> > - if there is no bitbake support
>> > - if the bitbake support is incomplete
>> > Otherwise it won't load and won't interfere.
>> >
>> > Even once the next release of pygments occurs and full bitbake support
>> > exists, it will still be a good idea to carry the shim so that older
>> > docs, users with older tools, and the AB doesn't have to wait for a new
>> > tarball to get full bitbake highlighting.
>> >
>> > Also, this way we don't have to skip the non-working snippets today
>> > with a comments, all snippets will highlight today, no need to go back
>> > and fix things up in 6 months if someone remembers, etc. Full bitbake
>> > highlighting for everyone under any circumstance starting today and
>> > available forever across all versions of docs and tools.
>>
>> Considering what I've said above, do you really think that's necessary? To me it
>> feels like increased complexity considering we'll only add this feature on
>> master, and it should be straightforward from there to fix future stable
>> releases with backport patches when Pygments gets updated.
>
> What's the complexity? The shim is written, it's done, it works
> regardless of which pygments version anyone (AB, users) are using and it
> doesn't install if the conditions are met. No waiting, everyone gets all
> bitbake highlighted today.
>
> If anything not adding the shim *is* where the complexity lies. Once you
> accept the default conf.py patch the AB must be using the new pygments,
> and users will see build errors, and report them, until we point out
> they have to update their tools.
Please send it - perhaps as a separate patch - so I can review it.
Thanks,
Antonin
^ permalink raw reply [flat|nested] 33+ messages in thread
end of thread, other threads:[~2026-09-01 7:31 UTC | newest]
Thread overview: 33+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-08-26 1:34 [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Trevor Woerner
2026-08-26 1:34 ` [PATCH 01/10] ref-manual/variables.rst: use the bitbake code-block language Trevor Woerner
2026-08-26 1:34 ` [PATCH 02/10] ref-manual: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 03/10] dev-manual: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 04/10] migration-guides: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 05/10] kernel-dev: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 06/10] test-manual: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 07/10] overview-manual: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 08/10] security-manual: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 09/10] sdk-manual: " Trevor Woerner
2026-08-26 1:34 ` [PATCH 10/10] docs-wide: " Trevor Woerner
2026-08-26 11:56 ` [PATCH 00/10] docs: highlight BitBake snippets with the bitbake language Paul Barker
2026-08-26 13:29 ` Trevor Woerner
2026-08-26 12:10 ` [docs] " Quentin Schulz
2026-08-26 13:09 ` Antonin Godard
2026-08-26 13:25 ` Trevor Woerner
2026-08-26 14:45 ` Quentin Schulz
2026-08-26 19:56 ` Trevor Woerner
2026-08-27 14:33 ` Quentin Schulz
2026-08-31 9:01 ` Antonin Godard
2026-08-31 13:18 ` Trevor Woerner
2026-08-31 14:16 ` Trevor Woerner
2026-08-31 15:19 ` Antonin Godard
2026-08-31 15:55 ` Trevor Woerner
2026-09-01 7:31 ` Antonin Godard
2026-08-26 14:34 ` Quentin Schulz
2026-08-26 15:10 ` Antonin Godard
2026-08-26 15:43 ` Quentin Schulz
2026-08-27 8:02 ` Antonin Godard
2026-08-27 8:38 ` Antonin Godard
2026-08-27 11:34 ` Trevor Woerner
2026-08-27 12:16 ` Antonin Godard
2026-08-27 14:23 ` Quentin Schulz
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox