docs: highlight BitBake snippets with the bitbake language
cover docs: highlight BitBake snippets with the bitbake language
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(-)
PATCH 1/10 ref-manual/variables.rst: use the bitbake code-block language
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)
--- documentation/ref-manual/variables.rst | 1635 ++++++++++++++++++------ 1 file changed, 1226 insertions(+), 409 deletions(-)
documentation/ref-manual/variables.rst +1226 -409
@@ -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 <[email protected]>" 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 <[email protected]>"
@@ -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`
Lines of this file are not shown. View the raw message.
The rest of this diff is not shown. View the raw message.
Part of the diff is not shown here. View the raw message.
PATCH 5/10 kernel-dev: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- 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(-)
documentation/kernel-dev/advanced.rst +36 -12
@@ -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"
documentation/kernel-dev/common.rst +66 -22
220 lines not on this page · raw message
documentation/kernel-dev/faq.rst +6 -2
@@ -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"
PATCH 6/10 test-manual: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- 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(-)
documentation/test-manual/intro.rst +3 -1
@@ -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"
documentation/test-manual/ptest.rst +18 -6
@@ -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
documentation/test-manual/reproducible-builds.rst +6 -2
@@ -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"
documentation/test-manual/runtime-testing.rst +39 -13
124 lines not on this page · raw message
PATCH 2/10 ref-manual: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- 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(-)
documentation/ref-manual/classes.rst +126 -42
@@ -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"
documentation/ref-manual/devtool-reference.rst +3 -1
@@ -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"
documentation/ref-manual/faq.rst +15 -5
@@ -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/ \
documentation/ref-manual/features.rst +9 -3
@@ -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 = "*"
documentation/ref-manual/qa-checks.rst +15 -5
@@ -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"
documentation/ref-manual/tasks.rst +15 -5
@@ -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"
PATCH 3/10 dev-manual: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- 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(-)
documentation/dev-manual/bblock.rst +3 -1
@@ -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}"
documentation/dev-manual/bmaptool.rst +3 -1
@@ -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"
documentation/dev-manual/build-quality.rst +6 -2
@@ -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"
documentation/dev-manual/building.rst +33 -11
109 lines not on this page · raw message
documentation/dev-manual/creating-fragments.rst +3 -3
@@ -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"
documentation/dev-manual/custom-distribution.rst +3 -1
@@ -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"
documentation/dev-manual/customizing-images.rst +24 -8
@@ -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 = ""
documentation/dev-manual/debugging.rst +30 -10
@@ -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"
documentation/dev-manual/device-manager.rst +9 -3
@@ -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"
documentation/dev-manual/devtool.rst +6 -2
@@ -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}'"
documentation/dev-manual/disk-space.rst +3 -1
@@ -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"
documentation/dev-manual/error-reporting-tool.rst +9 -3
@@ -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"
documentation/dev-manual/external-scm.rst +15 -5
@@ -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"
documentation/dev-manual/gobject-introspection.rst +9 -3
@@ -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"
documentation/dev-manual/hashequivserver.rst +9 -3
@@ -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"
documentation/dev-manual/init-manager.rst +12 -4
@@ -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 = ""
documentation/dev-manual/layers.rst +42 -14
138 lines not on this page · raw message
documentation/dev-manual/libraries.rst +9 -3
@@ -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"
documentation/dev-manual/licenses.rst +45 -15
146 lines not on this page · raw message
documentation/dev-manual/limiting-resources.rst +3 -1
@@ -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"
documentation/dev-manual/multiconfig.rst +30 -10
@@ -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
documentation/dev-manual/new-machine.rst +3 -1
@@ -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)'
documentation/dev-manual/new-recipe.rst +120 -40
392 lines not on this page · raw message
documentation/dev-manual/packages.rst +33 -11
106 lines not on this page · raw message
documentation/dev-manual/poky-manual-setup.rst +3 -1
@@ -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"
documentation/dev-manual/prebuilt-libraries.rst +9 -3
@@ -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"
documentation/dev-manual/qemu.rst +3 -1
@@ -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"
documentation/dev-manual/quilt.rst +3 -1
@@ -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"
documentation/dev-manual/sbom.rst +3 -1
@@ -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"
documentation/dev-manual/speeding-up-build.rst +3 -1
@@ -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 = ""
documentation/dev-manual/sstate-mirrors-setup.rst +12 -4
@@ -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"
documentation/dev-manual/temporary-source-code.rst +6 -2
@@ -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}"
documentation/dev-manual/upgrading-recipes.rst +9 -3
@@ -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"
documentation/dev-manual/wayland.rst +6 -2
@@ -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"
documentation/dev-manual/x32-psabi.rst +3 -1
@@ -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"
PATCH 4/10 migration-guides: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- .../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(-)
documentation/migration-guides/migration-1.3.rst +6 -2
@@ -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}"
documentation/migration-guides/migration-1.6.rst +9 -3
@@ -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"
documentation/migration-guides/migration-1.7.rst +3 -1
@@ -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"
documentation/migration-guides/migration-1.8.rst +9 -3
@@ -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"
documentation/migration-guides/migration-2.0.rst +6 -2
@@ -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"
documentation/migration-guides/migration-2.1.rst +3 -1
@@ -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 = ""
documentation/migration-guides/migration-2.2.rst +8 -3
@@ -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}"
documentation/migration-guides/migration-2.3.rst +9 -3
@@ -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 = ""
documentation/migration-guides/migration-2.5.rst +3 -1
@@ -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"
documentation/migration-guides/migration-2.6.rst +9 -3
@@ -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"
documentation/migration-guides/migration-3.0.rst +3 -1
@@ -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
documentation/migration-guides/migration-3.1.rst +9 -3
@@ -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"
documentation/migration-guides/migration-3.2.rst +6 -2
@@ -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
documentation/migration-guides/migration-3.3.rst +6 -2
@@ -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"
documentation/migration-guides/migration-3.4.rst +12 -4
@@ -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"
documentation/migration-guides/migration-4.0.rst +9 -3
@@ -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"
documentation/migration-guides/migration-4.1.rst +6 -2
@@ -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"
documentation/migration-guides/migration-4.2.rst +9 -3
@@ -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 = ""
documentation/migration-guides/migration-5.1.rst +9 -3
@@ -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}"
documentation/migration-guides/migration-5.2.rst +18 -6
@@ -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"
documentation/migration-guides/migration-5.3.rst +27 -9
@@ -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"
documentation/migration-guides/migration-6.0.rst +33 -11
103 lines not on this page · raw message
documentation/migration-guides/migration-6.1.rst +9 -3
@@ -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"
documentation/migration-guides/release-notes-4.0.rst +3 -1
@@ -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"
documentation/migration-guides/release-notes-4.3.rst +3 -1
@@ -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"
documentation/migration-guides/release-notes-5.0.rst +3 -1
@@ -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)}
documentation/migration-guides/release-notes-5.3.rst +6 -2
@@ -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"
PATCH 7/10 overview-manual: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- documentation/overview-manual/concepts.rst | 68 ++++++++++++++++------ 1 file changed, 51 insertions(+), 17 deletions(-)
documentation/overview-manual/concepts.rst +51 -17
@@ -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 () { ...
PATCH 8/10 security-manual: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- .../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(-)
documentation/security-manual/read-only-rootfs.rst +6 -2
@@ -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"
documentation/security-manual/securing-images.rst +6 -2
@@ -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"
documentation/security-manual/sstate-signing.rst +12 -4
@@ -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"
documentation/security-manual/vulnerabilities.rst +24 -8
@@ -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"
PATCH 9/10 sdk-manual: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- .../sdk-manual/appendix-customizing-standard.rst | 4 +++- .../sdk-manual/appendix-customizing.rst | 16 ++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-)
documentation/sdk-manual/appendix-customizing-standard.rst +3 -1
@@ -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"
documentation/sdk-manual/appendix-customizing.rst +8 -8
@@ -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"
PATCH 10/10 docs-wide: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- 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(-)
documentation/brief-yoctoprojectqs/index.rst +3 -1
@@ -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"
documentation/bsp-manual/bsp.rst +21 -7
@@ -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"
documentation/contributor-guide/recipe-style-guide.rst +18 -6
@@ -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"
documentation/profile-manual/intro.rst +12 -4
@@ -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'
Hi Trevor,
Quoted 1 line · Trevor Woerner
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,
Signature · 1 line
Paul Barker
Hi Trevor,
Quoted 9 lines · Trevor Woerner via lists.yoctoproject.org
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 ;)
[...]
Quoted 4 lines
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
Hi,
Quoted 23 lines · Quentin Schulz via lists.yoctoproject.org
Hi Trevor,
Quoted 9 lines · Trevor Woerner via lists.yoctoproject.org
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 ;)
[...]
Quoted 4 lines
Depends on
----------"docs: state the language of nine literal blocks explicitly", sent
Quoted 7 lines
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
Quoted 18 lines · Antonin Godard
Hi,
Quoted 15 lines · Quentin Schulz via lists.yoctoproject.org
Hi Trevor,
Quoted 9 lines · Trevor Woerner via lists.yoctoproject.org
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".
Quoted 19 lines
Quoted 8 lines
[...]
Quoted 4 lines
Depends on
----------"docs: state the language of nine literal blocks explicitly", sent
Quoted 7 lines
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?
Quoted 6 lines
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).
Quoted 7 lines · Paul Barker
Hi Trevor,
Quoted 1 line · Trevor Woerner
Please do not apply this yet
It's easy to miss this when looking at the individual patches, you should use
RFCin 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.
Quoted 5 lines
Best regards,
Signature · 1 line
Paul Barker
Quoted 28 lines · Antonin Godard
Hi,
Quoted 25 lines · Quentin Schulz via lists.yoctoproject.org
Hi Trevor,
Quoted 9 lines · Trevor Woerner via lists.yoctoproject.org
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 ;)
[...]
Quoted 4 lines
Depends on
----------"docs: state the language of nine literal blocks explicitly", sent
Link to the ML please to make maintainers and reviewers job easier.
Quoted 9 lines
Quoted 5 lines
[...]
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.
Quoted 4 lines
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.
Quoted 1 line
This is maybe a more conservative approach but at least it doesn't
leave room
Quoted 2 lines
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
Quoted 25 lines · Trevor Woerner via lists.yoctoproject.org
Quoted 24 lines · Antonin Godard
Hi,
Quoted 10 lines · Quentin Schulz via lists.yoctoproject.org
Hi Trevor,
On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:[...]>>> [...]
Quoted 4 lines
Depends on
----------"docs: state the language of nine literal blocks explicitly", sent
Quoted 7 lines
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?
Quoted 9 lines
Quoted 6 lines
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.
Quoted 1 line
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
Quoted 6 lines
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?
Quoted 4 lines
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.
Quoted 5 lines
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
Hi,
Quoted 3 lines · Quentin Schulz via lists.yoctoproject.org
On 8/26/26 3:09 PM, Antonin Godard wrote:
[...]
Quoted 20 lines
Quoted 7 lines
Quoted 3 lines
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
Quoted 8 lines
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).
Quoted 16 lines
Quoted 4 lines
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.
Quoted 1 line
This is maybe a more conservative approach but at least it doesn't
leave room
Quoted 2 lines
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
Quoted 8 lines
highlight_language= "please_specify_the_highlight_language_for_this_block"in
conf.pyand 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:
documentation/tools/host_packages_scripts/pip3_docs.sh +1 -1
@@ -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?
Quoted 4 lines
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.
Quoted 3 lines · your other email
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
Quoted 30 lines · Antonin Godard
Hi,
Quoted 3 lines · Quentin Schulz via lists.yoctoproject.org
On 8/26/26 3:09 PM, Antonin Godard wrote:
[...]
Quoted 23 lines
Quoted 7 lines
Quoted 3 lines
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.
Quoted 8 lines
Quoted 5 lines
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?
Quoted 40 lines
version of pygments, so backporting patches that use the bitbake lexer won't be an issue (from an Autobuilder perspective).
Quoted 16 lines
Quoted 4 lines
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.
Quoted 1 line
This is maybe a more conservative approach but at least it doesn't
leave room
Quoted 2 lines
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
Quoted 8 lines
highlight_language= "please_specify_the_highlight_language_for_this_block"in
conf.pyand 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:
documentation/tools/host_packages_scripts/pip3_docs.sh +1
-1@@ -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'
Quoted 2 lines
And backport it to Wrynose/Scarthgap?
/me shrugs
Quoted 7 lines
Quoted 4 lines
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.
Quoted 9 lines
Quoted 3 lines · your other email
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-examplesThis is interesting! If it behaves the same way with whatever
highlight_languageyou set inconf.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
Quoted 32 lines · Quentin Schulz
Quoted 29 lines · Trevor Woerner via lists.yoctoproject.org
Quoted 28 lines · Antonin Godard
Hi,
Quoted 10 lines · Quentin Schulz via lists.yoctoproject.org
Hi Trevor,
On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:[...]>>> [...]
Quoted 4 lines
Depends on
----------"docs: state the language of nine literal blocks explicitly", sent
Quoted 7 lines
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.
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
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.
Quoted 12 lines
Quoted 1 line
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-examplesQuoted 6 lines
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.
Quoted 6 lines
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.
Quoted 5 lines
Quoted 4 lines
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.
Quoted 7 lines
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.
Quoted 11 lines
Quoted 5 lines
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
Quoted 36 lines · Quentin Schulz via lists.yoctoproject.org
Quoted 33 lines · Antonin Godard
Hi,
Quoted 3 lines · Quentin Schulz via lists.yoctoproject.org
On 8/26/26 3:09 PM, Antonin Godard wrote:
[...]
Quoted 26 lines
Quoted 7 lines
Quoted 3 lines
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.
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines
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.
[...]
Quoted 15 lines
Quoted 3 lines
This is interesting! If it behaves the same way with whatever
highlight_languageyou set inconf.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()insphinx/highlighting.pyhas 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).
Quoted 5 lines
"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
Hi,
On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
[...]
Quoted 6 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.
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
Quoted 7 lines · Antonin Godard
Hi,
On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
[...]Quoted 3 lines
Not included
------------
Quoted 6 lines
Quoted 3 lines
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.
Hi,
Quoted 18 lines · Trevor Woerner
Quoted 7 lines · Antonin Godard
Hi,
On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
[...]Quoted 3 lines
Not included
------------Quoted 6 lines
Quoted 3 lines
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:
Quoted 6 lines
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.
Quoted 9 lines
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
Hi Antonin,
Quoted 28 lines · Antonin Godard via lists.yoctoproject.org
Hi,
Quoted 18 lines · Trevor Woerner
Quoted 7 lines · Antonin Godard
Hi,
On Wed Aug 26, 2026 at 3:34 AM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
[...]Quoted 3 lines
Not included
------------Quoted 6 lines
Quoted 3 lines
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:
Quoted 6 lines
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.
Quoted 5 lines
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
Hi Trevor,
Quoted 103 lines · Trevor Woerner
Quoted 32 lines · Quentin Schulz
Quoted 29 lines · Trevor Woerner via lists.yoctoproject.org
Quoted 28 lines · Antonin Godard
Hi,
Quoted 10 lines · Quentin Schulz via lists.yoctoproject.org
Hi Trevor,
On 8/26/26 3:34 AM, Trevor Woerner via lists.yoctoproject.org wrote:[...]>>> [...]
Quoted 4 lines
Depends on
----------"docs: state the language of nine literal blocks explicitly", sent
Quoted 7 lines
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.
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
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-blockPersonally 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 0Setting 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".
Quoted 6 lines
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.
Quoted 19 lines
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.
Quoted 12 lines
Quoted 1 line
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-examplesQuoted 6 lines
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.
Quoted 9 lines
Quoted 6 lines
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 :)
Quoted 10 lines
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%
Quoted 9 lines
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 aMakefile, 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.
Quoted 9 lines
Quoted 9 lines
Quoted 4 lines
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
Quoted 9 lines
Quoted 3 lines
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.
Quoted 11 lines
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 :)
Quoted 18 lines
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.
Quoted 11 lines
Quoted 5 lines
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
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
Quoted 15 lines · Antonin Godard
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"inconf.py.- remove file-wide lexer enforcing (.. highlight:: directive at the top of the file) (in a separate patch)
Quoted 8 lines
- 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.
Quoted 9 lines
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.pyfile at the moment (+ some possible additional code-blocks).Thanks both for sharing your thoughts on this!
Antonin
Quoted 15 lines · Antonin Godard
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"inconf.py.- remove file-wide lexer enforcing (.. highlight:: directive at the top of the file) (in a separate patch)
Quoted 6 lines
- 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.
Quoted 12 lines
- 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.pyfile at the moment (+ some possible additional code-blocks).Thanks both for sharing your thoughts on this!
Antonin
Quoted 27 lines · Trevor Woerner
Quoted 15 lines · Antonin Godard
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"inconf.py.- remove file-wide lexer enforcing (.. highlight:: directive at the top of the file) (in a separate patch)
Quoted 6 lines
- 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.
Quoted 5 lines
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.
Quoted 6 lines
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 pygmentsAnd 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.
Quoted 29 lines
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 correctlyThe 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.
Quoted 5 lines
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
Quoted 42 lines · Antonin Godard
Quoted 27 lines · Trevor Woerner
Quoted 15 lines · Antonin Godard
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"inconf.py.- remove file-wide lexer enforcing (.. highlight:: directive at the top of the file) (in a separate patch)
Quoted 6 lines
- 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.
Quoted 5 lines
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.Quoted 4 lines
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
Quoted 6 lines
Quoted 2 lines
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.pywill 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, becausehighlight_languageis 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.
Quoted 38 lines
Note: I think this change is big enough that I don't consider it candidate for backport on stable branches.
Quoted 29 lines
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 correctlyThe 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.
Quoted 5 lines
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.
Quoted 4 lines
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.
Quoted 1 line
Antonin
Quoted 50 lines · Trevor Woerner
Quoted 42 lines · Antonin Godard
Quoted 27 lines · Trevor Woerner
Quoted 15 lines · Antonin Godard
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"inconf.py.- remove file-wide lexer enforcing (.. highlight:: directive at the top of the file) (in a separate patch)
Quoted 6 lines
- 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.
Quoted 5 lines
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.Quoted 4 lines
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 pygmentsQuoted 6 lines
Quoted 2 lines
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.pywill 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, becausehighlight_languageis still "default" on these.
Quoted 7 lines
If we set:
highlight_language= "bitbake"in
conf.pyright 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.
Quoted 48 lines
Quoted 38 lines
Note: I think this change is big enough that I don't consider it candidate for backport on stable branches.
Quoted 29 lines
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 correctlyThe 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.
Quoted 5 lines
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.
Quoted 4 lines
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.
Quoted 4 lines
If anything not adding the shim *is* where the complexity lies. Once you accept the default
conf.pypatch 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