From patchwork Wed Aug 26 01:34:46 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96338 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id BA09CC61DB9 for ; Wed, 26 Aug 2026 01:35:21 +0000 (UTC) Received: from mail-qk1-f175.google.com (mail-qk1-f175.google.com [209.85.222.175]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.3462.1787708111832077245 for ; Tue, 25 Aug 2026 18:35:12 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=bLFVHN/v; spf=pass (domain: gmail.com, ip: 209.85.222.175, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f175.google.com with SMTP id af79cd13be357-92ed19f4d60so29711885a.0 for ; Tue, 25 Aug 2026 18:35:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708111; x=1788312911; darn=lists.yoctoproject.org; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:to:from:from:to:cc:subject:date :message-id:reply-to:content-type; bh=eR5JHgIOaC6B/Ek7HgVciHB1oRMXtDg90Dw3zDiV754=; b=bLFVHN/vtTs3tolUsQoKn2s4PdK+KK6p/4uXqME8Louo9tGesyC6+00BpD2nGN73XT fiIvRm2YUIh3m84BOxKlMDny7R1PhEhf3ff8LXr+zxqvY+ppja+vmC//3rBIWMoTmNm0 Kadztl2veXh/RwEKceW0TWR5kRoMcoxRNVpKKOi11xura1+ghRt7SBbsRvc58Kr3Uh0W 6KbSTf/dmElOR+g0nBa3bCWxLnc50rG/r1L2+048g1zgQDnD8n1M59MZITQdJLq4HO3L j54lP60zEIgMZXflVB4oam3ZXpXKg6rFZYiUTcNxMQSIzUf9chU9Sk8DdDcGnz3GLw2R tzdA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708111; x=1788312911; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=eR5JHgIOaC6B/Ek7HgVciHB1oRMXtDg90Dw3zDiV754=; b=Ew12Kmoe9d/BvjS1zn+B3mdgAj1pfCSdpG8fbVFI4huYNfVmBDsf8K57y0d0f0NlUT ql+Px4RF5rwGNvagcSbVtU9OW/k0ksz031NqihNTwQeRw+/BxaWev3rViHD9czSLdlki XNr+rlw52WkDImeYzS5VlYq/jyCqCqwvrjUfgqbbAOoQfUiIeOSzSzYXejcD93QmTCKu JUHsNV495Ft0l5h9dwuwuKW53MgkKftzSD6KMw31cvE8fBQDjZidRZiNHumSmgp0xT2X p/BAY/fyoh/cx+ITjp52/0DSFrqpnTgr+PQY2NE3mMa3GdXdXSxS5J0pPsxJuGa2kSAN eHag== X-Gm-Message-State: AFuF++nO5J0K+/tqjvFER/h4cRZCIEtS2qpcmDCrxv8SVsastoI1jvCn R6FLSqiXFbNmAfkEdT+pv1F28+Q8if8sDZKWbfl9gqhD0O+vwa3Cm8oyyJlLXjX9 X-Gm-Gg: AR+sD12gNADwjZGzGS9dl938SaZpjikRXL/PQX8WuQBtXBQwU2SU8Kke1SQ1g8d8Vh7 zdCeLt2v1oDX4K3TOIdrxX9wzuNoFV3BlAM+bYvfkzXo8SsXjf/rIefjQTJZG4fL0Eh6ElsGCKG qHzmXbpqN7h4cgwsNCVtbIogx8BaUzEmosW+o62iBvWVquzeSoR7piFpvhHy0CgPPRrFXAM7rp0 SNrXZ3U5noM5oavwZ+0dLmfMH2DhP5AHwd62xVKJDOf2GY9uJkszNJ5nUyu5mmjVgM20drVDzjE 2rVy8iqNXatqJFgtMy8G+HEI3g/LFnTeq8AJcs6sS24HAwLDhyZMzQ9jniR2atSVq5DUmO2KOf+ kidm6lIxfeJ7Oanmi5qPdaxQGsjU6jsf16bADjEBe46TgdHVaWppFVtbMe0x1c+W9NpvIa5tKl7 cjkwLnzBWXpx7blijV1DmQ66qrOBniu8L/m2UH8PanfahE2m1hSYp64iesgZAIsVcWg+hIAFo/2 JNznPsLMyoRfFp5f+MU9AAxZqqdan0= X-Received: by 2002:ae9:f703:0:b0:92e:57ea:8c8b with SMTP id af79cd13be357-9376f0ddbacmr916030685a.0.1787708108216; Tue, 25 Aug 2026 18:35:08 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.06 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:06 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 01/10] ref-manual/variables.rst: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:46 -0400 Message-ID: <20260826013502.2674000-2-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:21 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10346 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 418 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. The variables glossary is the densest concentration of BitBake syntax in the documentation, and nearly every entry showing how to set a variable was affected. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- documentation/ref-manual/variables.rst | 1635 ++++++++++++++++++------ 1 file changed, 1226 insertions(+), 409 deletions(-) diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 646a77982646..61a4c6faca20 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -31,7 +31,9 @@ system and gives an overview of their function and contents. ABI extensions are set in the machine include files. For example, the ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the - following extension:: + following extension: + + .. code-block:: bitbake ABIEXTENSION = "eabi" @@ -43,7 +45,9 @@ system and gives an overview of their function and contents. requirement on the existence of the package. Like all package-controlling variables, you must always use them in - conjunction with a package name override, as in:: + conjunction with a package name override, as in: + + .. code-block:: bitbake ALLOW_EMPTY:${PN} = "1" ALLOW_EMPTY:${PN}-dev = "1" @@ -58,7 +62,9 @@ system and gives an overview of their function and contents. To use the variable, list out the package's commands that are also provided by another package. For example, if the ``busybox`` package - has four such commands, you identify them as follows:: + has four such commands, you identify them as follows: + + .. code-block:: bitbake ALTERNATIVE:busybox = "sh sed test bracket" @@ -71,7 +77,9 @@ system and gives an overview of their function and contents. locations. For example, if the ``bracket`` command provided by the ``busybox`` package is duplicated through another package, you must use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual - location:: + location: + + .. code-block:: bitbake ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" @@ -92,7 +100,9 @@ system and gives an overview of their function and contents. default regardless of the command name or package, a default for specific duplicated commands regardless of the package, or a default for specific commands tied to particular packages. Here are the - available syntax forms:: + available syntax forms: + + .. code-block:: bitbake ALTERNATIVE_PRIORITY = "priority" ALTERNATIVE_PRIORITY[name] = "priority" @@ -108,7 +118,9 @@ system and gives an overview of their function and contents. default location for all duplicated commands regardless of the command name or package, a default for specific duplicated commands regardless of the package, or a default for specific commands tied to - particular packages. Here are the available syntax forms:: + particular packages. Here are the available syntax forms: + + .. code-block:: bitbake ALTERNATIVE_TARGET = "target" ALTERNATIVE_TARGET[name] = "target" @@ -156,7 +168,9 @@ system and gives an overview of their function and contents. determines the type of information used to create a released archive. You can use this variable to create archives of patched source, original source, configured source, and so forth by employing the - following variable flags (varflags):: + following variable flags (varflags): + + .. code-block:: bitbake ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. @@ -196,7 +210,9 @@ system and gives an overview of their function and contents. shlibname:packagename[_version] Here is an example that adds a shared library named ``libEGL.so.1`` - as being provided by the ``libegl-implementation`` package:: + as being provided by the ``libegl-implementation`` package: + + .. code-block:: bitbake ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" @@ -217,14 +233,18 @@ system and gives an overview of their function and contents. :term:`AUTOREV` When :term:`SRCREV` is set to the value of this variable, it specifies to - use the latest source revision in the repository. Here is an example:: + use the latest source revision in the repository. Here is an example: + + .. code-block:: bitbake SRCREV = "${AUTOREV}" If you use the previous statement to retrieve the latest version of software, you need to make sure :term:`PV` contains the ``+`` sign so :term:`bitbake` includes source control information to :term:`PKGV` when - packaging the recipe. For example:: + packaging the recipe. For example: + + .. code-block:: bitbake PV = "6.10.y+git" @@ -259,7 +279,9 @@ system and gives an overview of their function and contents. Azure Storage Shared Access Signature, when using the :ref:`Azure Storage fetcher (az://) ` 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=&sig="" @@ -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 ` 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 ` 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 ` 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 " @@ -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 `:: + Here is an example from the :oe_layerindex:`Berkeley DB recipe `: + + .. 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`:: + an example from the :oe_layerindex:`Python3 recipe`: + + .. 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 `. 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 `. 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 - `:: + `: + + .. 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 ` 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 `__ 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 ` - 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 ` - 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 ` 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: ?= "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 ` 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 `__ option of QEMU. For example, this variable can be set as follows to emulate U-Boot for the :oecore_path:`qemuarm64 ` - 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 " 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 " @@ -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 ` class to which the SDK is deployed. The :ref:`populate_sdk_base ` - 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 ` 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 ` 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 ` - 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 ` 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 ` 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 ` 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 `. 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 += "::" @@ -9260,7 +9860,9 @@ system and gives an overview of their function and contents. rebuilding the ````. If it does not exist, BitBake will build the ```` and the sstate cache will be used next time. - Example:: + Example: + + .. code-block:: bitbake SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0" @@ -9286,7 +9888,9 @@ system and gives an overview of their function and contents. :term:`SIGGEN_LOCKEDSIGS_TYPES` Allowed overrides for :term:`SIGGEN_LOCKEDSIGS`. This is mainly used for architecture specific locks. A common value for - :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``:: + :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``: + + .. code-block:: bitbake SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" @@ -9312,7 +9916,9 @@ system and gives an overview of their function and contents. To enable file removal, set the variable to "1" in your ``conf/local.conf`` configuration file in your: - :term:`Build Directory`:: + :term:`Build Directory`: + + .. code-block:: bitbake SKIP_FILEDEPS = "1" @@ -9324,7 +9930,9 @@ system and gives an overview of their function and contents. To prevent a recipe from being built, use the :term:`SKIP_RECIPE` variable in your ``local.conf`` file or distribution configuration. - Here is an example which prevents ``myrecipe`` from being built:: + Here is an example which prevents ``myrecipe`` from being built: + + .. code-block:: bitbake SKIP_RECIPE[myrecipe] = "Not supported by our organization." @@ -9369,7 +9977,9 @@ system and gives an overview of their function and contents. :oe_git:`meta/lib/oe/reproducible.py `. If a recipe wishes to override the default behavior, it should set its - own :term:`SOURCE_DATE_EPOCH` value:: + own :term:`SOURCE_DATE_EPOCH` value: + + .. code-block:: bitbake SOURCE_DATE_EPOCH = "1613559011" @@ -9398,7 +10008,9 @@ system and gives an overview of their function and contents. To use this variable, you must globally inherit the :ref:`ref-classes-own-mirrors` class and then provide - the URL to your mirrors. Here is the general syntax:: + the URL to your mirrors. Here is the general syntax: + + .. code-block:: bitbake INHERIT += "own-mirrors" SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" @@ -9428,7 +10040,9 @@ system and gives an overview of their function and contents. Another method to configure the username and password is from the URL in :term:`SOURCE_MIRROR_URL` directly, with the ``user`` and ``pswd`` - parameters:: + parameters: + + .. code-block:: bitbake SOURCE_MIRROR_URL = "http://example.com/my_source_mirror;user=;pswd=" @@ -9456,18 +10070,24 @@ system and gives an overview of their function and contents. This variable can be set in two ways: - - For the entire recipe:: + - For the entire recipe: + + .. code-block:: bitbake SPDX_CONCLUDED_LICENSE = "MIT & Apache-2.0" - - For an individual package produced by the recipe:: + - For an individual package produced by the recipe: + + .. code-block:: bitbake SPDX_CONCLUDED_LICENSE:${PN} = "MIT & Apache-2.0" :term:`SPDX_CUSTOM_ANNOTATION_VARS` This option allows to associate `SPDX annotations `__ to a recipe, - using the values of variables in the recipe:: + using the values of variables in the recipe: + + .. code-block:: bitbake ANNOTATION1 = "First annotation for recipe" ANNOTATION2 = "Second annotation for recipe" @@ -9533,14 +10153,18 @@ system and gives an overview of their function and contents. so the sub-variable names follow directly from ``SPDX_IMAGE_SUPPLIER``. - Example (set in the image recipe or in a :term:`configuration file`):: + Example (set in the image recipe or in a :term:`configuration file`): + + .. code-block:: bitbake SPDX_IMAGE_SUPPLIER = "SPDX_IMAGE_SUPPLIER" SPDX_IMAGE_SUPPLIER_name = "Acme Corp" SPDX_IMAGE_SUPPLIER_type = "organization" Alternatively, you can use any other prefix name, which is useful for - sharing an agent definition across multiple supplier variables:: + sharing an agent definition across multiple supplier variables: + + .. code-block:: bitbake MY_COMPANY_name = "Acme Corp" MY_COMPANY_type = "organization" @@ -9566,7 +10190,9 @@ system and gives an overview of their function and contents. Enabling this variable will result in non-reproducible SPDX output, because the build invocation identity changes with every run. - Enable as follows:: + Enable as follows: + + .. code-block:: bitbake SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1" @@ -9586,7 +10212,9 @@ system and gives an overview of their function and contents. This enables an external tool to use the SPDX information to disregard vulnerabilities that are not compiled in the packages. - Enable this option as follows:: + Enable this option as follows: + + .. code-block:: bitbake SPDX_INCLUDE_COMPILED_SOURCES = "1" @@ -9615,7 +10243,9 @@ system and gives an overview of their function and contents. This variable only has effect when using the SPDX 3.0 output format (see :ref:`ref-classes-create-spdx`). - Enable this option as follows:: + Enable this option as follows: + + .. code-block:: bitbake SPDX_INCLUDE_KERNEL_CONFIG = "1" @@ -9636,7 +10266,9 @@ system and gives an overview of their function and contents. This variable only has effect when using the SPDX 3.0 output format (see :ref:`ref-classes-create-spdx`). - Enable this option as follows:: + Enable this option as follows: + + .. code-block:: bitbake SPDX_INCLUDE_PACKAGECONFIG = "1" @@ -9654,7 +10286,9 @@ system and gives an overview of their function and contents. ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also modified to include references to such source file descriptions. - Enable this option as follows:: + Enable this option as follows: + + .. code-block:: bitbake SPDX_INCLUDE_SOURCES = "1" @@ -9697,7 +10331,9 @@ system and gives an overview of their function and contents. - ``SPDX_INVOKED_BY_name``: display name of the invoking agent - ``SPDX_INVOKED_BY_type``: agent type, such as ``software`` for a CI system - Example (CI pipeline invoking the build):: + Example (CI pipeline invoking the build): + + .. code-block:: bitbake SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1" SPDX_INVOKED_BY = "SPDX_INVOKED_BY" @@ -9752,7 +10388,9 @@ system and gives an overview of their function and contents. - ``SPDX_ON_BEHALF_OF_name``: display name of the commissioning agent - ``SPDX_ON_BEHALF_OF_type``: agent type, such as ``organization`` - Example (CI system building on behalf of a customer organization):: + Example (CI system building on behalf of a customer organization): + + .. code-block:: bitbake SPDX_INCLUDE_BITBAKE_PARENT_BUILD = "1" SPDX_INVOKED_BY = "SPDX_INVOKED_BY" @@ -9778,7 +10416,9 @@ system and gives an overview of their function and contents. Typically set in a distro :term:`configuration file` to apply globally to all packages, or in a specific software recipe (or a ``.bbappend``) to apply only to packages of that recipe. Recipe-level overrides - (``SPDX_PACKAGE_SUPPLIER:pn-``) are also supported:: + (``SPDX_PACKAGE_SUPPLIER:pn-``) are also supported: + + .. code-block:: bitbake SPDX_PACKAGE_SUPPLIER = "SPDX_PACKAGE_SUPPLIER" SPDX_PACKAGE_SUPPLIER_name = "Acme Corp" @@ -9809,7 +10449,9 @@ system and gives an overview of their function and contents. :term:`SPDX_PRETTY` This option makes the SPDX output more human-readable, using identation and newlines, instead of the default output in a - single line:: + single line: + + .. code-block:: bitbake SPDX_PRETTY = "1" @@ -9938,13 +10580,17 @@ system and gives an overview of their function and contents. └── psplash_%.bbappend And here are the contents of the ``psplash_%.bbappend`` file in - this example:: + this example: + + .. code-block:: bitbake SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default" FILESEXTRAPATHS:prepend := "${THISDIR}/files:" You could even add specific configuration options for ``psplash``, - for example:: + for example: + + .. code-block:: bitbake EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen" @@ -10022,7 +10668,9 @@ system and gives an overview of their function and contents. The :term:`SRCPV` variable used to be defined in the ``meta/conf/bitbake.conf`` configuration file in - :term:`OpenEmbedded-Core (OE-Core)` as follows:: + :term:`OpenEmbedded-Core (OE-Core)` as follows: + + .. code-block:: bitbake SRCPV = "${@bb.fetch2.get_srcrev(d)}" @@ -10052,13 +10700,17 @@ system and gives an overview of their function and contents. A list of tasks that are typically not relevant (and therefore skipped) when building using the :ref:`ref-classes-externalsrc` class. The default value as set in that class file is the set of tasks - that are rarely needed when using external source:: + that are rarely needed when using external source: + + .. code-block:: bitbake SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch" The notable exception is when processing external kernel source as defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for - aesthetics):: + aesthetics): + + .. code-block:: bitbake SRCTREECOVEREDTASKS += "\ do_validate_branches \ @@ -10123,7 +10775,9 @@ system and gives an overview of their function and contents. you point to can also be from builds on other machines. The Yocto Project actually shares the cache data objects built by its - autobuilder:: + autobuilder: + + .. code-block:: bitbake SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH" @@ -10183,11 +10837,15 @@ system and gives an overview of their function and contents. size and time costs of the artefact are similar to just running the tasks. This generally only applies to end artefact output like images. - The syntax to disable it for one task is:: + The syntax to disable it for one task is: + + .. code-block:: bitbake SSTATE_SKIP_CREATION:task-image-complete = "1" - The syntax to disable it for the whole recipe is:: + The syntax to disable it for the whole recipe is: + + .. code-block:: bitbake SSTATE_SKIP_CREATION = "1" @@ -10402,7 +11060,9 @@ system and gives an overview of their function and contents. to an actual stamp file is constructed by evaluating this string and then appending additional information. Currently, the default assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf`` - file is:: + file is: + + .. code-block:: bitbake STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" @@ -10446,7 +11106,9 @@ system and gives an overview of their function and contents. :term:`SYSLINUX_DEFAULT_CONSOLE` Specifies the kernel boot default console. If you want to use a console other than the default, set this variable in your recipe as - follows where "X" is the console number you want to use:: + follows where "X" is the console number you want to use: + + .. code-block:: bitbake SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" @@ -10465,7 +11127,9 @@ system and gives an overview of their function and contents. Specifies the alternate serial port or turns it off. To turn off serial, set this variable to an empty string in your recipe. The variable's default value is set in the - :ref:`ref-classes-syslinux` class as follows:: + :ref:`ref-classes-syslinux` class as follows: + + .. code-block:: bitbake SYSLINUX_SERIAL ?= "0 115200" @@ -10474,7 +11138,9 @@ system and gives an overview of their function and contents. :term:`SYSLINUX_SERIAL_TTY` Specifies the alternate console=tty... kernel boot argument. The variable's default value is set in the :ref:`ref-classes-syslinux` - class as follows:: + class as follows: + + .. code-block:: bitbake SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" @@ -10497,7 +11163,9 @@ system and gives an overview of their function and contents. :term:`SYSROOT_DIRS` Directories that are staged into the sysroot by the :ref:`ref-tasks-populate_sysroot` task. By - default, the following directories are staged:: + default, the following directories are staged: + + .. code-block:: bitbake SYSROOT_DIRS = " \ ${includedir} \ @@ -10526,14 +11194,18 @@ system and gives an overview of their function and contents. ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So, the linking process will fail. - To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`:: + To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`: + + .. code-block:: bitbake SYSROOT_DIRS:append = " /opt/lib" .. note:: Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail because the linker does not know that location, since :term:`TARGET_LDFLAGS` - doesn't contain it (if your recipe is for the target). Therefore, so you should add:: + doesn't contain it (if your recipe is for the target). Therefore, so you should add: + + .. code-block:: bitbake TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib" @@ -10542,7 +11214,9 @@ system and gives an overview of their function and contents. :ref:`ref-tasks-populate_sysroot` task. You can use this variable to exclude certain subdirectories of directories listed in :term:`SYSROOT_DIRS` from - staging. By default, the following directories are not staged:: + staging. By default, the following directories are not staged: + + .. code-block:: bitbake SYSROOT_DIRS_IGNORE = " \ ${mandir} \ @@ -10565,7 +11239,9 @@ system and gives an overview of their function and contents. :ref:`ref-tasks-populate_sysroot` task for ``-native`` recipes, in addition to those specified in :term:`SYSROOT_DIRS`. By default, the following - extra directories are staged:: + extra directories are staged: + + .. code-block:: bitbake SYSROOT_DIRS_NATIVE = " \ ${bindir} \ @@ -10594,7 +11270,9 @@ system and gives an overview of their function and contents. :term:`SYSTEMD_SERVICE` should start automatically or not. By default, the service is enabled to automatically start at boot time. The default setting is in the - :ref:`ref-classes-systemd` class as follows:: + :ref:`ref-classes-systemd` class as follows: + + .. code-block:: bitbake SYSTEMD_AUTO_ENABLE ??= "enable" @@ -10605,7 +11283,9 @@ system and gives an overview of their function and contents. "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the configuration file that should be used. By default, the :ref:`ref-classes-systemd-boot` class sets the - :term:`SYSTEMD_BOOT_CFG` as follows:: + :term:`SYSTEMD_BOOT_CFG` as follows: + + .. code-block:: bitbake SYSTEMD_BOOT_CFG ?= "${S}/loader.conf" @@ -10617,7 +11297,9 @@ system and gives an overview of their function and contents. "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a list of entry files (``*.conf``) to install that contain one boot entry per file. By default, the :ref:`ref-classes-systemd-boot` class - sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows:: + sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows: + + .. code-block:: bitbake SYSTEMD_BOOT_ENTRIES ?= "" @@ -10629,7 +11311,9 @@ system and gives an overview of their function and contents. "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the boot menu timeout in seconds. By default, the :ref:`ref-classes-systemd-boot` class sets the - :term:`SYSTEMD_BOOT_TIMEOUT` as follows:: + :term:`SYSTEMD_BOOT_TIMEOUT` as follows: + + .. code-block:: bitbake SYSTEMD_BOOT_TIMEOUT ?= "10" @@ -10649,7 +11333,9 @@ system and gives an overview of their function and contents. For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb ` - recipe:: + recipe: + + .. code-block:: bitbake SYSTEMD_DEFAULT_TARGET = "graphical.target" @@ -10658,7 +11344,9 @@ system and gives an overview of their function and contents. this variable locates the systemd unit files when they are not found in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES` variable is set such that the systemd unit files are assumed to - reside in the recipes main package:: + reside in the recipes main package: + + .. code-block:: bitbake SYSTEMD_PACKAGES ?= "${PN}" @@ -10674,7 +11362,9 @@ system and gives an overview of their function and contents. When you specify this file in your recipe, use a package name override to indicate the package to which the value applies. Here is - an example from the connman recipe:: + an example from the connman recipe: + + .. code-block:: bitbake SYSTEMD_SERVICE:${PN} = "connman.service" @@ -10694,7 +11384,9 @@ system and gives an overview of their function and contents. :term:`T` This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a - particular recipe. The variable is typically set as follows:: + particular recipe. The variable is typically set as follows: + + .. code-block:: bitbake T = "${WORKDIR}/temp" @@ -10728,7 +11420,9 @@ system and gives an overview of their function and contents. Specifies architecture-specific assembler flags for the target system. :term:`TARGET_AS_ARCH` is initialized from :term:`TUNE_ASARGS` by default in the BitBake - configuration file (``meta/conf/bitbake.conf``):: + configuration file (``meta/conf/bitbake.conf``): + + .. code-block:: bitbake TARGET_AS_ARCH = "${TUNE_ASARGS}" @@ -10799,7 +11493,9 @@ system and gives an overview of their function and contents. Specifies architecture-specific linker flags for the target system. :term:`TARGET_LD_ARCH` is initialized from :term:`TUNE_LDARGS` by default in the BitBake - configuration file (``meta/conf/bitbake.conf``):: + configuration file (``meta/conf/bitbake.conf``): + + .. code-block:: bitbake TARGET_LD_ARCH = "${TUNE_LDARGS}" @@ -10988,7 +11684,9 @@ system and gives an overview of their function and contents. program does. For example, to use the Picocom terminal program on serial device - ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: + ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: + + .. code-block:: bitbake TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" @@ -11037,13 +11735,17 @@ system and gives an overview of their function and contents. Tests include ``ping``, ``ssh``, ``df`` among others. You can add your own tests to the list of tests by appending :term:`TEST_SUITES` as - follows:: + follows: + + .. code-block:: bitbake TEST_SUITES:append = " mytest" Alternatively, you can provide the "auto" option to have all applicable tests run against - the image:: + the image: + + .. code-block:: bitbake TEST_SUITES:append = " auto" @@ -11055,7 +11757,9 @@ system and gives an overview of their function and contents. another test must appear later in the list than the test on which they depend. For example, if you append the list of tests with two tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on - ``test_A``, then you must order the tests as follows:: + ``test_A``, then you must order the tests as follows: + + .. code-block:: bitbake TEST_SUITES = "test_A test_B" @@ -11065,7 +11769,9 @@ system and gives an overview of their function and contents. :term:`TEST_TARGET` Specifies the target controller to use when running tests against a - test image. The default controller to use is "qemu":: + test image. The default controller to use is "qemu": + + .. code-block:: bitbake TEST_TARGET = "qemu" @@ -11104,7 +11810,9 @@ system and gives an overview of their function and contents. set to "qemu". When you specify the IP address, you can also include a port. Here is - an example:: + an example: + + .. code-block:: bitbake TEST_TARGET_IP = "192.168.1.4:2201" @@ -11164,7 +11872,9 @@ system and gives an overview of their function and contents. If you want to establish this directory in a location other than the default, you can set it to another value in your - :ref:`structure-build-conf-site.conf` configuration file:: + :ref:`structure-build-conf-site.conf` configuration file: + + .. code-block:: bitbake TMPDIR = "/another/location" @@ -11240,7 +11950,9 @@ system and gives an overview of their function and contents. :term:`TOOLCHAIN_OPTIONS` This variable holds extra options passed to the compiler and the linker for non ``-native`` recipes as they have to point to their custom - ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`:: + ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`: + + .. code-block:: bitbake TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}" @@ -11250,7 +11962,9 @@ system and gives an overview of their function and contents. :term:`TOOLCHAIN_OUTPUTNAME` This variable defines the name used for the toolchain output. The :ref:`populate_sdk_base ` class sets - the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:: + the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows: + + .. code-block:: bitbake TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" @@ -11304,7 +12018,9 @@ system and gives an overview of their function and contents. :term:`TUNE_ARCH` is tied closely to :term:`TARGET_ARCH`, which defines the target machine's architecture. The BitBake configuration file - (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:: + (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows: + + .. code-block:: bitbake TARGET_ARCH = "${TUNE_ARCH}" @@ -11326,7 +12042,9 @@ system and gives an overview of their function and contents. typically under ``meta/conf/machine/include/`` and are influenced through :term:`TUNE_FEATURES`. For example, the ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags - for the x86 architecture as follows:: + for the x86 architecture as follows: + + .. code-block:: bitbake TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" @@ -11372,7 +12090,9 @@ system and gives an overview of their function and contents. typically under ``meta/conf/machine/include/`` and are influenced through :term:`TUNE_FEATURES`. For example, the ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags - for the x86 architecture as follows:: + for the x86 architecture as follows: + + .. code-block:: bitbake TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" @@ -11385,13 +12105,17 @@ system and gives an overview of their function and contents. :term:`TUNE_PKGARCH` The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages. The specific - tune is defined using the "_tune" override as follows:: + tune is defined using the "_tune" override as follows: + + .. code-block:: bitbake TUNE_PKGARCH:tune-tune = "tune" These tune-specific package architectures are defined in the machine include files. Here is an example of the "core2-32" tuning as used in - the ``meta/conf/machine/include/x86/tune-core2.inc`` file:: + the ``meta/conf/machine/include/x86/tune-core2.inc`` file: + + .. code-block:: bitbake TUNE_PKGARCH:tune-core2-32 = "core2-32" @@ -11403,7 +12127,9 @@ system and gives an overview of their function and contents. :term:`OpenEmbedded-Core (OE-Core)`. Here is an example from the ``meta/conf/machine/include/mips/arch-mips.inc`` include file that lists the "o32" and "n64" features as conflicting with the "n32" - feature:: + feature: + + .. code-block:: bitbake TUNECONFLICTS[n32] = "o32 n64" @@ -11412,7 +12138,9 @@ system and gives an overview of their function and contents. feature. The specified feature is stored as a flag. Valid features are specified in the machine include files (e.g. ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example - from that file:: + from that file: + + .. code-block:: bitbake TUNEVALID[bigendian] = "Enable big-endian mode." @@ -11429,7 +12157,9 @@ system and gives an overview of their function and contents. :term:`UBOOT_CONFIG_FRAGMENTS`, :term:`UBOOT_CONFIG_IMAGE_FSTYPES`, and :term:`UBOOT_CONFIG_MAKE_OPTS`. - Here is an updated example from the ``meta-freescale`` layer. :: + Here is an updated example from the ``meta-freescale`` layer. + + .. code-block:: bitbake UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor" @@ -11455,7 +12185,9 @@ system and gives an overview of their function and contents. :term:`UBOOT_CONFIG_BINARY` This variable cannot be set to a value in a config, it is a placeholder - for configuring the :term:`UBOOT_CONFIG` flow via flags:: + for configuring the :term:`UBOOT_CONFIG` flow via flags: + + .. code-block:: bitbake UBOOT_CONFIG_BINARY[foo] = "binary1" UBOOT_CONFIG_BINARY[bar] = "binary2" @@ -11478,7 +12210,9 @@ system and gives an overview of their function and contents. :term:`UBOOT_CONFIG_FRAGMENTS` This variable cannot be set to a value in a config, it is a placeholder - for configuring the :term:`UBOOT_CONFIG` flow via flags:: + for configuring the :term:`UBOOT_CONFIG` flow via flags: + + .. code-block:: bitbake UBOOT_CONFIG_FRAGMENTS[foo] = "frag1 frag2" UBOOT_CONFIG_FRAGMENTS[bar] = "frag3" @@ -11496,7 +12230,9 @@ system and gives an overview of their function and contents. :term:`UBOOT_CONFIG_IMAGE_FSTYPES` This variable cannot be set to a value in a config, it is a placeholder - for configuring the :term:`UBOOT_CONFIG` flow via flags:: + for configuring the :term:`UBOOT_CONFIG` flow via flags: + + .. code-block:: bitbake UBOOT_CONFIG_IMAGE_FSTYPES[foo] = "fstype1" UBOOT_CONFIG_IMAGE_FSTYPES[bar] = "fstype2" @@ -11513,7 +12249,9 @@ system and gives an overview of their function and contents. :term:`UBOOT_CONFIG_MAKE_OPTS` This variable cannot be set to a value in a config, it is a placeholder - for configuring the :term:`UBOOT_CONFIG` flow via flags:: + for configuring the :term:`UBOOT_CONFIG` flow via flags: + + .. code-block:: bitbake UBOOT_CONFIG_MAKE_OPTS[foo] = "OPT1=foo OPT2=2" UBOOT_CONFIG_MAKE_OPTS[bar] = "OPT1=bar" @@ -11568,13 +12306,17 @@ system and gives an overview of their function and contents. Some examples: - - Adding a script ``boot.cmd`` as a uImage to ``/boot``:: + - Adding a script ``boot.cmd`` as a uImage to ``/boot``: + + .. code-block:: bitbake UBOOT_ENV = "boot" UBOOT_ENV_SUFFIX = "scr" SRC_URI += "file://${UBOOT_ENV_SRC}" - - Adding a script ``uEnv.txt`` as a plain text file to ``/boot``:: + - Adding a script ``uEnv.txt`` as a plain text file to ``/boot``: + + .. code-block:: bitbake UBOOT_ENV = "uEnv" UBOOT_ENV_SUFFIX = "txt" @@ -11603,7 +12345,9 @@ system and gives an overview of their function and contents. set this value to "2", as two 32 bit values (cells) will be needed to represent such addresses. - Here is an example setting "0x400000000" as a load address:: + Here is an example setting "0x400000000" as a load address: + + .. code-block:: bitbake UBOOT_FIT_ADDRESS_CELLS = "2" UBOOT_LOADADDRESS = "0x04 0x00000000" @@ -11617,19 +12361,25 @@ system and gives an overview of their function and contents. Secure Monitor. This variable enables the generation of a U-Boot FIT image with a Trusted Firmware-A (TF-A) binary. - Its default value is "0", so set it to "1" to enable this functionality:: + Its default value is "0", so set it to "1" to enable this functionality: + + .. code-block:: bitbake UBOOT_FIT_ARM_TRUSTED_FIRMWARE = "1" :term:`UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE` Specifies the path to the Trusted Firmware-A (TF-A) binary. Its default - value is "bl31.bin":: + value is "bl31.bin": + + .. code-block:: bitbake UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "bl31.bin" If a relative path is provided, the file is expected to be relative to U-Boot's :term:`B` directory. An absolute path can be provided too, - e.g.:: + e.g.: + + .. code-block:: bitbake UBOOT_FIT_ARM_TRUSTED_FIRMWARE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/bl31.bin" @@ -11637,7 +12387,9 @@ system and gives an overview of their function and contents. you must add the necessary dependency in a U-Boot ``.bbappend`` file. The recipe name for Trusted Firmware-A (TF-A) binary is ``trusted-firmware-a``, which comes from the - :yocto_git:`meta-arm ` layer:: + :yocto_git:`meta-arm ` layer: + + .. code-block:: bitbake do_compile[depends] += "trusted-firmware-a:do_deploy" @@ -11648,7 +12400,9 @@ system and gives an overview of their function and contents. :term:`UBOOT_FIT_CONF_FIRMWARE` Adds one image to the ``firmware`` property of the configuration node of the U-Boot Image Tree Source (ITS). Sets the ``firmware`` property to - select the image to boot first:: + select the image to boot first: + + .. code-block:: bitbake UBOOT_FIT_CONF_FIRMWARE = "fwa" @@ -11658,13 +12412,17 @@ system and gives an overview of their function and contents. Adds one or more user-defined images to the ``loadables`` property of the configuration node of the U-Boot Image Tree Source (ITS). This variable is handled by the local shell in the recipe so appropriate escaping - should be done, e.g. escaping quotes.:: + should be done, e.g. escaping quotes.: + + .. code-block:: bitbake UBOOT_FIT_CONF_USER_LOADABLES = '\"fwa\", \"fwb\"' :term:`UBOOT_FIT_DESC` Specifies the description string encoded into a U-Boot fitImage. The default - value is set by the :ref:`ref-classes-uboot-sign` class as follows:: + value is set by the :ref:`ref-classes-uboot-sign` class as follows: + + .. code-block:: bitbake UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" @@ -11673,7 +12431,9 @@ system and gives an overview of their function and contents. they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`. The default value is "0". - Enable this as follows:: + Enable this as follows: + + .. code-block:: bitbake UBOOT_FIT_GENERATE_KEYS = "1" @@ -11716,19 +12476,25 @@ system and gives an overview of their function and contents. the surrounding system. This variable enables the generation of a U-Boot FIT image with a Trusted Execution Environment (TEE) binary. - Its default value is "0", so set it to "1" to enable this functionality:: + Its default value is "0", so set it to "1" to enable this functionality: + + .. code-block:: bitbake UBOOT_FIT_TEE = "1" :term:`UBOOT_FIT_TEE_IMAGE` Specifies the path to the Trusted Execution Environment (TEE) binary. Its - default value is "tee-raw.bin":: + default value is "tee-raw.bin": + + .. code-block:: bitbake UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin" If a relative path is provided, the file is expected to be relative to U-Boot's :term:`B` directory. An absolute path can be provided too, - e.g.:: + e.g.: + + .. code-block:: bitbake UBOOT_FIT_TEE_IMAGE ?= "${DEPLOY_DIR_IMAGE}/tee-raw.bin" @@ -11736,7 +12502,9 @@ system and gives an overview of their function and contents. recipe, you must add the necessary dependency in a U-Boot ``.bbappend`` file. The recipe name for Trusted Execution Environment (TEE) binary is ``optee-os``, which comes from the :yocto_git:`meta-arm ` - layer:: + layer: + + .. code-block:: bitbake do_compile[depends] += "optee-os:do_deploy" @@ -11764,7 +12532,9 @@ system and gives an overview of their function and contents. }; }; - Users can include their custom ITS snippet in this variable, e.g.:: + Users can include their custom ITS snippet in this variable, e.g.: + + .. code-block:: bitbake UBOOT_FIT_FWA_ITS = '\ fwa {\n\ @@ -11817,7 +12587,9 @@ system and gives an overview of their function and contents. This variable allows to generate a FIT image for U-Boot, which is one of the ways to implement a verified boot process. - Its default value is "0", so set it to "1" to enable this functionality:: + Its default value is "0", so set it to "1" to enable this functionality: + + .. code-block:: bitbake UBOOT_FITIMAGE_ENABLE = "1" @@ -11829,7 +12601,9 @@ system and gives an overview of their function and contents. These fragments are located in same ``${S}/configs/`` directory as the defconfig. - For example:: + For example: + + .. code-block:: bitbake UBOOT_MACHINE = "am62x_evm_r5_defconfig" UBOOT_FRAGMENTS = "am62x_r5_usbdfu.config" @@ -11840,7 +12614,9 @@ system and gives an overview of their function and contents. This variable enables the generation of the U-Boot initial environment in binary format. - Its default value is "0", set it to "1" to enable this functionality:: + Its default value is "0", set it to "1" to enable this functionality: + + .. code-block:: bitbake UBOOT_INITIAL_ENV_BINARY = "1" @@ -11864,7 +12640,9 @@ system and gives an overview of their function and contents. this variable should be set to properly generate the redundant environment in the output U-boot environment binary file. - Its default value is "0", set it to "1" to enable this functionality:: + Its default value is "0", set it to "1" to enable this functionality: + + .. code-block:: bitbake UBOOT_INITIAL_ENV_BINARY_REDUND = "1" @@ -11876,7 +12654,9 @@ system and gives an overview of their function and contents. :term:`UBOOT_INITIAL_ENV_BINARY_SIZE` This variable sets the binary size (in bytes) of the U-Boot initial environment. Both hexadecimal and decimal values are supported and can be - set as follows:: + set as follows: + + .. code-block:: bitbake UBOOT_INITIAL_ENV_BINARY_SIZE = "0x4000" @@ -11901,7 +12681,9 @@ system and gives an overview of their function and contents. Appends a string to the name of the local version of the U-Boot image. For example, assuming the version of the U-Boot image built was "2013.10", the full version string reported by U-Boot would be - "2013.10-yocto" given the following statement:: + "2013.10-yocto" given the following statement: + + .. code-block:: bitbake UBOOT_LOCALVERSION = "-yocto" @@ -12068,7 +12850,9 @@ system and gives an overview of their function and contents. :term:`UNINATIVE_CHECKSUM` variable flags contain the checksums of the uninative tarball as specified by the :term:`UNINATIVE_URL` variable. There should be one checksum per tarballs published at - :term:`UNINATIVE_URL`, which match architectures. For example:: + :term:`UNINATIVE_URL`, which match architectures. For example: + + .. code-block:: bitbake UNINATIVE_CHECKSUM[aarch64] ?= "812045d826b7fda88944055e8526b95a5a9440bfef608d5b53fd52faab49bf85" UNINATIVE_CHECKSUM[i686] ?= "5cc28efd0c15a75de4bcb147c6cce65f1c1c9d442173a220f08427f40a3ffa09" @@ -12117,7 +12901,9 @@ system and gives an overview of their function and contents. releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS` to ``1`` in the recipe, and the OpenEmbedded build system will compare the latest commit with the one currently specified - by the recipe (:term:`SRCREV`):: + by the recipe (:term:`SRCREV`): + + .. code-block:: bitbake UPSTREAM_CHECK_COMMITS = "1" @@ -12130,7 +12916,9 @@ system and gives an overview of their function and contents. You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a regular expression to filter only the relevant tags should the - default filter not work correctly:: + default filter not work correctly: + + .. code-block:: bitbake UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" @@ -12138,7 +12926,9 @@ system and gives an overview of their function and contents. Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different regular expression instead of the default one when the package checking system is parsing the page found using - :term:`UPSTREAM_CHECK_URI`:: + :term:`UPSTREAM_CHECK_URI`: + + .. code-block:: bitbake UPSTREAM_CHECK_REGEX = "package_regex" @@ -12149,7 +12939,9 @@ system and gives an overview of their function and contents. determined by fetching the directory listing where the tarball is and attempting to find a later tarball. When this approach does not work, you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that - contains the link to the latest tarball:: + contains the link to the latest tarball: + + .. code-block:: bitbake UPSTREAM_CHECK_URI = "recipe_url" @@ -12179,7 +12971,9 @@ system and gives an overview of their function and contents. :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in the recipe allows to determine what the latest upstream version is, you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe - to acknowledge that the check cannot be performed:: + to acknowledge that the check cannot be performed: + + .. code-block:: bitbake UPSTREAM_VERSION_UNKNOWN = "1" @@ -12225,7 +13019,9 @@ system and gives an overview of their function and contents. Classes inherited using :term:`USER_CLASSES` must be located in the ``classes-global/`` or ``classes/`` subdirectories. - The default list is set in your ``local.conf`` file:: + The default list is set in your ``local.conf`` file: + + .. code-block:: bitbake USER_CLASSES ?= "buildstats" @@ -12252,7 +13048,9 @@ system and gives an overview of their function and contents. :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan on using statically assigned ``gid`` and ``uid`` values, you should set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` - file as follows:: + file as follows: + + .. code-block:: bitbake USERADD_ERROR_DYNAMIC = "error" @@ -12282,8 +13080,9 @@ system and gives an overview of their function and contents. When applying static group identification (``gid``) values, the OpenEmbedded build system looks in :term:`BBPATH` for a ``files/group`` file and then applies those ``uid`` values. Set the - variable as follows in your ``local.conf`` file:: + variable as follows in your ``local.conf`` file: + .. code-block:: bitbake USERADD_GID_TABLES = "files/group" @@ -12299,7 +13098,9 @@ system and gives an overview of their function and contents. You must set this variable if the recipe inherits the class. For example, the following enables adding a user for the main package in - a recipe:: + a recipe: + + .. code-block:: bitbake USERADD_PACKAGES = "${PN}" @@ -12315,7 +13116,9 @@ system and gives an overview of their function and contents. the ``useradd`` command if you add a user to the system when the package is installed. - Here is an example from the ``dbus`` recipe:: + Here is an example from the ``dbus`` recipe: + + .. code-block:: bitbake USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \ --no-create-home --shell /bin/false \ @@ -12333,7 +13136,9 @@ system and gives an overview of their function and contents. When applying static user identification (``uid``) values, the OpenEmbedded build system looks in :term:`BBPATH` for a ``files/passwd`` file and then applies those ``uid`` values. Set the - variable as follows in your ``local.conf`` file:: + variable as follows in your ``local.conf`` file: + + .. code-block:: bitbake USERADD_UID_TABLES = "files/passwd" @@ -12368,7 +13173,9 @@ system and gives an overview of their function and contents. When a recipe inherits the :ref:`ref-classes-useradd` class, this variable specifies for a package what parameters should be passed to the ``usermod`` command if you wish to modify a user when the package is installed. - Is is typically used to add the user to one or more groups. For example:: + Is is typically used to add the user to one or more groups. For example: + + .. code-block:: bitbake USERMOD_PARAM:${PN} = "--append --groups group1,group2 user" @@ -12378,24 +13185,32 @@ system and gives an overview of their function and contents. or in image definitions. An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible - to either use BusyBox based utilities:: + to either use BusyBox based utilities: + + .. code-block:: bitbake VIRTUAL-RUNTIME_base-utils = "busybox" or their full featured implementations from GNU Coreutils - and other projects:: + and other projects: + + .. code-block:: bitbake VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils" Here are two examples using this virtual runtime package. The first one is in :oe_git:`initramfs-framework_1.0.bb - `:: + `: + + .. code-block:: bitbake RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}" The second example is in the :oe_git:`core-image-initramfs-boot ` - image definition:: + image definition: + + .. code-block:: bitbake PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd" @@ -12485,7 +13300,9 @@ system and gives an overview of their function and contents. With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to specify a list of additional dependencies (e.g. native tools, bootloaders, and so forth), that are required to build Wic images. - Here is an example:: + Here is an example: + + .. code-block:: bitbake WKS_FILE_DEPENDS = "some-native-tool" From patchwork Wed Aug 26 01:34:47 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96335 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 4251AC61DBE for ; Wed, 26 Aug 2026 01:35:22 +0000 (UTC) Received: from mail-qk1-f174.google.com (mail-qk1-f174.google.com [209.85.222.174]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3401.1787708112361942152 for ; Tue, 25 Aug 2026 18:35:12 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=AWzp/RaQ; spf=pass (domain: gmail.com, ip: 209.85.222.174, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f174.google.com with SMTP id af79cd13be357-936ea476db3so30369785a.0 for ; Tue, 25 Aug 2026 18:35:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708111; x=1788312911; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=VejAsGiLFGIHFTUVfmxBm6mF6A+7uLZTQYCNOZKl1ug=; b=AWzp/RaQyOr9W/OcjPRybHGjJMib/zFPzEB6djEnvVOUuE8Uiaz2Bbm8TgvNV70eoz f/1ohdpBCHqfdd09wY3DXAFC5kqQPYoeDS5yrWS4E6vWn7QxZpvK4ibn3Z3ScsThSbQs Euh7XrtqfdThZDyzMfPkQhzfIsRvmICric1y3VBbDQPiWi9pcJq51ahA+uRuluYl8OHY 9pAJlDhc95/OgL3Q6mmKo76r9GLPyUjN0IhDI6NTrebZRDpEQfzf/UM8bsViYWqO/J/R gJhvvOa5Bwg3Hpn0QmioVKDXc3NsxO84OCNYoEw5Uqb4hMUxfZn5VzjSgVkVvLm7qqT1 tkEw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708111; x=1788312911; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=VejAsGiLFGIHFTUVfmxBm6mF6A+7uLZTQYCNOZKl1ug=; b=tJtqsWgb1Ii3+UTqsVAsHQQEpdt3lykaZ1pS8XXrJiriuCLxjPIyGkNhEnaCRcIJ7B /l4iRRm8pOAwD07XDZnScToM+hMgwj8Eqt+Q0hgD2ocscwwSf/e+L8Z0SvCXUMtmK1ZX WgXibod3eWz4+mfoncFN6AdT64Jxxvpze8HkMGWI7Aud2wN2CP8WpgkclPnyn/H0x2fC c3TI0jHiMi6AJ+UtNlKU5lRnK4fhNiKdi++kn6qhlk5BvqTXjkQV97KBODUuPzPbinNh SofQOQOBL3zmrk5CM0SYcyPdXsPHciMqGIF7rs1fnsTleqkz665HK1NL1MyJAjxnosyq Th6w== X-Gm-Message-State: AFuF++m2L1gyjMkjXrEdZy9Vkwc+jBEwPjCdrG8V7pjD6CCAuWe699lo HAEh+tuRXK7T5E517u+rE7oDsS0WKI7gGtoQjtkc5l0BjKywj7ydIz8SEfnMkxVu X-Gm-Gg: AR+sD118c4aYDbBLk5EuQFBZvL08DUS7y3CZQLUjhNVAujV/BgS+dopNO/Ndym2kugt kVcX22dtVFkcIihRxORI7NBNxjpFyyHo4a9HgshEToI7IVxFEthB6E7T/F/C/dod767FDZG8rn8 voKKSicU25GcK0fYrUal+YfDVwb3ehLRVnx8fwierf7uT3GwQUOia2VHo8hNoyTKVZGy4lX2CSl ysqOTo3kXpGgkhRYbsuyYoMa+1glCD1NRgAJYNZVEA7m7GsfJAfGQpGLQGY6B1Yl/ZKFf3N+3Xm yom0okfKPKcTjKZNw3Simhnga1cr/Dcux1SIg8KQ51hQCfwS5P/3E3+Wr3ZqoxU0vSvEeNQVZQF QjQyJvt9VjKbV3vjxqxMkS/E0z78jfYItvEEsQpY8SaxyZjdhjJ1qkNI29M5Tv4rhx1ZHdHUkSX /7Qhr22+4sFq66QqaZLI7AxPcIye3xe5w5WtJzSUKlhQ2zG+tS12lZotuYbu+Bu+wCvN8avfR/D Lp3z3LGOz8FZu1Q2inx9hN05fvdy5o= X-Received: by 2002:a05:620a:5236:b0:937:6c0a:9b65 with SMTP id af79cd13be357-93780186a21mr201677985a.7.1787708110696; Tue, 25 Aug 2026 18:35:10 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.08 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:08 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 02/10] ref-manual: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:47 -0400 Message-ID: <20260826013502.2674000-3-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:22 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10347 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 62 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- documentation/ref-manual/classes.rst | 168 +++++++++++++----- .../ref-manual/devtool-reference.rst | 4 +- documentation/ref-manual/faq.rst | 20 ++- documentation/ref-manual/features.rst | 12 +- documentation/ref-manual/qa-checks.rst | 20 ++- documentation/ref-manual/tasks.rst | 20 ++- 6 files changed, 183 insertions(+), 61 deletions(-) diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index f3d1aa64e703..5dec5008ec3f 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -206,11 +206,15 @@ package in the :term:`SRC_URI` variable and inheriting this class. For RPMs and other packages that do not contain a subdirectory, you should set the :term:`SRC_URI` option ``subdir`` to :term:`BP` so that the contents are extracted to the directory expected by the default value of :term:`S`. For -example:: +example: + +.. code-block:: bitbake SRC_URI = "https://example.com/downloads/somepackage.rpm;subdir=${BP}" -This class can also be used for tarballs. For example:: +This class can also be used for tarballs. For example: + +.. code-block:: bitbake SRC_URI = "file://somepackage.tar.xz;subdir=${BP}" @@ -372,7 +376,9 @@ make it inherit the :ref:`ref-classes-cargo` and bitbake -c update_crates recipe This creates a ``recipe-crates.inc`` file that you can include in your -recipe:: +recipe: + +.. code-block:: bitbake require ${BPN}-crates.inc @@ -395,7 +401,9 @@ files between builds. Recipes (including :ref:`ref-classes-native` ones) can make use of the host's ``ccache`` binary (via :term:`HOSTTOOLS`) if the following configuration -statements are provided in a :term:`configuration file`:: +statements are provided in a :term:`configuration file`: + +.. code-block:: bitbake ASSUME_PROVIDED += "ccache-native" HOSTTOOLS += "ccache" @@ -549,7 +557,9 @@ The :ref:`ref-classes-create-spdx` class provides support for automatically creating :term:`SPDX` :term:`SBOM` documents based upon image and SDK contents. -This class is meant to be inherited globally from a configuration file:: +This class is meant to be inherited globally from a configuration file: + +.. code-block:: bitbake INHERIT += "create-spdx" @@ -702,7 +712,9 @@ information about using :ref:`ref-classes-devshell`. The :ref:`ref-classes-devupstream` class uses :term:`BBCLASSEXTEND` to add a variant of the recipe that fetches from an alternative URI (e.g. Git) instead of a -tarball. Here is an example:: +tarball. Here is an example: + +.. code-block:: bitbake BBCLASSEXTEND = "devupstream:target" SRC_URI:class-devupstream = "git://git.example.com/example;branch=main" @@ -712,7 +724,9 @@ Adding the above statements to your recipe creates a variant that has :term:`DEFAULT_PREFERENCE` set to "-1". Consequently, you need to select the variant of the recipe to use it. Any development-specific adjustments can be done by using the -``class-devupstream`` override. Here is an example:: +``class-devupstream`` override. Here is an example: + +.. code-block:: bitbake DEPENDS:append:class-devupstream = " gperf-native" do_configure:prepend:class-devupstream() { @@ -785,7 +799,9 @@ be performed using the whole. Use the :ref:`ref-classes-useradd` class to add user and group configuration to a specific recipe. -Here is an example that uses this class in an image recipe:: +Here is an example that uses this class in an image recipe: + +.. code-block:: bitbake inherit extrausers EXTRA_USERS_PARAMS = "\ @@ -802,7 +818,9 @@ passwords. First on host, create the (escaped) password hash:: printf "%q" $(mkpasswd -m sha256crypt tester01) -The resulting hash is set to a variable and used in ``useradd`` command parameters:: +The resulting hash is set to a variable and used in ``useradd`` command parameters: + +.. code-block:: bitbake inherit extrausers PASSWD = "\$X\$ABC123\$A-Long-Hash" @@ -811,7 +829,9 @@ The resulting hash is set to a variable and used in ``useradd`` command paramete useradd -p '${PASSWD}' tester-sue; \ " -Finally, here is an example that sets the root password:: +Finally, here is an example that sets the root password: + +.. code-block:: bitbake inherit extrausers EXTRA_USERS_PARAMS = "\ @@ -1046,7 +1066,9 @@ specific override names are defined as ``grub_LABEL``. For example, for a label ``factory``, the override name would be ``grub_factory``. A custom GRUB menu entry titled "Factory Install" with the -additional parameter ``factory=yes`` can be achieved as follows:: +additional parameter ``factory=yes`` can be achieved as follows: + +.. code-block:: bitbake LABELS:append = " factory" APPEND:grub_factory = "factory=yes" @@ -1277,7 +1299,9 @@ configuration). However, to skip one or more checks in recipes, you should use :term:`INSANE_SKIP`. For example, to skip the check for symbolic link ``.so`` files in the main package of a recipe, add the following to the recipe. You need to realize that the -package name override, in this example ``${PN}``, must be used:: +package name override, in this example ``${PN}``, must be used: + +.. code-block:: bitbake INSANE_SKIP:${PN} += "dev-so" @@ -1370,7 +1394,9 @@ The :ref:`ref-classes-kernel-fit-extra-artifacts` class exposes the required ker artifacts to the :term:`DEPLOY_DIR_IMAGE` which are used by the :ref:`ref-classes-kernel-fit-image` class to create the FIT image. -The simplest example for building a FIT image is to add:: +The simplest example for building a FIT image is to add: + +.. code-block:: bitbake KERNEL_CLASSES += "kernel-fit-extra-artifacts" @@ -1383,7 +1409,9 @@ directory and a ``linux-yocto-fitimage`` package which can be installed. The same approach works for all variants of the ``linux-yocto`` kernel. For example, if the ``linux-yocto-rt`` kernel should be used, add the following -lines to the machine configuration file:: +lines to the machine configuration file: + +.. code-block:: bitbake KERNEL_CLASSES += "kernel-fit-extra-artifacts" PREFERRED_PROVIDER_virtual/kernel = "linux-yocto-rt" @@ -1460,7 +1488,9 @@ allow configuration: U-Boot commands. When using a boot script the recipe which inherits the :ref:`ref-classes-kernel-fit-image` class should add the script to :term:`SRC_URI` and set the :term:`FIT_UBOOT_ENV` variable to the name of the - file like the following:: + file like the following: + + .. code-block:: bitbake FIT_UBOOT_ENV = "boot.txt" SRC_URI += "file://${FIT_UBOOT_ENV}" @@ -1504,7 +1534,9 @@ variable in your kernel recipe or machine configuration when building FIT images It ensures that all necessary files are available for packaging into the FIT image, such as the kernel binary, device tree blobs (DTBs), and other related files. -For example, to enable this class, set:: +For example, to enable this class, set: + +.. code-block:: bitbake KERNEL_CLASSES += "kernel-fit-extra-artifacts" @@ -1780,7 +1812,9 @@ a couple different ways: caused by existing code that depends on that naming convention. - Or, create a :ref:`ref-classes-native` variant of any target recipe (e.g. - ``myrecipe.bb``) by adding the following to the recipe:: + ``myrecipe.bb``) by adding the following to the recipe: + + .. code-block:: bitbake BBCLASSEXTEND = "native" @@ -1822,7 +1856,9 @@ couple different ways: depends on the naming convention. - Or, create a :ref:`ref-classes-nativesdk` variant of any target recipe (e.g. - ``myrecipe.bb``) by adding the following to the recipe:: + ``myrecipe.bb``) by adding the following to the recipe: + + .. code-block:: bitbake BBCLASSEXTEND = "nativesdk" @@ -1889,7 +1925,9 @@ root filesystem read-only. To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper layer in your machine configuration. The underlying file system can be anything that -is supported by ``overlayfs``. This has to be done in your machine configuration:: +is supported by ``overlayfs``. This has to be done in your machine configuration: + +.. code-block:: bitbake OVERLAYFS_MOUNT_POINT[data] = "/data" @@ -1903,7 +1941,9 @@ is supported by ``overlayfs``. This has to be done in your machine configuration The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP (e.g. in ``systemd-machine-units`` recipe) and it's installed into the image. -Then you can specify writable directories on a recipe basis (e.g. in my-application.bb):: +Then you can specify writable directories on a recipe basis (e.g. in my-application.bb): + +.. code-block:: bitbake OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" @@ -1912,11 +1952,15 @@ want to have a writable location on the file system, but do not need that the da survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs`` file system. -In your machine configuration:: +In your machine configuration: + +.. code-block:: bitbake OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay" -and then in your recipe:: +and then in your recipe: + +.. code-block:: bitbake OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application" @@ -1948,7 +1992,9 @@ boot stage is required. The idea is to supply a custom init script that mounts ``/etc`` before launching the actual init program, because the latter already requires ``/etc`` to be mounted. -Example usage in image recipe:: +Example usage in image recipe: + +.. code-block:: bitbake IMAGE_FEATURES += "overlayfs-etc" @@ -1957,14 +2003,18 @@ Example usage in image recipe:: This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES` Your machine configuration should define at least the device, mount point, and file system type -you are going to use for ``overlayfs``:: +you are going to use for ``overlayfs``: + +.. code-block:: bitbake OVERLAYFS_ETC_MOUNT_POINT = "/data" OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2" OVERLAYFS_ETC_FSTYPE ?= "ext4" To control more mount options you should consider setting mount options -(``defaults`` is used by default):: +(``defaults`` is used by default): + +.. code-block:: bitbake OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync" @@ -1976,7 +2026,9 @@ The class provides two options for ``/sbin/init`` generation: but it poses a restriction that package-management can't be used, because updating the init manager would remove the generated script. -- If you wish to keep original init as is, you can set:: +- If you wish to keep original init as is, you can set: + + .. code-block:: bitbake OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0" @@ -1994,7 +2046,9 @@ before attempting to fetch it from the upstream specified in :term:`SRC_URI` within each recipe. To use this class, inherit it globally and specify -:term:`SOURCE_MIRROR_URL`. Here is an example:: +:term:`SOURCE_MIRROR_URL`. Here is an example: + +.. code-block:: bitbake INHERIT += "own-mirrors" SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" @@ -2129,7 +2183,9 @@ Previously, this class was called the ``task`` class. .. note:: - If you're defining a packagegroup and need to set:: + If you're defining a packagegroup and need to set: + + .. code-block:: bitbake PACKAGE_ARCH = "${MACHINE_ARCH}" @@ -2563,7 +2619,9 @@ installed by ``libtool``. Removing these files results in them being absent from both the sysroot and target packages. If a recipe needs the ``.la`` files to be installed, then the recipe can -override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:: +override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: + +.. code-block:: bitbake REMOVE_LIBTOOL_LA = "0" @@ -2596,7 +2654,9 @@ directory for a recipe when one of its tasks fails, or any other nominated directories. It is useful in cases where the environment in which builds are run is ephemeral or otherwise inaccessible for examination during debugging. -To enable, add the following to your configuration:: +To enable, add the following to your configuration: + +.. code-block:: bitbake INHERIT += "retain" @@ -2619,7 +2679,9 @@ recipe are no longer needed. However, by default, the build system preserves these files for inspection and possible debugging purposes. If you would rather have these files deleted to save disk space as the build progresses, you can enable :ref:`ref-classes-rm-work` by adding the following to -your ``local.conf`` file, which is found in the :term:`Build Directory`:: +your ``local.conf`` file, which is found in the :term:`Build Directory`: + +.. code-block:: bitbake INHERIT += "rm_work" @@ -2628,14 +2690,18 @@ recipe, enabling :ref:`ref-classes-rm-work` will potentially result in your changes to the source being lost. To exclude some recipes from having their work directories deleted by :ref:`ref-classes-rm-work`, you can add the names of the recipe or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, -which can also be set in your ``local.conf`` file. Here is an example:: +which can also be set in your ``local.conf`` file. Here is an example: + +.. code-block:: bitbake RM_WORK_EXCLUDE += "busybox glibc" Finally, if you are using this class for a recipe but want to prevent :term:`BitBake` from deleting specific folders or files in that recipe's :term:`WORKDIR` (other than ``temp``), you can preserve those folders or -files with the :term:`RM_WORK_EXCLUDE_ITEMS` variable as follows:: +files with the :term:`RM_WORK_EXCLUDE_ITEMS` variable as follows: + +.. code-block:: bitbake RM_WORK_EXCLUDE_ITEMS += "items_to_keep" @@ -3064,7 +3130,9 @@ You should set :term:`SYSTEMD_SERVICE` to the name of the service file. You should also use a package name override to indicate the package to which the value applies. If the value applies to the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here -is an example from the connman recipe:: +is an example from the connman recipe: + +.. code-block:: bitbake SYSTEMD_SERVICE:${PN} = "connman.service" @@ -3144,7 +3212,9 @@ images using QEMU and on actual hardware. The classes handle loading the tests and starting the image. To use the classes, you need to perform steps to set up the environment. -To enable this class, add the following to your configuration:: +To enable this class, add the following to your configuration: + +.. code-block:: bitbake IMAGE_CLASSES += "testimage" @@ -3157,7 +3227,9 @@ following:: $ bitbake -c testimage image Alternatively, if you wish to have tests automatically run for each image -after it is built, you can set :term:`TESTIMAGE_AUTO`:: +after it is built, you can set :term:`TESTIMAGE_AUTO`: + +.. code-block:: bitbake TESTIMAGE_AUTO = "1" @@ -3310,7 +3382,9 @@ This class should not be inherited directly. It is inherited by the The :ref:`ref-classes-typecheck` class provides support for validating the values of variables set at the configuration level against their defined types. The OpenEmbedded build system allows you to define the type of a -variable using the "type" varflag. Here is an example:: +variable using the "type" varflag. Here is an example: + +.. code-block:: bitbake IMAGE_FEATURES[type] = "list" @@ -3325,12 +3399,16 @@ or more U-Boot build configurations. There are three ways to configure the recipe for your machine: - Using the :term:`UBOOT_MACHINE` variable (and its companion variable - :term:`UBOOT_BINARY`). For example:: + :term:`UBOOT_BINARY`). For example: + + .. code-block:: bitbake UBOOT_MACHINE = "config" UBOOT_BINARY = "u-boot.bin" -- Using :term:`UBOOT_CONFIG` variables. For example:: +- Using :term:`UBOOT_CONFIG` variables. For example: + + .. code-block:: bitbake UBOOT_CONFIG ??= "foo bar" UBOOT_CONFIG[foo] = "config" @@ -3348,7 +3426,9 @@ There are three ways to configure the recipe for your machine: In this example, all possible configurations are selected (``foo`` and ``bar``), but it is also possible to build only ``foo`` or ``bar`` by changing the value of :term:`UBOOT_CONFIG` to include either one or the - other. For exmaple:: + other. For exmaple: + + .. code-block:: bitbake UBOOT_CONFIG = "foo" UBOOT_CONFIG[foo] = "config" @@ -3415,7 +3495,9 @@ There are three ways to configure the recipe for your machine: See the documentation of :term:`UBOOT_CONFIG_FRAGMENTS` for more information. - Or, a legacy method using the :term:`UBOOT_CONFIG` variable by itself. - *This method is being deprecated, see note below.* For example:: + *This method is being deprecated, see note below.* For example: + + .. code-block:: bitbake UBOOT_CONFIG ??= "foo bar" UBOOT_CONFIG[foo] = "config,images,binary" @@ -3797,7 +3879,9 @@ The :ref:`ref-classes-vex` class is used to generate metadata needed by external tools to check for vulnerabilities, for example CVEs. In order to use this class, inherit the class in the ``local.conf`` file and it -will add the ``generate_vex`` task for every recipe:: +will add the ``generate_vex`` task for every recipe: + +.. code-block:: bitbake INHERIT += "vex" diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst index 6b21d302ff7e..dd3849e0e053 100644 --- a/documentation/ref-manual/devtool-reference.rst +++ b/documentation/ref-manual/devtool-reference.rst @@ -391,7 +391,9 @@ want to use it because the dependency on ``cdebconf`` is not easily satisfied. Maintainers can explicit the reason that is shown by adding the :term:`RECIPE_NO_UPDATE_REASON` variable to the corresponding recipe. See the :oe_git:`base-passwd_*.bb ` -recipe for an example:: +recipe for an example: + +.. code-block:: bitbake RECIPE_NO_UPDATE_REASON = "Version 3.5.38 requires cdebconf for update-passwd utility" diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index 374ecf8e887f..0b7814589660 100644 --- a/documentation/ref-manual/faq.rst +++ b/documentation/ref-manual/faq.rst @@ -120,7 +120,9 @@ fail. As an example, you could add a specific server for the build system to attempt before any others by adding something like the following to the -``local.conf`` configuration file:: +``local.conf`` configuration file: + +.. code-block:: bitbake PREMIRRORS:prepend = "\ git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ @@ -134,7 +136,9 @@ HTTPS requests and direct them to the ``http://`` sources mirror. You can use ``file://`` URLs to point to local directories or network shares as well. -Another option is to set:: +Another option is to set: + +.. code-block:: bitbake BB_NO_NETWORK = "1" @@ -142,7 +146,9 @@ This statement tells BitBake to issue an error instead of trying to access the Internet. This technique is useful if you want to ensure code builds only from local sources. -Here is another technique:: +Here is another technique: + +.. code-block:: bitbake BB_FETCH_PREMIRRORONLY = "1" @@ -150,7 +156,9 @@ This statement limits the build system to pulling source from the :term:`PREMIRRORS` only. Again, this technique is useful for reproducing builds. -Here is yet another technique:: +Here is yet another technique: + +.. code-block:: bitbake BB_GENERATE_MIRROR_TARBALLS = "1" @@ -160,7 +168,9 @@ however, the technique can simply waste time during the build. Finally, consider an example where you are behind an HTTP-only firewall. You could make the following changes to the ``local.conf`` configuration -file as long as the :term:`PREMIRRORS` server is current:: +file as long as the :term:`PREMIRRORS` server is current: + +.. code-block:: bitbake PREMIRRORS:prepend = "\ git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ diff --git a/documentation/ref-manual/features.rst b/documentation/ref-manual/features.rst index 63d47d6eca16..56337992f264 100644 --- a/documentation/ref-manual/features.rst +++ b/documentation/ref-manual/features.rst @@ -390,7 +390,9 @@ these valid features is as follows: installed, you can either remove ``ssh-server-dropbear`` from ``IMAGE_FEATURES`` and add ``dropbear`` to :term:`IMAGE_INSTALL` instead, or alternatively still use the feature but set - :term:`BAD_RECOMMENDATIONS` as follows:: + :term:`BAD_RECOMMENDATIONS` as follows: + + .. code-block:: bitbake BAD_RECOMMENDATIONS += "openssh-sftp-server" @@ -443,7 +445,9 @@ The :term:`DISTRO_FEATURES_OPTED_OUT` and :term:`MACHINE_FEATURES_OPTED_OUT` variables can be used to remove a feature provided by one of the :term:`DISTRO_FEATURES_DEFAULTS` of :term:`MACHINE_FEATURES_DEFAULTS` variables. -For example, the two following assignments:: +For example, the two following assignments: + +.. code-block:: bitbake DISTRO_FEATURES_DEFAULTS = "a b c" DISTRO_FEATURES_OPTED_OUT = "b" @@ -454,7 +458,9 @@ Would result in feature ``a`` and feature ``c`` making it to the final value of You can also opt out of all default features by setting :term:`DISTRO_FEATURES_OPTED_OUT` or :term:`MACHINE_FEATURES_OPTED_OUT` to -``*``:: +``*``: + +.. code-block:: bitbake DISTRO_FEATURES_OPTED_OUT = "*" diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst index 09b0f628a74b..49852c1b641d 100644 --- a/documentation/ref-manual/qa-checks.rst +++ b/documentation/ref-manual/qa-checks.rst @@ -408,7 +408,9 @@ non-UTF-8 characters. Some package managers do not support such characters. ``: invalid PACKAGECONFIG(s): [invalid-packageconfig]`` Checks that no undefined features are being added to :term:`PACKAGECONFIG`. -For example, any name "foo" for which the following form does not exist:: +For example, any name "foo" for which the following form does not exist: + +.. code-block:: bitbake PACKAGECONFIG[foo] = "..." @@ -437,7 +439,9 @@ provided by the build system. Check to be sure that the :term:`LDFLAGS` variable is being passed to the linker command. A common workaround for this situation is to pass in :term:`LDFLAGS` using :term:`TARGET_CC_ARCH` within the recipe as -follows:: +follows: + +.. code-block:: bitbake TARGET_CC_ARCH += "${LDFLAGS}" @@ -789,13 +793,17 @@ the private version of the library. This warning indicated that there is missing spaces around an assignment. -For example, the following assignments would print a warning:: +For example, the following assignments would print a warning: + +.. code-block:: bitbake FOO="bar" FOO= "bar" FOO ="bar" -These should be replaced by:: +These should be replaced by: + +.. code-block:: bitbake FOO = "bar" @@ -887,7 +895,9 @@ runtime. Typically, the way to solve this performance issue is to add "-fPIC" or "-fpic" to the compiler command-line options. For example, given software that reads :term:`CFLAGS` when you build it, -you could add the following to your recipe:: +you could add the following to your recipe: + +.. code-block:: bitbake CFLAGS:append = " -fPIC" diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst index 3517d0b91456..405254c7b3a9 100644 --- a/documentation/ref-manual/tasks.rst +++ b/documentation/ref-manual/tasks.rst @@ -120,7 +120,9 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. The :ref:`ref-tasks-deploy` task is not added as a task by default and consequently needs to be added manually. If you want the task to run after :ref:`ref-tasks-compile`, you can add it by doing -the following:: +the following: + +.. code-block:: bitbake addtask deploy after do_compile @@ -129,7 +131,9 @@ Adding :ref:`ref-tasks-deploy` after other tasks works the same way. .. note:: You do not need to add ``before do_build`` to the ``addtask`` command - (though it is harmless), because the :ref:`ref-classes-base` class contains the following:: + (though it is harmless), because the :ref:`ref-classes-base` class contains the following: + + .. code-block:: bitbake do_build[recrdeptask] += "do_deploy" @@ -335,7 +339,9 @@ and patch files needed to build the package. As mentioned earlier, the build system treats files whose file types are ``.patch`` and ``.diff`` as patch files. However, you can use the "apply=yes" parameter with the :term:`SRC_URI` statement to indicate any -file as a patch file:: +file as a patch file: + +.. code-block:: bitbake SRC_URI = " \ git://path_to_repo/some_package \ @@ -345,7 +351,9 @@ file as a patch file:: Conversely, if you have a file whose file type is ``.patch`` or ``.diff`` and you want to exclude it so that the :ref:`ref-tasks-patch` task does not apply it during the patch phase, you can use the "apply=no" parameter with the -:term:`SRC_URI` statement:: +:term:`SRC_URI` statement: + +.. code-block:: bitbake SRC_URI = " \ git://path_to_repo/some_package \ @@ -468,7 +476,9 @@ recipe and would be invoked with: $ bitbake -c listtasks recipename -A typical definition of a manually-called task would look like:: +A typical definition of a manually-called task would look like: + +.. code-block:: bitbake addtask listtasks do_listtasks[nostamp] = "1" From patchwork Wed Aug 26 01:34:48 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96337 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 6895AC61DC7 for ; Wed, 26 Aug 2026 01:35:22 +0000 (UTC) Received: from mail-qk1-f182.google.com (mail-qk1-f182.google.com [209.85.222.182]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.3463.1787708115070320448 for ; Tue, 25 Aug 2026 18:35:15 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=jMK7OvTe; spf=pass (domain: gmail.com, ip: 209.85.222.182, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f182.google.com with SMTP id af79cd13be357-930f618435cso22625385a.3 for ; Tue, 25 Aug 2026 18:35:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708114; x=1788312914; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=OFJSulw2RkqwGV2dzmcoVPk5cqc4QAoKI32qJxyYP4Y=; b=jMK7OvTedswZ3Sy1nEHTqlEXHL8i89jPThkth0jRsmeVIV+4uW4qzgn3C4dpMvzw4Z rzADwV1mRUb0lJOBFxXy3YlBebRcQlmBA84yrVmcOa/IjhhY2MIhKXyuHNMkOwVn0+HY THz4ra5sgOQemDx0Ml6AvfhRAqXJyXxkp2ED1CXCKGVxJfWLnLCyqCbXFscBWXSS+A3j eWV4h03UUTGp2MpRctJaXcvI0vowlQeno5//QjIJjEquY3cR62VDq1EStiYEikobcrcl zMWrTtQzY+ofVxYpv8uTVmNEp44B6v4G3300VUe4RuF+kojh5+9sey+Vy4ChbfW4+33G V7Hw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708114; x=1788312914; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=OFJSulw2RkqwGV2dzmcoVPk5cqc4QAoKI32qJxyYP4Y=; b=izJ7cP4/sFTQyw6DO630m6h4tVzmktz1ez6ANTLveL+ZxFOfk0yUKTkqjIAumuLKOw Z8LCpoVy8s+Hj1xeBjt8fXDjx92LF2E7OPvewl7kDnzWvKvPpyXB9MVWdi+SP4j+VoDE +91w+/o3QgvEMIC64JVz9jYzY6LpQQFWrJR9x9WggAHOYVFTsLtgDUiIWkJaKgm749QF jCCu+3hMC8TINY+WaOZDDm4sDDcATRntDJJRYkETO7/zLwShs2tBZgazanIWNpJ5i1Hx hgNRzl49lNPeCTS3FOVLimAU7+60aJY8q+C+xKlEcpe+gOaSFh5EkIyTTr+Res55Dj8a 8dKA== X-Gm-Message-State: AFuF++mr3V0u11r7o4NjmMkehLcFZlWiGMoTVXYsdENumKusGkx/QvpG lfnj1NQyt7aUbqyMzW1LdZjxLUYGzIxYk2TMn4NGcYM8PyZG48kgvsmLLJuEfG6i X-Gm-Gg: AR+sD10/kzUaliIn0f5hD0kib7Ttn72gReR3iLoGwV4BOu+54+lPU9jd8fdZNCPFMIV sdpQGsUVF4N/qZfc+H6dt6HXyWMpFM10uF7O0LkXsszpZpVigcWyJ9L/e1NdDWGGdlbEfN1naD1 tNk5/VMVBxy/sYBi+ATYMqSmpnIiPWmMGRq+gGTY5KJ0vM1PF4MlUcthqgPTHGVhMzhJNdhnNfJ BXsuNkbPx88ZGwimqddsxsUtj5vgKOH32oh9RvW8PE92IN+WWYW6eslcZPK/XhVGQfj9c7UqyLx vLuZwEBy6NF54BpyvDqnOp6a4SzMqE37Od0UY4j7xTKx4v0X7By4ykxIFLhi7FVC7nUT4av+W6m VXwXCtjL02LZceYcs3fcjwY/QNLDekxQNE2g6nawCK08GplRFn4gLMRp0JSmV/cRfLh+JZYz/D3 CaNgsZ+q5IFqww6I7iytFu73MsZxhj+E12gq9dKCLrS/Gnys0vXOohJ5TdPovziLxTBOOVoNGej auHzA1y+LKMAPyKwn6FWPTIYjZBDl8= X-Received: by 2002:a05:620a:4892:b0:930:b4f9:f327 with SMTP id af79cd13be357-93780445ef0mr250368285a.33.1787708112010; Tue, 25 Aug 2026 18:35:12 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:11 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 03/10] dev-manual: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:48 -0400 Message-ID: <20260826013502.2674000-4-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:22 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10348 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 176 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- documentation/dev-manual/bblock.rst | 4 +- documentation/dev-manual/bmaptool.rst | 4 +- documentation/dev-manual/build-quality.rst | 8 +- documentation/dev-manual/building.rst | 44 +++-- .../dev-manual/creating-fragments.rst | 6 +- .../dev-manual/custom-distribution.rst | 4 +- .../dev-manual/customizing-images.rst | 32 +++- documentation/dev-manual/debugging.rst | 40 +++-- documentation/dev-manual/device-manager.rst | 12 +- documentation/dev-manual/devtool.rst | 8 +- documentation/dev-manual/disk-space.rst | 4 +- .../dev-manual/error-reporting-tool.rst | 12 +- documentation/dev-manual/external-scm.rst | 20 ++- .../dev-manual/gobject-introspection.rst | 12 +- documentation/dev-manual/hashequivserver.rst | 12 +- documentation/dev-manual/init-manager.rst | 16 +- documentation/dev-manual/layers.rst | 56 ++++-- documentation/dev-manual/libraries.rst | 12 +- documentation/dev-manual/licenses.rst | 60 +++++-- .../dev-manual/limiting-resources.rst | 4 +- documentation/dev-manual/multiconfig.rst | 40 +++-- documentation/dev-manual/new-machine.rst | 4 +- documentation/dev-manual/new-recipe.rst | 160 +++++++++++++----- documentation/dev-manual/packages.rst | 44 +++-- .../dev-manual/poky-manual-setup.rst | 4 +- .../dev-manual/prebuilt-libraries.rst | 12 +- documentation/dev-manual/qemu.rst | 4 +- documentation/dev-manual/quilt.rst | 4 +- documentation/dev-manual/sbom.rst | 4 +- .../dev-manual/speeding-up-build.rst | 4 +- .../dev-manual/sstate-mirrors-setup.rst | 16 +- .../dev-manual/temporary-source-code.rst | 8 +- .../dev-manual/upgrading-recipes.rst | 12 +- documentation/dev-manual/wayland.rst | 8 +- documentation/dev-manual/x32-psabi.rst | 4 +- 35 files changed, 522 insertions(+), 176 deletions(-) diff --git a/documentation/dev-manual/bblock.rst b/documentation/dev-manual/bblock.rst index 605bb7565524..a6ca740c5123 100644 --- a/documentation/dev-manual/bblock.rst +++ b/documentation/dev-manual/bblock.rst @@ -87,7 +87,9 @@ Locking mechanism variables: :term:`SIGGEN_LOCKEDSIGS`, :term:`SIGGEN_LOCKEDSIGS_TYPES` and :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`. -In particular, ``bblock`` sets:: +In particular, ``bblock`` sets: + +.. code-block:: bitbake SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info" SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" diff --git a/documentation/dev-manual/bmaptool.rst b/documentation/dev-manual/bmaptool.rst index 29e7f0d2ebbd..8fd949eea2a2 100644 --- a/documentation/dev-manual/bmaptool.rst +++ b/documentation/dev-manual/bmaptool.rst @@ -29,7 +29,9 @@ that while this example uses a Wic image, you can use `bmaptool` to flash any type of image. Use these steps to flash an image using `bmaptool`: #. *Update your local.conf File:* You need to have the following set - in your ``local.conf`` file before building your image:: + in your ``local.conf`` file before building your image: + + .. code-block:: bitbake IMAGE_FSTYPES += "wic wic.bmap" diff --git a/documentation/dev-manual/build-quality.rst b/documentation/dev-manual/build-quality.rst index e9b066c4453f..6682122d4ee4 100644 --- a/documentation/dev-manual/build-quality.rst +++ b/documentation/dev-manual/build-quality.rst @@ -36,7 +36,9 @@ Enabling and Disabling Build History Build history is disabled by default. To enable it, add the following :term:`INHERIT` statement and set the :term:`BUILDHISTORY_COMMIT` variable to "1" at the end of your ``conf/local.conf`` file found in the -:term:`Build Directory`:: +:term:`Build Directory`: + +.. code-block:: bitbake INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "1" @@ -261,7 +263,9 @@ image. If you are just interested in this information and not interested in collecting specific package or SDK information, you can enable writing only image information without any history by adding the following to your ``conf/local.conf`` file found in the -:term:`Build Directory`:: +:term:`Build Directory`: + +.. code-block:: bitbake INHERIT += "buildhistory" BUILDHISTORY_COMMIT = "0" diff --git a/documentation/dev-manual/building.rst b/documentation/dev-manual/building.rst index 60cb22785725..cb073a2be5ad 100644 --- a/documentation/dev-manual/building.rst +++ b/documentation/dev-manual/building.rst @@ -230,14 +230,18 @@ To achieve this, you need to perform some additional steps: #. *Create a multiconfig for your Initramfs image:* You can perform the steps on ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" to create a separate multiconfig. For the sake of simplicity let's assume such multiconfig is called: ``initramfscfg.conf`` and - contains the variables:: + contains the variables: + + .. code-block:: bitbake TMPDIR = "${TOPDIR}/tmp-initramfscfg" TCLIBC = "musl" #. *Set additional Initramfs variables on your main configuration:* Additionally, on your main configuration (``local.conf``) you need to set the - variables:: + variables: + + .. code-block:: bitbake INITRAMFS_MULTICONFIG = "initramfscfg" INITRAMFS_DEPLOY_DIR_IMAGE = "${TOPDIR}/tmp-initramfscfg/deploy/images/${MACHINE}" @@ -416,7 +420,9 @@ instead of ``udev``. Use your ``local.conf`` file to make changes. For example, to eliminate ``udev`` and ``glib``, set the following in the local configuration -file:: +file: + +.. code-block:: bitbake VIRTUAL-RUNTIME_dev_manager = "" @@ -603,7 +609,9 @@ your tunings to best consider build times and package feed maintenance. machine-architecture dependent, make sure your recipe enables the "machine" package architecture through the :term:`MACHINE_ARCH` - variable:: + variable: + + .. code-block:: bitbake PACKAGE_ARCH = "${MACHINE_ARCH}" @@ -611,7 +619,9 @@ your tunings to best consider build times and package feed maintenance. specifically enable a package architecture through the :term:`PACKAGE_ARCH`, The OpenEmbedded build system defaults to the - :term:`TUNE_PKGARCH` setting:: + :term:`TUNE_PKGARCH` setting: + + .. code-block:: bitbake PACKAGE_ARCH = "${TUNE_PKGARCH}" @@ -707,13 +717,17 @@ the external directory and use it as is, not copy it. To build from software that comes from an external source, all you need to do is inherit the :ref:`ref-classes-externalsrc` class and then set the :term:`EXTERNALSRC` variable to point to your external source code. Here -are the statements to put in your ``local.conf`` file:: +are the statements to put in your ``local.conf`` file: + +.. code-block:: bitbake INHERIT += "externalsrc" EXTERNALSRC:pn-myrecipe = "path-to-your-source-tree" This next example shows how to accomplish the same thing by setting -:term:`EXTERNALSRC` in the recipe itself or in the recipe's append file:: +:term:`EXTERNALSRC` in the recipe itself or in the recipe's append file: + +.. code-block:: bitbake EXTERNALSRC = "path" EXTERNALSRC_BUILD = "path" @@ -729,7 +743,9 @@ directory separate from the external source directory as specified by to have the source built in the same directory in which it resides, or some other nominated directory, you can set :term:`EXTERNALSRC_BUILD` -to point to that directory:: +to point to that directory: + +.. code-block:: bitbake EXTERNALSRC_BUILD:pn-myrecipe = "path-to-your-source-tree" @@ -757,7 +773,9 @@ Follow these steps to populate your Downloads directory: an empty location or one that does not yet exist. #. *Generate Tarballs of the Source Git Repositories:* Edit your - ``local.conf`` configuration file as follows:: + ``local.conf`` configuration file as follows: + + .. code-block:: bitbake DL_DIR = "/home/your-download-dir/" BB_GENERATE_MIRROR_TARBALLS = "1" @@ -795,7 +813,9 @@ directory: #. *Using Local Files Only:* Inside your ``local.conf`` file, add the :term:`SOURCE_MIRROR_URL` variable, inherit the :ref:`ref-classes-own-mirrors` class, and add the - :term:`BB_NO_NETWORK` variable to your ``local.conf``:: + :term:`BB_NO_NETWORK` variable to your ``local.conf``: + + .. code-block:: bitbake SOURCE_MIRROR_URL ?= "file:///home/your-download-dir/" INHERIT += "own-mirrors" @@ -824,7 +844,9 @@ directory: The offline build does not work if recipes attempt to find the latest version of software by setting :term:`SRCREV` to - ``${``\ :term:`AUTOREV`\ ``}``:: + ``${``\ :term:`AUTOREV`\ ``}``: + + .. code-block:: bitbake SRCREV = "${AUTOREV}" diff --git a/documentation/dev-manual/creating-fragments.rst b/documentation/dev-manual/creating-fragments.rst index 8dabd599f13f..ea9ad8eb23dc 100644 --- a/documentation/dev-manual/creating-fragments.rst +++ b/documentation/dev-manual/creating-fragments.rst @@ -61,7 +61,7 @@ Build System`: After creating these variables, our custom fragment should look like the following: -.. code-block:: +.. code-block:: bitbake :caption: custom-fragment.conf BB_CONF_FRAGMENT_SUMMARY = "This fragment sets a limit of 4 bitbake threads and 4 parsing threads" @@ -71,7 +71,7 @@ following: For now, our fragment does not have any additional configuration statement. Let's add the following assignments to our fragment: -.. code-block:: +.. code-block:: bitbake :caption: custom-fragment.conf (continued) BB_NUMBER_THREADS = "4" @@ -123,7 +123,7 @@ Adding new :term:`Built-in Fragments ` can be done by appending the :term:`OE_FRAGMENTS_BUILTIN` variable from your :term:`layer` configuration file: -.. code-block:: +.. code-block:: bitbake :caption: layer.conf OE_FRAGMENTS_BUILTIN:append = " custom-builtin-fragment:CUSTOM_VARIABLE" diff --git a/documentation/dev-manual/custom-distribution.rst b/documentation/dev-manual/custom-distribution.rst index 4dafd2725557..1146d5313102 100644 --- a/documentation/dev-manual/custom-distribution.rst +++ b/documentation/dev-manual/custom-distribution.rst @@ -87,7 +87,9 @@ layer. The following steps provide some more detail: file in the :term:`Build Directory`, set your :term:`DISTRO` variable to point to your distribution's configuration file. For example, if your distribution's configuration file is named ``mydistro.conf``, then - you point to it as follows:: + you point to it as follows: + + .. code-block:: bitbake DISTRO = "mydistro" diff --git a/documentation/dev-manual/customizing-images.rst b/documentation/dev-manual/customizing-images.rst index 6eed9ef56a80..b715f83990fa 100644 --- a/documentation/dev-manual/customizing-images.rst +++ b/documentation/dev-manual/customizing-images.rst @@ -18,7 +18,9 @@ variable changes are in effect for every build and consequently affect all images, which might not be what you require. To add a package to your image using the local configuration file, use -the :term:`IMAGE_INSTALL` variable with the ``:append`` operator:: +the :term:`IMAGE_INSTALL` variable with the ``:append`` operator: + +.. code-block:: bitbake IMAGE_INSTALL:append = " strace" @@ -36,7 +38,9 @@ takes effect. As shown in its simplest use, ``IMAGE_INSTALL:append`` affects all images. It is possible to extend the syntax so that the variable applies -to a specific image only. Here is an example:: +to a specific image only. Here is an example: + +.. code-block:: bitbake IMAGE_INSTALL:append:pn-core-image-minimal = " strace" @@ -105,7 +109,9 @@ Customizing Images Using Custom .bb Files You can also customize an image by creating a custom recipe that defines additional software as part of the image. The following example shows -the form for the two lines you need:: +the form for the two lines you need: + +.. code-block:: bitbake IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2" inherit core-image @@ -120,7 +126,9 @@ The other method for creating a custom image is to base it on an existing image. For example, if you want to create an image based on ``core-image-sato`` but add the additional package ``strace`` to the image, copy the ``meta/recipes-sato/images/core-image-sato.bb`` to a new -``.bb`` and add the following line to the end of the copy:: +``.bb`` and add the following line to the end of the copy: + +.. code-block:: bitbake IMAGE_INSTALL += "strace" @@ -151,7 +159,9 @@ in the ``packagegroup-base.bb`` recipe. Here is a short, fabricated example showing the same basic pieces for a hypothetical packagegroup defined in ``packagegroup-custom.bb``, where the variable :term:`PN` is the standard way to abbreviate the reference to -the full packagegroup name ``packagegroup-custom``:: +the full packagegroup name ``packagegroup-custom``: + +.. code-block:: bitbake DESCRIPTION = "My Custom Package Groups" @@ -193,11 +203,15 @@ configured hostname written to ``/etc/hostname`` is "qemux86". You can customize this name by altering the value of the "hostname" variable in the ``base-files`` recipe using either an append file or a -configuration file. Use the following in an append file:: +configuration file. Use the following in an append file: + +.. code-block:: bitbake hostname = "myhostname" -Use the following in a configuration file:: +Use the following in a configuration file: + +.. code-block:: bitbake hostname:pn-base-files = "myhostname" @@ -212,7 +226,9 @@ you can easily reset the default hostname. Another point of interest is that if you unset the variable, the image will have no default hostname in the filesystem. Here is an example that -unsets the variable in a configuration file:: +unsets the variable in a configuration file: + +.. code-block:: bitbake hostname:pn-base-files = "" diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index 3afc17ad4ba2..6ee101721ef8 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst @@ -628,7 +628,9 @@ in the log, use the "debug" loglevel. Here is an example written in Python. The code handles logging for a function that determines the number of tasks needed to be run. See the ":ref:`ref-tasks-listtasks`" -section for additional information:: +section for additional information: + +.. code-block:: bitbake python do_listtasks() { bb.debug(2, "Starting to figure out the task list") @@ -654,7 +656,9 @@ The syntax you use for recipes written in Bash is similar to that of recipes written in Python described in the previous section. Here is an example written in Bash. The code logs the progress of -the ``do_my_function`` function:: +the ``do_my_function`` function: + +.. code-block:: bitbake do_my_function() { bbdebug 2 "Running do_my_function" @@ -861,7 +865,9 @@ The final thing you need to do to implement the fix in the build is to update the "neard" recipe (i.e. ``neard-0.14.bb``) so that the :term:`SRC_URI` statement includes the patch file. The recipe file is in the folder above the patch. Here -is what the edited :term:`SRC_URI` statement would look like:: +is what the edited :term:`SRC_URI` statement would look like: + +.. code-block:: bitbake SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \ file://neard.in \ @@ -943,7 +949,9 @@ To run a ``debuginfod`` server, you need to do the following: (it already is in :term:`OpenEmbedded-Core (OE-Core)` defaults and :term:`Poky` reference distribution). - If not, set in your distro config file or in ``local.conf``:: + If not, set in your distro config file or in ``local.conf``: + + .. code-block:: bitbake DISTRO_FEATURES:append = " debuginfod" @@ -1010,7 +1018,9 @@ debugger. #. *Configure your build system to construct the companion debug filesystem:* - In your ``local.conf`` file, set the following:: + In your ``local.conf`` file, set the following: + + .. code-block:: bitbake IMAGE_GEN_DEBUGFS = "1" IMAGE_FSTYPES_DEBUGFS = "tar.bz2" @@ -1029,7 +1039,9 @@ debugger. #. *Configure the system to include gdbserver in the target filesystem:* - Make the following addition in your ``local.conf`` file:: + Make the following addition in your ``local.conf`` file: + + .. code-block:: bitbake EXTRA_IMAGE_FEATURES:append = " tools-debug" @@ -1165,17 +1177,23 @@ debug on the target hardware. To support this kind of debugging, you need do the following: - Ensure that GDB is on the target. You can do this by making - the following addition to your ``local.conf`` file:: + the following addition to your ``local.conf`` file: + + .. code-block:: bitbake EXTRA_IMAGE_FEATURES:append = " tools-debug" - Ensure that debug symbols are present. You can do so by adding the - corresponding ``-dbg`` package to :term:`IMAGE_INSTALL`:: + corresponding ``-dbg`` package to :term:`IMAGE_INSTALL`: + + .. code-block:: bitbake IMAGE_INSTALL:append = " packagename-dbg" Alternatively, you can add the following to ``local.conf`` to include - all the debug symbols:: + all the debug symbols: + + .. code-block:: bitbake EXTRA_IMAGE_FEATURES:append = " dbg-pkgs" @@ -1185,7 +1203,9 @@ To support this kind of debugging, you need do the following: of optimization used by the compiler. For example, when adding the following line to your ``local.conf`` file, you will reduce optimization from :term:`FULL_OPTIMIZATION` of "-O2" to :term:`DEBUG_OPTIMIZATION` - of "-O -fno-omit-frame-pointer":: + of "-O -fno-omit-frame-pointer": + + .. code-block:: bitbake DEBUG_BUILD = "1" diff --git a/documentation/dev-manual/device-manager.rst b/documentation/dev-manual/device-manager.rst index 49fc785feccb..1fa572090804 100644 --- a/documentation/dev-manual/device-manager.rst +++ b/documentation/dev-manual/device-manager.rst @@ -23,7 +23,9 @@ Using Persistent and Pre-Populated ``/dev`` To use the static method for device population, you need to set the :term:`USE_DEVFS` variable to "0" -as follows:: +as follows: + +.. code-block:: bitbake USE_DEVFS = "0" @@ -35,7 +37,9 @@ machine or distro configuration file. Alternatively, you can set this variable in your ``local.conf`` configuration file. If you do not define the :term:`IMAGE_DEVICE_TABLES` variable, the default -``device_table-minimal.txt`` is used:: +``device_table-minimal.txt`` is used: + +.. code-block:: bitbake IMAGE_DEVICE_TABLES = "device_table-mymachine.txt" @@ -47,7 +51,9 @@ Using ``devtmpfs`` and a Device Manager To use the dynamic method for device population, you need to use (or be sure to set) the :term:`USE_DEVFS` -variable to "1", which is the default:: +variable to "1", which is the default: + +.. code-block:: bitbake USE_DEVFS = "1" diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst index d67f22277342..2078678a855e 100644 --- a/documentation/dev-manual/devtool.rst +++ b/documentation/dev-manual/devtool.rst @@ -981,7 +981,9 @@ the :term:`DEPENDS` variable in the original recipe to include the new recipe. If you need to add runtime dependencies, you can do so by adding the -following to your recipe:: +following to your recipe: + +.. code-block:: bitbake RDEPENDS:${PN} += "dependency1 dependency2 ..." @@ -1062,7 +1064,9 @@ mind: the command line, add the variable setting to :term:`EXTRA_OEMAKE` or :term:`PACKAGECONFIG_CONFARGS` - within the recipe. Here is an example using :term:`EXTRA_OEMAKE`:: + within the recipe. Here is an example using :term:`EXTRA_OEMAKE`: + + .. code-block:: bitbake EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" diff --git a/documentation/dev-manual/disk-space.rst b/documentation/dev-manual/disk-space.rst index ba3afa5a2cab..efc7529d9263 100644 --- a/documentation/dev-manual/disk-space.rst +++ b/documentation/dev-manual/disk-space.rst @@ -8,7 +8,9 @@ Conserving Disk Space During Builds To help conserve disk space during builds, you can add the following statement to your project's ``local.conf`` configuration file found in -the :term:`Build Directory`:: +the :term:`Build Directory`: + +.. code-block:: bitbake INHERIT += "rm_work" diff --git a/documentation/dev-manual/error-reporting-tool.rst b/documentation/dev-manual/error-reporting-tool.rst index 30d1ce2b315b..3b765e30db51 100644 --- a/documentation/dev-manual/error-reporting-tool.rst +++ b/documentation/dev-manual/error-reporting-tool.rst @@ -28,14 +28,18 @@ Enabling and Using the Tool By default, the error reporting tool is disabled. You can enable it by inheriting the :ref:`ref-classes-report-error` class by adding the following statement to the end of your ``local.conf`` file in your -:term:`Build Directory`:: +:term:`Build Directory`: + +.. code-block:: bitbake INHERIT += "report-error" By default, the error reporting feature stores information in ``${``\ :term:`LOG_DIR`\ ``}/error-report``. However, you can specify a directory to use by adding the following to -your ``local.conf`` file:: +your ``local.conf`` file: + +.. code-block:: bitbake ERR_REPORT_DIR = "path" @@ -70,7 +74,9 @@ Disabling the Tool To disable the error reporting feature, simply remove or comment out the following statement from the end of your ``local.conf`` file in your -:term:`Build Directory`:: +:term:`Build Directory`: + +.. code-block:: bitbake INHERIT += "report-error" diff --git a/documentation/dev-manual/external-scm.rst b/documentation/dev-manual/external-scm.rst index e7ab8a4c6b9e..dfdd6853ff68 100644 --- a/documentation/dev-manual/external-scm.rst +++ b/documentation/dev-manual/external-scm.rst @@ -13,7 +13,9 @@ Subversion (SVN) and Git. To enable this behavior, the :term:`PV` of the recipe needs to include a ``+`` sign in its assignment. -Here is an example:: +Here is an example: + +.. code-block:: bitbake PV = "1.2.3+git" @@ -21,7 +23,9 @@ Here is an example:: during the packaging phase. Then, you can add the following to your -``local.conf``:: +``local.conf``: + +.. code-block:: bitbake SRCREV:pn-PN = "${AUTOREV}" @@ -29,17 +33,23 @@ Then, you can add the following to your which you want to enable automatic source revision updating. If you do not want to update your local configuration file, you can add -the following directly to the recipe to finish enabling the feature:: +the following directly to the recipe to finish enabling the feature: + +.. code-block:: bitbake SRCREV = "${AUTOREV}" The Yocto Project provides a distribution named ``poky-bleeding``, whose -configuration file contains the line:: +configuration file contains the line: + +.. code-block:: bitbake require conf/distro/include/poky-floating-revisions.inc This line pulls in the listed include file that defines the set of -AUTOREV-enabled recipes:: +AUTOREV-enabled recipes: + +.. code-block:: bitbake INHERIT += "poky-bleeding" diff --git a/documentation/dev-manual/gobject-introspection.rst b/documentation/dev-manual/gobject-introspection.rst index 8203f17f0177..c57b0a302227 100644 --- a/documentation/dev-manual/gobject-introspection.rst +++ b/documentation/dev-manual/gobject-introspection.rst @@ -52,7 +52,9 @@ library package involves the following: #. Try to build the recipe. If you encounter build errors that look like something is unable to find ``.so`` libraries, check where these libraries are located in the source tree and add the following to the - recipe:: + recipe: + + .. code-block:: bitbake GIR_EXTRA_LIBS_PATH = "${B}/something/.libs" @@ -82,7 +84,9 @@ perhaps QEMU does not work on your build host and target architecture combination. If so, you can use either of the following methods to disable GIR file generations: -- Add the following to your distro configuration:: +- Add the following to your distro configuration: + + .. code-block:: bitbake DISTRO_FEATURES_OPTED_OUT = "gobject-introspection-data" @@ -90,7 +94,9 @@ disable GIR file generations: QEMU but will still enable building introspection tools and libraries (i.e. building them does not require the use of QEMU). -- Add the following to your machine configuration:: +- Add the following to your machine configuration: + + .. code-block:: bitbake MACHINE_FEATURES_OPTED_OUT = "qemu-usermode" diff --git a/documentation/dev-manual/hashequivserver.rst b/documentation/dev-manual/hashequivserver.rst index 75b77c30b944..3c1f813cf95f 100644 --- a/documentation/dev-manual/hashequivserver.rst +++ b/documentation/dev-manual/hashequivserver.rst @@ -79,7 +79,9 @@ Yocto Project Build Setup ========================= To use the server started in the previous section, set the following variables -in a :term:`configuration file`:: +in a :term:`configuration file`: + +.. code-block:: bitbake BB_HASHSERVE = "" BB_SIGNATURE_HANDLER = "OEEquivHash" @@ -91,7 +93,9 @@ See the documentation of :term:`BB_SIGNATURE_HANDLER` for more details on this variable. You can optionally specify an upstream server with :term:`BB_HASHSERVE_UPSTREAM` -variable. For example:: +variable. For example: + +.. code-block:: bitbake BB_HASHSERVE_UPSTREAM = "wss://hashserv.yoctoproject.org/ws" @@ -101,7 +105,9 @@ This will make the local server pull hashes from the upstream server. The To output debugging information on what is happening with Hash Equivalence when builds are started, you can configure :term:`BitBake` logging as follows from a -:term:`configuration file`:: +:term:`configuration file`: + +.. code-block:: bitbake BB_LOGCONFIG = "hashequiv.json" diff --git a/documentation/dev-manual/init-manager.rst b/documentation/dev-manual/init-manager.rst index c9d344a88bf3..51644df2dd51 100644 --- a/documentation/dev-manual/init-manager.rst +++ b/documentation/dev-manual/init-manager.rst @@ -54,7 +54,9 @@ Using SysVinit with udev ========================= SysVinit with the udev device manager corresponds to the -default setting in :term:`Poky`. This corresponds to setting:: +default setting in :term:`Poky`. This corresponds to setting: + +.. code-block:: bitbake INIT_MANAGER = "sysvinit" @@ -63,7 +65,9 @@ Using BusyBox init with BusyBox mdev BusyBox init with BusyBox mdev is the simplest and lightest solution for small root filesystems. All you need is BusyBox, which most systems -have anyway:: +have anyway: + +.. code-block:: bitbake INIT_MANAGER = "mdev-busybox" @@ -72,7 +76,9 @@ Using systemd The last option is to use systemd together with the udev device manager. This is the most powerful and versatile solution, especially -for more complex systems:: +for more complex systems: + +.. code-block:: bitbake INIT_MANAGER = "systemd" @@ -103,7 +109,9 @@ Using systemd-journald without a traditional syslog daemon Counter-intuitively, ``systemd-journald`` is not a syslog runtime or provider, and the proper way to use ``systemd-journald`` as your sole logging mechanism is to effectively disable syslog entirely by setting these variables in your distribution -configuration file:: +configuration file: + +.. code-block:: bitbake VIRTUAL-RUNTIME_syslog = "" VIRTUAL-RUNTIME_base-utils-syslog = "" diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst index 3937c54ad2cc..a15fce6b93ba 100644 --- a/documentation/dev-manual/layers.rst +++ b/documentation/dev-manual/layers.rst @@ -212,7 +212,9 @@ following list: machine "one". To do so, you use an append file named ``base-files.bbappend`` and create a dependency on "foo" by altering the :term:`DEPENDS` - variable:: + variable: + + .. code-block:: bitbake DEPENDS = "foo" @@ -225,12 +227,16 @@ following list: ``foo``. To make sure your changes apply only when building machine "one", - use a machine override with the :term:`DEPENDS` statement:: + use a machine override with the :term:`DEPENDS` statement: + + .. code-block:: bitbake DEPENDS:one = "foo" You should follow the same strategy when using ``:append`` - and ``:prepend`` operations:: + and ``:prepend`` operations: + + .. code-block:: bitbake DEPENDS:append:one = " foo" DEPENDS:prepend:one = "foo " @@ -238,7 +244,9 @@ following list: As an actual example, here's a snippet from the generic kernel include file ``linux-yocto.inc``, wherein the kernel compile and link options are adjusted in the - case of a subset of the supported architectures:: + case of a subset of the supported architectures: + + .. code-block:: bitbake DEPENDS:append:aarch64 = " libgcc" KERNEL_CC:append:aarch64 = " ${TOOLCHAIN_OPTIONS}" @@ -260,7 +268,9 @@ following list: file, you can use an append file to cause the build to use your own version of the file. For example, an append file in your layer at ``meta-one/recipes-core/base-files/base-files.bbappend`` could - extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows:: + extend :term:`FILESPATH` using :term:`FILESEXTRAPATHS` as follows: + + .. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${BPN}:" @@ -571,7 +581,9 @@ during the build. Here is the append file, which is named ``formfactor_0.0.bbappend`` and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The -file is in the layer at ``recipes-bsp/formfactor``:: +file is in the layer at ``recipes-bsp/formfactor``: + +.. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" @@ -619,7 +631,9 @@ As another example, consider the main ``xserver-xf86-config`` recipe and a corresponding ``xserver-xf86-config`` append file both from :term:`OpenEmbedded-Core (OE-Core)`. Here is the main ``xserver-xf86-config`` recipe, which is named ``xserver-xf86-config_0.1.bb`` and located in the "meta" layer at -``meta/recipes-graphics/xorg-xserver``:: +``meta/recipes-graphics/xorg-xserver``: + +.. code-block:: bitbake SUMMARY = "X.Org X server configuration file" HOMEPAGE = "http://www.x.org" @@ -645,7 +659,9 @@ corresponding ``xserver-xf86-config`` append file both from Here is the append file, which is named ``xserver-xf86-config_%.bbappend`` and is from the Raspberry Pi BSP Layer named ``meta-raspberrypi``. The -file is in the layer at ``recipes-graphics/xorg-xserver``:: +file is in the layer at ``recipes-graphics/xorg-xserver``: + +.. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" @@ -685,7 +701,9 @@ build system to calculate it based on the layer's dependencies. To specify the layer's priority manually, use the :term:`BBFILE_PRIORITY` -variable and append the layer's root name:: +variable and append the layer's root name: + +.. code-block:: bitbake BBFILE_PRIORITY_mylayer = "1" @@ -753,14 +771,18 @@ for the kernel only if our feature ``mylayer-kernel`` is part of the PREFERRED_PROVIDER_virtual/kernel = "linux-custom" -#. Provide a path to this include file in your ``layer.conf``:: +#. Provide a path to this include file in your ``layer.conf``: + + .. code-block:: bitbake META_MYLAYER_KERNEL_PROVIDER_PATH = "${LAYERDIR}/conf/distro/include/mylayer-kernel-provider.inc" #. Create a new class in ``meta-mylayer/classes-global/``, for example a class ``meta-mylayer-cfg.bbclass``. Make it conditionally require the file ``mylayer-kernel-provider.inc`` defined above, using the variable - ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``:: + ``META_MYLAYER_KERNEL_PROVIDER_PATH`` defined in ``layer.conf``: + + .. code-block:: bitbake require ${@bb.utils.contains('DISTRO_FEATURES', 'mylayer-kernel', '${META_MYLAYER_KERNEL_PROVIDER_PATH}', '', d)} @@ -773,7 +795,9 @@ for the kernel only if our feature ``mylayer-kernel`` is part of the ``bb.utils.contains`` returns an empty string. #. Back to your ``layer.conf`` file, add the class ``meta-mylayer-cfg`` class to - the :term:`USER_CLASSES` variable:: + the :term:`USER_CLASSES` variable: + + .. code-block:: bitbake USER_CLASSES:append = " meta-mylayer-cfg" @@ -846,7 +870,9 @@ The following list describes the available commands: variable values, you need to tidy these up yourself. Consider the following example. Here, the ``bitbake-layers`` command adds the line ``#### bbappended ...`` so that you know where the following - lines originate:: + lines originate: + + .. code-block:: bitbake ... DESCRIPTION = "A useful utility" @@ -860,7 +886,9 @@ The following list describes the available commands: EXTRA_OECONF += "--enable-somethingelse" - Ideally, you would tidy up these utilities as follows:: + Ideally, you would tidy up these utilities as follows: + + .. code-block:: bitbake ... DESCRIPTION = "Customized utility" diff --git a/documentation/dev-manual/libraries.rst b/documentation/dev-manual/libraries.rst index 160734729183..46ce2856158e 100644 --- a/documentation/dev-manual/libraries.rst +++ b/documentation/dev-manual/libraries.rst @@ -38,7 +38,9 @@ library files. static library files through ``${PN}-dev``. Here is a small part of the BitBake configuration file, where you can see -how the static library files are defined:: +how the static library files are defined: + +.. code-block:: bitbake PACKAGES = "${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" @@ -118,7 +120,9 @@ Using Multilib After you have set up the recipes, you need to define the actual combination of multiple libraries you want to build. You accomplish this through your ``local.conf`` configuration file in the -:term:`Build Directory`. An example configuration would be as follows:: +:term:`Build Directory`. An example configuration would be as follows: + +.. code-block:: bitbake MACHINE = "qemux86-64" require conf/multilib.conf @@ -231,7 +235,9 @@ you have other recipes that depend on a given library, you need to use the :term:`DEPENDS` variable to create the dependency. Continuing with the same example, if you want to have a recipe depend on the 1.8 version of the ``clutter`` library, use -the following in your recipe:: +the following in your recipe: + +.. code-block:: bitbake DEPENDS = "clutter-1.8" diff --git a/documentation/dev-manual/licenses.rst b/documentation/dev-manual/licenses.rst index 774b5db23517..132a848b4660 100644 --- a/documentation/dev-manual/licenses.rst +++ b/documentation/dev-manual/licenses.rst @@ -28,7 +28,9 @@ Specifying the ``LIC_FILES_CHKSUM`` Variable The :term:`LIC_FILES_CHKSUM` variable contains checksums of the license text in the source code for the recipe. Here is an example of how to -specify :term:`LIC_FILES_CHKSUM`:: +specify :term:`LIC_FILES_CHKSUM`: + +.. code-block:: bitbake LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ @@ -51,7 +53,9 @@ variable as the default directory when searching files listed in :term:`LIC_FILES_CHKSUM`. The previous example employs the default directory. -Consider this next example:: +Consider this next example: + +.. code-block:: bitbake LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ md5=bb14ed3c4cda583abc85401304b5cd4e" @@ -113,18 +117,24 @@ are defined on a recipe-by-recipe basis through the :term:`LICENSE_FLAGS` variable definition in the affected recipe. For instance, the ``meta/recipes-multimedia/gstreamer/gstreamer1.0-plugins-ugly`` recipe of -:term:`OpenEmbedded-Core (OE-Core)` contains the following statement:: +:term:`OpenEmbedded-Core (OE-Core)` contains the following statement: + +.. code-block:: bitbake LICENSE_FLAGS = "commercial" Here is a slightly more complicated example that contains both an explicit recipe -name and version (after variable expansion):: +name and version (after variable expansion): + +.. code-block:: bitbake LICENSE_FLAGS = "license_${PN}_${PV}" It is possible to give more details about a specific license -using flags on the :term:`LICENSE_FLAGS_DETAILS` variable:: +using flags on the :term:`LICENSE_FLAGS_DETAILS` variable: + +.. code-block:: bitbake LICENSE_FLAGS_DETAILS[my-eula-license] = "For further details, see https://example.com/eula." @@ -142,7 +152,9 @@ could add either the string "commercial_gst-plugins-ugly" or the more general string "commercial" to :term:`LICENSE_FLAGS_ACCEPTED`. See the ":ref:`dev-manual/licenses:license flag matching`" section for a full explanation of how :term:`LICENSE_FLAGS` matching works. Here is the -example:: +example: + +.. code-block:: bitbake LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly" @@ -150,7 +162,9 @@ Likewise, to additionally enable the package built from the recipe containing ``LICENSE_FLAGS = "license_${PN}_${PV}"``, and assuming that the actual recipe name was ``emgd_1.10.bb``, the following string would enable that package as well as the original ``gst-plugins-ugly`` -package:: +package: + +.. code-block:: bitbake LICENSE_FLAGS_ACCEPTED = "commercial_gst-plugins-ugly license_emgd_1.10" @@ -162,7 +176,9 @@ or characters. A partial string will match any license that contains the given string as the first portion of its license. For example, the following value will also match both of the packages previously mentioned as well as any other packages that have licenses -starting with "commercial" or "license":: +starting with "commercial" or "license": + +.. code-block:: bitbake LICENSE_FLAGS_ACCEPTED = "commercial license" @@ -207,7 +223,9 @@ For example, simply specifying the string "commercial" in the "commercial" such as "commercial_foo" and "commercial_bar", which are the strings the build system automatically generates for hypothetical recipes named "foo" and "bar" assuming those recipes simply -specify the following:: +specify the following: + +.. code-block:: bitbake LICENSE_FLAGS = "commercial" @@ -245,13 +263,17 @@ Other Variables Related to Commercial Licenses There are other helpful variables related to commercial license handling, defined in the -``meta/conf/distro/include/default-distrovars.inc`` file in :term:`OpenEmbedded-Core (OE-Core)`:: +``meta/conf/distro/include/default-distrovars.inc`` file in :term:`OpenEmbedded-Core (OE-Core)`: + +.. code-block:: bitbake COMMERCIAL_AUDIO_PLUGINS ?= "" COMMERCIAL_VIDEO_PLUGINS ?= "" If you want to enable these components, you can do so by making sure you have -statements similar to the following in your ``local.conf`` configuration file:: +statements similar to the following in your ``local.conf`` configuration file: + +.. code-block:: bitbake COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ gst-plugins-ugly-mpegaudioparse" @@ -262,7 +284,9 @@ statements similar to the following in your ``local.conf`` configuration file:: Of course, you could also create a matching list for those components using the more general "commercial" string in the :term:`LICENSE_FLAGS_ACCEPTED` variable, but that would also enable all the other packages with :term:`LICENSE_FLAGS` -containing "commercial", which you may or may not want:: +containing "commercial", which you may or may not want: + +.. code-block:: bitbake LICENSE_FLAGS_ACCEPTED = "commercial" @@ -361,7 +385,9 @@ create them with various levels of compliance in mind. One way of doing this (but certainly not the only way) is to release just the source as a tarball. You can do this by adding the following to -the ``local.conf`` file found in the :term:`Build Directory`:: +the ``local.conf`` file found in the :term:`Build Directory`: + +.. code-block:: bitbake INHERIT += "archiver" ARCHIVER_MODE[src] = "original" @@ -417,7 +443,9 @@ One requirement that is often overlooked is inclusion of license text. This requirement also needs to be dealt with prior to generating the final image. Some licenses require the license text to accompany the binary. You can achieve this by adding the following to your -``local.conf`` file:: +``local.conf`` file: + +.. code-block:: bitbake COPY_LIC_MANIFEST = "1" COPY_LIC_DIRS = "1" @@ -528,7 +556,9 @@ variable. Using this variable also avoids QA errors when you use a non-common, non-CLOSED license in a recipe. Here is an example that uses the ``LICENSE.Abilis.txt`` file as -the license from the fetched source:: +the license from the fetched source: + +.. code-block:: bitbake NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" diff --git a/documentation/dev-manual/limiting-resources.rst b/documentation/dev-manual/limiting-resources.rst index 9b3db0a59514..8101a9d1ea3b 100644 --- a/documentation/dev-manual/limiting-resources.rst +++ b/documentation/dev-manual/limiting-resources.rst @@ -38,7 +38,9 @@ details. If you want to have a different limit from the rest of the build for a recipe, it is also possible to achieve with the following line added to your - ``local.conf`` :term:`configuration file`:: + ``local.conf`` :term:`configuration file`: + + .. code-block:: bitbake PARALLEL_MAKE:pn-linux-yocto = "-j4" diff --git a/documentation/dev-manual/multiconfig.rst b/documentation/dev-manual/multiconfig.rst index 71fe542efbbd..356dcb768def 100644 --- a/documentation/dev-manual/multiconfig.rst +++ b/documentation/dev-manual/multiconfig.rst @@ -61,7 +61,9 @@ Follow these steps to set up and execute multiple configuration builds: Here is an example showing the minimal statements needed in a :term:`configuration file` named ``qemux86.conf`` for a ``qemux86`` target - whose temporary build directory is ``tmp-qemux86``:: + whose temporary build directory is ``tmp-qemux86``: + + .. code-block:: bitbake MACHINE = "qemux86" TMPDIR .= "-${BB_CURRENT_MC}" @@ -77,7 +79,9 @@ Follow these steps to set up and execute multiple configuration builds: variable in your ``conf/local.conf`` configuration file to specify each multiconfig. Continuing with the example from the previous figure, the :term:`BBMULTICONFIG` variable needs to enable two - multiconfigs: "x86" and "arm" by specifying each configuration file:: + multiconfigs: "x86" and "arm" by specifying each configuration file: + + .. code-block:: bitbake BBMULTICONFIG = "x86 arm" @@ -134,13 +138,17 @@ essentially that the To enable dependencies in a multiple configuration build, you must declare the dependencies in the recipe using the following statement -form:: +form: + +.. code-block:: bitbake task_or_package[mcdepends] = "mc:from_multiconfig:to_multiconfig:recipe_name:task_on_which_to_depend" To better show how to use this statement, consider the example scenario from the first paragraph of this section. The following statement needs -to be added to the recipe that builds the ``core-image-sato`` image:: +to be added to the recipe that builds the ``core-image-sato`` image: + +.. code-block:: bitbake do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_rootfs" @@ -161,7 +169,9 @@ dependency, BitBake also executes through the :ref:`ref-tasks-rootfs` task for t Having a recipe depend on the root filesystem of another build might not seem that useful. Consider this change to the statement in the -``core-image-sato`` recipe:: +``core-image-sato`` recipe: + +.. code-block:: bitbake do_image[mcdepends] = "mc:x86:arm:core-image-minimal:do_image" @@ -192,7 +202,9 @@ Suggested best practices the deployed item based on :term:`TMPDIR`. The :ref:`ref-tasks-install` and :ref:`ref-tasks-deploy` tasks should look - like this:: + like this: + + .. code-block:: bitbake do_install() { install -m 0644 ${TMPDIR}-/tmp/deploy/images//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//my-firmware.elf" FIRMWARE_FILE[vardepsexclude] += "TMPDIR" @@ -302,7 +320,9 @@ cache `. Additionally, ```` should be replaced by the :term:`MACHINE` for which we are building in the baremetal-firmware context. -We can then add a :ref:`ref-tasks-install` task to ``my-parent-firmware``:: +We can then add a :ref:`ref-tasks-install` task to ``my-parent-firmware``: + +.. code-block:: bitbake do_install() { install -Dm 0644 ${FIRMWARE_FILE} ${D}/lib/firmware/my-firmware.elf diff --git a/documentation/dev-manual/new-machine.rst b/documentation/dev-manual/new-machine.rst index b4d29027be12..c08e359a2e64 100644 --- a/documentation/dev-manual/new-machine.rst +++ b/documentation/dev-manual/new-machine.rst @@ -77,7 +77,9 @@ of adding a suitable ``defconfig`` file. The file needs to be added into a location similar to ``defconfig`` files used for other machines in a given kernel recipe. A possible way to do this is by listing the file in the :term:`SRC_URI` and adding the machine to the expression in -:term:`COMPATIBLE_MACHINE`:: +:term:`COMPATIBLE_MACHINE`: + +.. code-block:: bitbake COMPATIBLE_MACHINE = '(qemux86|qemumips)' diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst index d1c863117259..27e9065d5f4c 100644 --- a/documentation/dev-manual/new-recipe.rst +++ b/documentation/dev-manual/new-recipe.rst @@ -147,7 +147,9 @@ get started. Here are some points on both methods: - *Use and modify the following skeleton recipe:* If for some reason you do not want to use ``recipetool`` and you cannot find an existing recipe that is close to meeting your needs, you can use the following - structure to provide the fundamental areas of a new recipe:: + structure to provide the fundamental areas of a new recipe: + + .. code-block:: bitbake DESCRIPTION = "" HOMEPAGE = "" @@ -170,7 +172,9 @@ the recipe. recipe through the layer's ``conf/layer.conf`` file and the :term:`BBFILES` variable. This variable sets up a path from which the build system can locate - recipes. Here is the typical use:: + recipes. Here is the typical use: + + .. code-block:: bitbake BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ ${LAYERDIR}/recipes-*/*/*.bbappend" @@ -289,7 +293,9 @@ recipe to match the new version. Here is a simple example from the :oe_git:`strace recipe ` where the source comes from a single tarball. Notice the use of the -:term:`PV` variable:: +:term:`PV` variable: + +.. code-block:: bitbake SRC_URI = "${GITHUB_BASE_URI}/download/v${PV}/strace-${PV}.tar.xz \ @@ -303,7 +309,9 @@ another example that specifies these types of files, see the Another way of specifying source is from an SCM. For Git repositories, you must specify :term:`SRCREV` and you should specify :term:`PV` to include a ``+`` sign in its definition. Here is an example from the recipe -:oe_git:`l3afpad_git.bb `:: +:oe_git:`l3afpad_git.bb `: + +.. code-block:: bitbake SRC_URI = "git://github.com/stevenhoneyman/l3afpad.git;branch=master;protocol=https" @@ -329,7 +337,9 @@ If your :term:`SRC_URI` variable points to more than a single URL (excluding SCM URLs), you need to provide the ``sha256`` checksum for each URL. For these cases, you provide a name for each URL as part of the :term:`SRC_URI` and then reference that name in the subsequent checksum statements. Here is an example -combining lines from the files ``git.inc`` and ``git_2.24.1.bb``:: +combining lines from the files ``git.inc`` and ``git_2.24.1.bb``: + +.. code-block:: bitbake SRC_URI = "${KERNELORG_MIRROR}/software/scm/git/git-${PV}.tar.gz;name=tarball \ ${KERNELORG_MIRROR}/software/scm/git/git-manpages-${PV}.tar.gz;name=manpages" @@ -360,7 +370,9 @@ paste them into your recipe and then run the build again to continue. This final example is a bit more complicated and is from the :oe_git:`rxvt-unicode ` recipe. The example's :term:`SRC_URI` statement identifies multiple files as the source -files for the recipe: a tarball, a patch file, a desktop file, and an icon:: +files for the recipe: a tarball, a patch file, a desktop file, and an icon: + +.. code-block:: bitbake SRC_URI = "http://dist.schmorp.de/rxvt-unicode/Attic/rxvt-unicode-${PV}.tar.bz2 \ file://xwc.patch \ @@ -396,7 +408,9 @@ Limiting the Number of Parallel Connections Some users are behind firewalls or use servers where the number of parallel connections is limited. In such cases, you can limit the number of fetch tasks being run in parallel by adding the following to your ``local.conf`` -file:: +file: + +.. code-block:: bitbake do_fetch[number_threads] = "4" @@ -644,7 +658,9 @@ standard mainline kernel, not your own custom one. When you use custom kernel headers you need to get them from :term:`STAGING_KERNEL_DIR`, which is the directory with kernel headers that are required to build -out-of-tree modules. Your recipe will also need the following:: +out-of-tree modules. Your recipe will also need the following: + +.. code-block:: bitbake do_configure[depends] += "virtual/kernel:do_shared_workdir" @@ -675,7 +691,9 @@ Here are some common issues that cause failures. To fix the problem, you need to either satisfy the missing dependency in the Makefile or whatever script produced the Makefile, or (as a - workaround) set :term:`PARALLEL_MAKE` to an empty string:: + workaround) set :term:`PARALLEL_MAKE` to an empty string: + + .. code-block:: bitbake PARALLEL_MAKE = "" @@ -784,7 +802,9 @@ installed correctly. can result in race conditions. If you experience intermittent failures during :ref:`ref-tasks-install`, you might be able to work around them by disabling parallel Makefile installs by adding the following to the - recipe:: + recipe: + + .. code-block:: bitbake PARALLEL_MAKEINST = "" @@ -895,7 +915,9 @@ take. The following list describes the process: :term:`MACHINE` value is passed into the configure script or a patch is applied only for a particular machine), you should mark them as such by adding the following to the - recipe:: + recipe: + + .. code-block:: bitbake PACKAGE_ARCH = "${MACHINE_ARCH}" @@ -903,7 +925,9 @@ take. The following list describes the process: contain anything specific to the target machine or architecture at all (e.g. recipes that simply package script files or configuration files), you should use the :ref:`ref-classes-allarch` class to - do this for you by adding this to your recipe:: + do this for you by adding this to your recipe: + + .. code-block:: bitbake inherit allarch @@ -947,7 +971,9 @@ used by the :ref:`ref-tasks-populate_sysroot` task as defined by the :term:`SYSROOT_DIRS` variable to automatically populate the sysroot. It is possible to modify the list of directories that populate the sysroot. The following example shows how you could add the ``/opt`` directory to -the list of directories within a recipe:: +the list of directories within a recipe: + +.. code-block:: bitbake SYSROOT_DIRS += "/opt" @@ -974,7 +1000,9 @@ recipe. Suppose you have three kernel recipes whose :term:`PN` values map to ``kernel-big``, ``kernel-mid``, and ``kernel-small``. Furthermore, each of these recipes in some way uses a :term:`PROVIDES` statement that essentially identifies itself as being able to provide ``virtual/kernel``. Here is one way -through the :ref:`ref-classes-kernel` class:: +through the :ref:`ref-classes-kernel` class: + +.. code-block:: bitbake PROVIDES += "virtual/kernel" @@ -996,7 +1024,9 @@ relevant line from that include file:: When you use a virtual provider, you do not have to "hard code" a recipe name as a build dependency. You can use the :term:`DEPENDS` variable to state the -build is dependent on ``virtual/kernel`` for example:: +build is dependent on ``virtual/kernel`` for example: + +.. code-block:: bitbake DEPENDS = "virtual/kernel" @@ -1053,7 +1083,9 @@ build system and package managers, so the resulting packages will not correctly trigger an upgrade. In order to ensure the versions compare properly, the recommended -convention is to use a tilde (``~``) character as follows:: +convention is to use a tilde (``~``) character as follows: + +.. code-block:: bitbake PV = 0.8.16~rc1 @@ -1158,7 +1190,9 @@ Building an application from a single file that is stored locally (e.g. under variable. Additionally, you need to manually write the :ref:`ref-tasks-compile` and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the directory containing the source code, which is set to :term:`UNPACKDIR` in this -case --- the directory BitBake uses for the build:: +case --- the directory BitBake uses for the build: + +.. code-block:: bitbake SUMMARY = "Simple helloworld application" SECTION = "examples" @@ -1198,11 +1232,15 @@ empty :ref:`ref-tasks-install` task by default. Some applications might require extra parameters to be passed to the compiler. For example, the application might need an additional header path. You can accomplish this by adding to the :term:`CFLAGS` variable. The -following example shows this:: +following example shows this: + +.. code-block:: bitbake CFLAGS:prepend = "-I ${S}/include " -In the following example, ``lz4`` is a makefile-based package:: +In the following example, ``lz4`` is a makefile-based package: + +.. code-block:: bitbake SUMMARY = "Extremely Fast Compression algorithm" DESCRIPTION = "LZ4 is a very fast lossless compression algorithm, providing compression speed at 400 MB/s per core, scalable with multi-cores CPU. It also features an extremely fast decoder, with speed in multiple GB/s per core, typically reaching RAM speed limits on multi-core systems." @@ -1242,7 +1280,9 @@ inherit the :ref:`ref-classes-autotools` class, which contains the definitions of all the steps needed to build an Autotool-based application. The result of the build is automatically packaged. And, if the application uses NLS for localization, packages with local information are generated (one package per -language). Here is one example: (``hello_2.3.bb``):: +language). Here is one example: (``hello_2.3.bb``): + +.. code-block:: bitbake SUMMARY = "GNU Helloworld application" SECTION = "examples" @@ -1268,7 +1308,9 @@ just need a recipe that has sources described in :term:`SRC_URI` and inherits the :ref:`ref-classes-meson` class. The :oe_git:`ipcalc recipe ` -is a simple example of an application without dependencies:: +is a simple example of an application without dependencies: + +.. code-block:: bitbake SUMMARY = "Tool to assist in network address calculations for IPv4 and IPv6." HOMEPAGE = "https://gitlab.com/ipcalc/ipcalc" @@ -1296,7 +1338,9 @@ application into multiple packages. Here is an example that uses the ``libxpm`` recipe. By default, this recipe generates a single package that contains the library along with a few binaries. You can modify the recipe to split the binaries -into separate packages:: +into separate packages: + +.. code-block:: bitbake require xorg-lib-common.inc @@ -1385,7 +1429,9 @@ doing the following: that replaces :ref:`ref-tasks-configure` and :ref:`ref-tasks-compile` with custom versions, then you can use the ``[``\ :ref:`noexec `\ ``]`` - flag to turn the tasks into no-ops, as follows:: + flag to turn the tasks into no-ops, as follows: + + .. code-block:: bitbake do_configure[noexec] = "1" do_compile[noexec] = "1" @@ -1409,7 +1455,9 @@ As a basic example of a :ref:`ref-classes-bin-package`-style recipe, consider this snippet from the :oe_git:`wireless-regdb ` recipe file, which fetches a single tarball of binary content and manually -installs with no need for any configuration or compilation:: +installs with no need for any configuration or compilation: + +.. code-block:: bitbake SRC_URI = "https://www.kernel.org/pub/software/network/${BPN}/${BP}.tar.xz" SRC_URI[sha256sum] = "57f8e7721cf5a880c13ae0c202edbb21092a060d45f9e9c59bcd2a8272bfa456" @@ -1454,7 +1502,9 @@ chapter of the BitBake User Manual. supported. The following example shows some of the ways you can use variables in - recipes:: + recipes: + + .. code-block:: bitbake S = "${UNPACKDIR}/postfix-${PV}" CFLAGS += "-DNO_ASM" @@ -1467,7 +1517,9 @@ chapter of the BitBake User Manual. syntax, although access to OpenEmbedded variables and internal methods are also available. - Here is an example function from the ``sed`` recipe:: + Here is an example function from the ``sed`` recipe: + + .. code-block:: bitbake do_install () { autotools_do_install @@ -1490,7 +1542,9 @@ chapter of the BitBake User Manual. from other files (``include`` and ``require``) and export variables to the environment (``export``). - The following example shows the use of some of these keywords:: + The following example shows the use of some of these keywords: + + .. code-block:: bitbake export POSTCONF = "${STAGING_BINDIR}/postconf" inherit autoconf @@ -1509,7 +1563,9 @@ in the BitBake User Manual. - *Line Continuation (\\):* Use the backward slash (``\``) character to split a statement over multiple lines. Place the slash character at - the end of the line that is to be continued on the next line:: + the end of the line that is to be continued on the next line: + + .. code-block:: bitbake VAR = "A really long \ line" @@ -1520,7 +1576,9 @@ in the BitBake User Manual. slash character. - *Using Variables (${VARNAME}):* Use the ``${VARNAME}`` syntax to - access the contents of a variable:: + access the contents of a variable: + + .. code-block:: bitbake SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" @@ -1540,7 +1598,9 @@ in the BitBake User Manual. when you make the assignment, but this is not generally needed. - *Quote All Assignments ("value"):* Use double quotes around values in - all variable assignments (e.g. ``"value"``). Here is an example:: + all variable assignments (e.g. ``"value"``). Here is an example: + + .. code-block:: bitbake VAR1 = "${OTHERVAR}" VAR2 = "The version is ${PV}" @@ -1554,11 +1614,15 @@ in the BitBake User Manual. Here is an example where ``VAR1`` is set to "New value" if it is currently empty. However, if ``VAR1`` has already been set, it - remains unchanged:: + remains unchanged: + + .. code-block:: bitbake VAR1 ?= "New value" - In this next example, ``VAR1`` is left with the value "Original value":: + In this next example, ``VAR1`` is left with the value "Original value": + + .. code-block:: bitbake VAR1 = "Original value" VAR1 ?= "New value" @@ -1571,7 +1635,9 @@ in the BitBake User Manual. This operator adds a space between the existing content of the variable and the new content. - Here is an example:: + Here is an example: + + .. code-block:: bitbake SRC_URI += "file://fix-makefile.patch" @@ -1583,7 +1649,9 @@ in the BitBake User Manual. This operator adds a space between the new content and the existing content of the variable. - Here is an example:: + Here is an example: + + .. code-block:: bitbake VAR =+ "Starts" @@ -1597,13 +1665,17 @@ in the BitBake User Manual. The following example shows the space being explicitly added to the start to ensure the appended value is not merged with the existing - value:: + value: + + .. code-block:: bitbake CFLAGS:append = " --enable-important-feature" You can also use the ``:append`` operator with overrides, which results in the actions - only being performed for the specified target or machine:: + only being performed for the specified target or machine: + + .. code-block:: bitbake CFLAGS:append:sh4 = " --enable-important-sh4-specific-feature" @@ -1615,13 +1687,17 @@ in the BitBake User Manual. The following example shows the space being explicitly added to the end to ensure the prepended value is not merged with the existing - value:: + value: + + .. code-block:: bitbake CFLAGS:prepend = "-I${S}/myincludes " You can also use the ``:prepend`` operator with overrides, which results in the actions - only being performed for the specified target or machine:: + only being performed for the specified target or machine: + + .. code-block:: bitbake CFLAGS:prepend:sh4 = "-I${S}/myincludes " @@ -1631,7 +1707,9 @@ in the BitBake User Manual. value to "standard/base" for any target :term:`MACHINE`, except for qemuarm where it should be set to "standard/arm-versatile-926ejs", - you would do the following:: + you would do the following: + + .. code-block:: bitbake KBRANCH = "standard/base" KBRANCH:qemuarm = "standard/arm-versatile-926ejs" @@ -1654,7 +1732,9 @@ in the BitBake User Manual. search and replacement on a variable). You indicate Python code using the ``${@python_code}`` syntax for the - variable assignment:: + variable assignment: + + .. code-block:: bitbake SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst index c75584c936bf..16ce82606007 100644 --- a/documentation/dev-manual/packages.rst +++ b/documentation/dev-manual/packages.rst @@ -163,7 +163,9 @@ be consistent and correct with the latest changes. The simplest form for a PR Service is for a single host development system that builds the package feed (building system). For this scenario, you can enable a local PR Service by setting :term:`PRSERV_HOST` in your -``local.conf`` file in the :term:`Build Directory`:: +``local.conf`` file in the :term:`Build Directory`: + +.. code-block:: bitbake PRSERV_HOST = "localhost:0" @@ -248,13 +250,17 @@ the specific source code revision from which to build. You set the :term:`SRCREV` variable to :term:`AUTOREV` to cause the OpenEmbedded build system to automatically use the latest revision of -the software:: +the software: + +.. code-block:: bitbake SRCREV = "${AUTOREV}" Furthermore, you need to include a ``+`` sign in :term:`PV` in order to automatically update the version whenever the revision of the source -code changes. Here is an example:: +code changes. Here is an example: + +.. code-block:: bitbake PV = "1.0+git" @@ -338,7 +344,9 @@ package for each one it finds by appending to the :term:`PACKAGES` variable and setting the appropriate values for ``FILES:packagename``, ``RDEPENDS:packagename``, ``DESCRIPTION:packagename``, and so forth. -Here is an example from the ``lighttpd`` recipe:: +Here is an example from the ``lighttpd`` recipe: + +.. code-block:: bitbake python populate_packages:prepend () { lighttpd_libdir = d.expand('${libdir}') @@ -470,7 +478,9 @@ any dependencies on optional modules from other recipes are satisfied by your recipe. You can be sure these dependencies are satisfied by using the :term:`PACKAGES_DYNAMIC` variable. Here is an example that continues with the ``lighttpd`` recipe -shown earlier:: +shown earlier: + +.. code-block:: bitbake PACKAGES_DYNAMIC = "lighttpd-module-.*" @@ -561,7 +571,9 @@ variable to specify the format: #. Open the ``local.conf`` file inside your :term:`Build Directory` (e.g. ``bitbake-builds/build/conf/local.conf``). -#. Select the desired package format as follows:: +#. Select the desired package format as follows: + + .. code-block:: bitbake PACKAGE_CLASSES ?= "package_packageformat" @@ -837,11 +849,15 @@ Signing RPM Packages To enable signing RPM packages, you must modify the ``rpm`` recipe configuration to include support for OpenPGP signing. -That may be done either in a ``.bbappend`` for the ``rpm`` recipe:: +That may be done either in a ``.bbappend`` for the ``rpm`` recipe: + +.. code-block:: bitbake PACKAGECONFIG:append = " sequoia" -or in a :term:`Configuration File`:: +or in a :term:`Configuration File`: + +.. code-block:: bitbake PACKAGECONFIG:append:pn-rpm-native = " sequoia" PACKAGECONFIG:append:pn-rpm = " sequoia" @@ -878,7 +894,9 @@ signed package feeds for IPK and RPM packages. The steps you need to take to enable signed package feed use are similar to the steps used to sign RPM packages. You must define the following in -your ``local.config`` or ``distro.config`` file:: +your ``local.config`` or ``distro.config`` file: + +.. code-block:: bitbake INHERIT += "sign_package_feed" PACKAGE_FEED_GPG_NAME = "key_name" @@ -1115,7 +1133,9 @@ command:: $ devtool add https://github.com/martinaglv/cute-files.git The recipe this command generates is very similar to the recipe created in -the previous section. However, the :term:`SRC_URI` looks like the following:: +the previous section. However, the :term:`SRC_URI` looks like the following: + +.. code-block:: bitbake SRC_URI = " \ git://github.com/martinaglv/cute-files.git;protocol=https;branch=master \ @@ -1167,7 +1187,9 @@ by the literal sequence '\\n'. The separator can be redefined using the variable flag ``separator``. Here is an example that adds two custom fields for ipk -packages:: +packages: + +.. code-block:: bitbake PACKAGE_ADD_METADATA_IPK = "Vendor: CustomIpk\nGroup:Applications/Spreadsheets" diff --git a/documentation/dev-manual/poky-manual-setup.rst b/documentation/dev-manual/poky-manual-setup.rst index 833e1631ee50..f2287c25c339 100644 --- a/documentation/dev-manual/poky-manual-setup.rst +++ b/documentation/dev-manual/poky-manual-setup.rst @@ -119,7 +119,9 @@ an entire Linux distribution, including the toolchain, from source. can download these artifacts faster than you would be able to build them. To use such mirrors, uncomment the below lines in your ``conf/local.conf`` - file in the :term:`Build Directory`:: + file in the :term:`Build Directory`: + + .. code-block:: bitbake BB_HASHSERVE_UPSTREAM = "wss://hashserv.yoctoproject.org/ws" SSTATE_MIRRORS ?= "file://.* http://sstate.yoctoproject.org/all/PATH;downloadfilename=PATH" diff --git a/documentation/dev-manual/prebuilt-libraries.rst b/documentation/dev-manual/prebuilt-libraries.rst index 9cc8bd2d9dee..8eb4d5023b17 100644 --- a/documentation/dev-manual/prebuilt-libraries.rst +++ b/documentation/dev-manual/prebuilt-libraries.rst @@ -149,7 +149,9 @@ triggers a QA warning that a non-symlink library is in a ``-dev`` package, and binaries in the same recipe link to the library in ``${PN}-dev``, which triggers more QA warnings. To solve this problem, you need to package the unversioned library into ``${PN}`` where it belongs. The abridged -default :term:`FILES` variables in ``bitbake.conf`` are:: +default :term:`FILES` variables in ``bitbake.conf`` are: + +.. code-block:: bitbake SOLIBS = ".so.*" SOLIBSDEV = ".so" @@ -162,7 +164,9 @@ default :term:`FILES` variables in ``bitbake.conf`` are:: variables are then used in ``FILES:${PN}`` and ``FILES:${PN}-dev``, which puts the real libraries into ``${PN}`` and the unversioned symbolic link into ``${PN}-dev``. To package unversioned libraries, you need to modify the variables in the recipe -as follows:: +as follows: + +.. code-block:: bitbake SOLIBS = ".so" FILES_SOLIBSDEV = "" @@ -186,7 +190,9 @@ The example below installs an unversioned x86-64 pre-built library named x86-64 architecture while the :term:`INSANE_SKIP`, :term:`INHIBIT_PACKAGE_STRIP` and :term:`INHIBIT_SYSROOT_STRIP` variables are all set as in the above versioned library example. The "magic" is setting the :term:`SOLIBS` and -:term:`FILES_SOLIBSDEV` variables as explained above:: +:term:`FILES_SOLIBSDEV` variables as explained above: + +.. code-block:: bitbake SUMMARY = "libfoo sample recipe" SECTION = "libs" diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst index 514a72fc528a..eead23f67376 100644 --- a/documentation/dev-manual/qemu.rst +++ b/documentation/dev-manual/qemu.rst @@ -434,7 +434,9 @@ command line: (or the next free ports). Specific forwarding rules can be configured by setting ``QB_SLIRP_OPT`` as environment variable or in ``qemuboot.conf`` in the :term:`Build Directory` ``deploy/image`` directory. - Examples:: + Examples: + + .. code-block:: bitbake QB_SLIRP_OPT = "-netdev user,id=net0,hostfwd=tcp::8080-:80" diff --git a/documentation/dev-manual/quilt.rst b/documentation/dev-manual/quilt.rst index 59240705ad99..2173d86981db 100644 --- a/documentation/dev-manual/quilt.rst +++ b/documentation/dev-manual/quilt.rst @@ -83,7 +83,9 @@ Follow these general steps: that holds the recipe (``.bb``) file or the append (``.bbappend``) file. Placing the patch here guarantees that the OpenEmbedded build system will find the patch. Next, add the patch into the :term:`SRC_URI` - of the recipe. Here is an example:: + of the recipe. Here is an example: + + .. code-block:: bitbake SRC_URI += "file://my_changes.patch" diff --git a/documentation/dev-manual/sbom.rst b/documentation/dev-manual/sbom.rst index 45b63ed8edea..aff328423287 100644 --- a/documentation/dev-manual/sbom.rst +++ b/documentation/dev-manual/sbom.rst @@ -27,7 +27,9 @@ assessments, as all the components used in the Software Supply Chain are listed. The OpenEmbedded build system generates such information by default (by inheriting the :ref:`ref-classes-create-spdx` class in :term:`INHERIT_DISTRO`). -If needed, it can be disabled from a :term:`configuration file`:: +If needed, it can be disabled from a :term:`configuration file`: + +.. code-block:: bitbake INHERIT_DISTRO:remove = "create-spdx" diff --git a/documentation/dev-manual/speeding-up-build.rst b/documentation/dev-manual/speeding-up-build.rst index 262935313a19..a6930fc41642 100644 --- a/documentation/dev-manual/speeding-up-build.rst +++ b/documentation/dev-manual/speeding-up-build.rst @@ -90,7 +90,9 @@ that can help you speed up the build: - Disable static library generation for recipes derived from ``autoconf`` or ``libtool``: Here is an example showing how to disable static libraries and still provide an override to handle - exceptions:: + exceptions: + + .. code-block:: bitbake STATICLIBCONF = "--disable-static" STATICLIBCONF:sqlite3-native = "" diff --git a/documentation/dev-manual/sstate-mirrors-setup.rst b/documentation/dev-manual/sstate-mirrors-setup.rst index e69aa00d1cc6..a0c6e7d579fc 100644 --- a/documentation/dev-manual/sstate-mirrors-setup.rst +++ b/documentation/dev-manual/sstate-mirrors-setup.rst @@ -86,7 +86,9 @@ Client Configuration Configuring clients to this server happens through a :term:`configuration file`, for example, the :ref:`site.conf ` 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=;pswd=;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 `-mounted directory, is also possible - using the ``file://`` fetcher:: + using the ``file://`` fetcher: + + .. code-block:: bitbake SSTATE_MIRRORS = "file://.* file:///path/to/shared-state/PATH;downloadfilename=PATH" diff --git a/documentation/dev-manual/temporary-source-code.rst b/documentation/dev-manual/temporary-source-code.rst index cb27d22070ef..a2f6b6ef40d5 100644 --- a/documentation/dev-manual/temporary-source-code.rst +++ b/documentation/dev-manual/temporary-source-code.rst @@ -16,7 +16,9 @@ During a build, the unpacked temporary source code used by recipes to build packages is available in the :term:`Build Directory` as defined by the :term:`S` variable. Below is the default value for the :term:`S` variable as defined in the ``meta/conf/bitbake.conf`` configuration file in -:term:`OpenEmbedded-Core (OE-Core)`:: +:term:`OpenEmbedded-Core (OE-Core)`: + +.. code-block:: bitbake S = "${UNPACKDIR}/${BP}" @@ -26,7 +28,9 @@ You should be aware that many recipes override the .. note:: The :term:`BP` represents the base recipe name, which consists of the name - and version:: + and version: + + .. code-block:: bitbake BP = "${BPN}-${PV}" diff --git a/documentation/dev-manual/upgrading-recipes.rst b/documentation/dev-manual/upgrading-recipes.rst index cc984bbccbeb..fdbe630393a7 100644 --- a/documentation/dev-manual/upgrading-recipes.rst +++ b/documentation/dev-manual/upgrading-recipes.rst @@ -103,7 +103,9 @@ The following steps describe how to set up the AUH utility: - If you want to enable :ref:`Build History `, which is optional, you need the following lines in the - ``conf/local.conf`` file:: + ``conf/local.conf`` file: + + .. code-block:: bitbake INHERIT =+ "buildhistory" BUILDHISTORY_COMMIT = "1" @@ -115,14 +117,18 @@ The following steps describe how to set up the AUH utility: - If you want to enable testing through the :ref:`ref-classes-testimage` class, which is optional, you need to have the following set in - your ``conf/local.conf`` file:: + your ``conf/local.conf`` file: + + .. code-block:: bitbake IMAGE_CLASSES += "testimage" .. note:: If your distro does not enable by default ptest, which :term:`Poky` - does, you need the following in your ``local.conf`` file:: + does, you need the following in your ``local.conf`` file: + + .. code-block:: bitbake DISTRO_FEATURES:append = " ptest" diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst index 18d1bfb0a608..510bc2bcfd91 100644 --- a/documentation/dev-manual/wayland.rst +++ b/documentation/dev-manual/wayland.rst @@ -48,7 +48,9 @@ Wayland with Kernel Mode Setting (`KMS `__) support, include the "wayland" flag in the :term:`DISTRO_FEATURES` -statement in your ``local.conf`` file:: +statement in your ``local.conf`` file: + +.. code-block:: bitbake DISTRO_FEATURES:append = " wayland" @@ -63,7 +65,9 @@ Installing Wayland and Weston To install the Wayland feature into an image, you must include the following :term:`CORE_IMAGE_EXTRA_INSTALL` -statement in your ``local.conf`` file:: +statement in your ``local.conf`` file: + +.. code-block:: bitbake CORE_IMAGE_EXTRA_INSTALL += "wayland weston" diff --git a/documentation/dev-manual/x32-psabi.rst b/documentation/dev-manual/x32-psabi.rst index 0a19d28233d8..1bff33a34a3b 100644 --- a/documentation/dev-manual/x32-psabi.rst +++ b/documentation/dev-manual/x32-psabi.rst @@ -39,7 +39,9 @@ follows: - There is support for large images. To use the x32 psABI, you need to edit your ``conf/local.conf`` -configuration file as follows:: +configuration file as follows: + +.. code-block:: bitbake MACHINE = "qemux86-64" DEFAULTTUNE = "x86-64-x32" From patchwork Wed Aug 26 01:34:49 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96336 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id BDDEDC61DCD for ; Wed, 26 Aug 2026 01:35:22 +0000 (UTC) Received: from mail-qk1-f178.google.com (mail-qk1-f178.google.com [209.85.222.178]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3402.1787708116673648446 for ; Tue, 25 Aug 2026 18:35:16 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=jLOL1oZL; spf=pass (domain: gmail.com, ip: 209.85.222.178, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f178.google.com with SMTP id af79cd13be357-936dfd009d1so119020485a.1 for ; Tue, 25 Aug 2026 18:35:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708116; x=1788312916; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=AMmg9I+C1d87MPNVgolSbRYtndc6AnUktjxEbceTVbk=; b=jLOL1oZLH/PkaHQwLN5ANC/IiYw9Jo7V3iY6GWYnTQxRHks66r22USA0VCfTTDbPgc PQSr6YCZGnSg0fkpFrj1QDNiG6HVCct88lgYEN67E1W75LGLsHPdj0tSp0Ld2cglIGmd wX59sq8T4puU2vkhHKg5nO10N4SEhd3icK3ZDAdwyF5nZArTjABv+vByNPoyALYDpJPv 7CWcrqHpslXC9IDhtQbNSQ+dtpFGMlpxYqWUa22aITuetcCKBMj+oMvg8D8/3GcRNKRY TO3qVb05ctKHjDJ0EBBbf7nk9am4qz0rwaFMRDzP75MUgPINn6ZFJ4VpQ4uZ0FuJpPrL kEXA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708116; x=1788312916; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=AMmg9I+C1d87MPNVgolSbRYtndc6AnUktjxEbceTVbk=; b=sVLY/3fdN21WoKkvzkWvQo8tnJfP0lh43SeNco/Ae42oIuQWonFIjI1nbNVOQwPjb8 569Xj/gMgzRJT4aMrQjNcnTmjGDU98qmxFq26UfCFs4K2dPdWWtvH6FrzH4yAFeMGAbe Rzajw0xUGQNeNTlvrbGzbg7Q62/6ERcjuEIFrwHJvw/5zWvI74dXtvNPCBChsqCIHy7T 95sZwdLkRmIt8VOKGSG8v1GHnRR8Ps/fQeCAxG2vBQidiQ6oMshWnLU7TXg7dwDOHGub ITCOoNhgfT1ksTsGiAVQNe0h+rqD97U9Vv0pFE4Z+v/DEWNbiI5Wamdme1RHXbCK+e/L ziUQ== X-Gm-Message-State: AFuF++njfiT5mitoY4x2okqOg8eFfHg5Vhs9NChH1OV18Ym5jdF08Xs5 dRibHT5mGz/z5pOQNQXxMDy3EVNOxG4i0FVqyYOoVC9WV1mSLLhf9vUqu2zaS7sF X-Gm-Gg: AR+sD13bpxPf0/vMiZIFX756tUNZk1ivE26egYIVLtLGbfeVQ0HsCtHb2pzobD7J6pQ c2WCt5FF8OMUPC7Ci+k83N7DlwxUjeHKn+ihidSNXvU1s18jQG4IdPS+ia1nkmV7iEKXavROvKU mLxLagx67ffREkFiqxgWI2/XK8S7ulYXj3p4lG8XXaWt3bRlE7gyL8WAhd8yXCPg98u5BjlXfN9 MtYzVE6MWK6XBu9N/V88AWsxmtcJOOQEJI5RJ/Kf1c6WQQ4wmSa7GmVhWIB2SnWUon9iPvONaub OcT8iv5SG0weuBQOkJLwDYeEEaarzaCQ7itO/LQbpO8NNmv/LTtaslj9NyydNPTYbHOOk8uS8fw LBfAS9+kc6/n8DeJXZ1SR5APkLScJwbhKmn0sTvWYmB5VD4HVnC0tjCc/DyDoRTNqlURWMCAQW/ 3tImBqLCIB3gshS4ljvFbdw8LOKKfV4fI1pBZHgcaxswKVNJEAjL6j4ret8TTsMjCgM5Lv1TK9P Ph5bXORMwW/mU5aTEYAPhWWKOfqYbA= X-Received: by 2002:a05:620a:2587:b0:92e:e467:7f93 with SMTP id af79cd13be357-9377e990c46mr300481685a.14.1787708114627; Tue, 25 Aug 2026 18:35:14 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.12 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:12 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 04/10] migration-guides: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:49 -0400 Message-ID: <20260826013502.2674000-5-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:22 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10349 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 79 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- .../migration-guides/migration-1.3.rst | 8 +++- .../migration-guides/migration-1.6.rst | 12 +++-- .../migration-guides/migration-1.7.rst | 4 +- .../migration-guides/migration-1.8.rst | 12 +++-- .../migration-guides/migration-2.0.rst | 8 +++- .../migration-guides/migration-2.1.rst | 4 +- .../migration-guides/migration-2.2.rst | 11 +++-- .../migration-guides/migration-2.3.rst | 12 +++-- .../migration-guides/migration-2.5.rst | 4 +- .../migration-guides/migration-2.6.rst | 12 +++-- .../migration-guides/migration-3.0.rst | 4 +- .../migration-guides/migration-3.1.rst | 12 +++-- .../migration-guides/migration-3.2.rst | 8 +++- .../migration-guides/migration-3.3.rst | 8 +++- .../migration-guides/migration-3.4.rst | 16 +++++-- .../migration-guides/migration-4.0.rst | 12 +++-- .../migration-guides/migration-4.1.rst | 8 +++- .../migration-guides/migration-4.2.rst | 12 +++-- .../migration-guides/migration-5.1.rst | 12 +++-- .../migration-guides/migration-5.2.rst | 24 +++++++--- .../migration-guides/migration-5.3.rst | 36 +++++++++++---- .../migration-guides/migration-6.0.rst | 44 ++++++++++++++----- .../migration-guides/migration-6.1.rst | 12 +++-- .../migration-guides/release-notes-4.0.rst | 4 +- .../migration-guides/release-notes-4.3.rst | 4 +- .../migration-guides/release-notes-5.0.rst | 4 +- .../migration-guides/release-notes-5.3.rst | 8 +++- 27 files changed, 236 insertions(+), 79 deletions(-) diff --git a/documentation/migration-guides/migration-1.3.rst b/documentation/migration-guides/migration-1.3.rst index 594320d5e1c3..23f54dca96e7 100644 --- a/documentation/migration-guides/migration-1.3.rst +++ b/documentation/migration-guides/migration-1.3.rst @@ -29,7 +29,9 @@ location (either local or remote) and then point to it in :term:`SSTATE_MIRRORS`, you need to append "PATH" to the end of the mirror URL so that the path used by BitBake before the mirror substitution is appended to the path used to access the mirror. -Here is an example:: +Here is an example: + +.. code-block:: bitbake SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" @@ -178,7 +180,9 @@ Linux Kernel Naming ------------------- The naming scheme for kernel output binaries has been changed to now -include :term:`PE` as part of the filename:: +include :term:`PE` as part of the filename: + +.. code-block:: bitbake KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" diff --git a/documentation/migration-guides/migration-1.6.rst b/documentation/migration-guides/migration-1.6.rst index b052a43a3125..aef0b5bce284 100644 --- a/documentation/migration-guides/migration-1.6.rst +++ b/documentation/migration-guides/migration-1.6.rst @@ -54,7 +54,9 @@ Matching Branch Requirement for Git Fetching When fetching source from a Git repository using :term:`SRC_URI`, BitBake will now validate the :term:`SRCREV` value against the branch. You can specify -the branch using the following form:: +the branch using the following form: + +.. code-block:: bitbake SRC_URI = "git://server.name/repository;branch=branchname" @@ -207,7 +209,9 @@ functions to call and not arbitrary shell commands: For migration purposes, you can simply wrap shell commands in a shell -function and then call the function. Here is an example:: +function and then call the function. Here is an example: + +.. code-block:: bitbake my_postprocess_function() { echo "hello" > ${IMAGE_ROOTFS}/hello.txt @@ -247,7 +251,9 @@ the :ref:`ref-classes-autotools` or ``autotools_stage`` classes. ``qemu-native`` now builds without SDL-based graphical output support by default. The following additional lines are needed in your -``local.conf`` to enable it:: +``local.conf`` to enable it: + +.. code-block:: bitbake PACKAGECONFIG_pn-qemu-native = "sdl" ASSUME_PROVIDED += "libsdl-native" diff --git a/documentation/migration-guides/migration-1.7.rst b/documentation/migration-guides/migration-1.7.rst index 1a5704fd4da6..c686f6dab10b 100644 --- a/documentation/migration-guides/migration-1.7.rst +++ b/documentation/migration-guides/migration-1.7.rst @@ -17,7 +17,9 @@ optional features. The method used to set defaults for these options means that existing ``local.conf`` files will need to be modified to append to :term:`PACKAGECONFIG` for ``qemu-native`` and ``nativesdk-qemu`` instead of setting it. In other words, to enable graphical output for -QEMU, you should now have these lines in ``local.conf``:: +QEMU, you should now have these lines in ``local.conf``: + +.. code-block:: bitbake PACKAGECONFIG_append_pn-qemu-native = " sdl" PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" diff --git a/documentation/migration-guides/migration-1.8.rst b/documentation/migration-guides/migration-1.8.rst index 5cc5f8a047d8..e7e43fd64e55 100644 --- a/documentation/migration-guides/migration-1.8.rst +++ b/documentation/migration-guides/migration-1.8.rst @@ -58,7 +58,9 @@ you can now remove them. Additionally, a ``bluetooth`` class has been added to make selection of the appropriate bluetooth support within a recipe a little easier. If you wish to make use of this class in a recipe, add something such as -the following:: +the following: + +.. code-block:: bitbake inherit bluetooth PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}" @@ -85,7 +87,9 @@ where the ``linux.inc`` file in ``meta-oe`` was updated. Recipes that rely on the kernel source code and do not inherit the :ref:`module ` classes might need to add explicit -dependencies on the :ref:`ref-tasks-shared_workdir` kernel task, for example:: +dependencies on the :ref:`ref-tasks-shared_workdir` kernel task, for example: + +.. code-block:: bitbake do_configure[depends] += "virtual/kernel:do_shared_workdir" @@ -131,7 +135,9 @@ One of the improvements is to attempt to run "make clean" during the :ref:`ref-tasks-configure` task if a ``Makefile`` exists. Some software packages do not provide a working clean target within their make files. If you have such recipes, you need to set -:term:`CLEANBROKEN` to "1" within the recipe, for example:: +:term:`CLEANBROKEN` to "1" within the recipe, for example: + +.. code-block:: bitbake CLEANBROKEN = "1" diff --git a/documentation/migration-guides/migration-2.0.rst b/documentation/migration-guides/migration-2.0.rst index 13be9846dfb3..f8d14e44c136 100644 --- a/documentation/migration-guides/migration-2.0.rst +++ b/documentation/migration-guides/migration-2.0.rst @@ -27,7 +27,9 @@ and the porting guide at https://gcc.gnu.org/gcc-5/porting_to.html. Alternatively, you can switch back to GCC 4.9 or 4.8 by setting -:term:`GCCVERSION` in your configuration, as follows:: +:term:`GCCVERSION` in your configuration, as follows: + +.. code-block:: bitbake GCCVERSION = "4.9%" @@ -200,7 +202,9 @@ changes. Additionally, work directories for old versions of recipes are now pruned. If you wish to disable pruning old work directories, you can set -the following variable in your configuration:: +the following variable in your configuration: + +.. code-block:: bitbake SSTATE_PRUNE_OBSOLETEWORKDIR = "0" diff --git a/documentation/migration-guides/migration-2.1.rst b/documentation/migration-guides/migration-2.1.rst index 4d7aa15af565..bdbc7e4d289f 100644 --- a/documentation/migration-guides/migration-2.1.rst +++ b/documentation/migration-guides/migration-2.1.rst @@ -284,7 +284,9 @@ The following changes have been made for the Poky distribution: Any recipe that needs to opt-out of having the ``--disable-static`` option specified on the configure command line either because it is not a supported option for the configure script or because static - libraries are needed should set the following variable:: + libraries are needed should set the following variable: + + .. code-block:: bitbake DISABLE_STATIC = "" diff --git a/documentation/migration-guides/migration-2.2.rst b/documentation/migration-guides/migration-2.2.rst index 9d50dc62022b..20fe4ad3bfb2 100644 --- a/documentation/migration-guides/migration-2.2.rst +++ b/documentation/migration-guides/migration-2.2.rst @@ -224,7 +224,8 @@ follows and run ``runqemu``: For command-line syntax, use ``runqemu help``. -:: + +.. code-block:: bitbake IMAGE_CLASSES += "qemuboot" @@ -241,7 +242,9 @@ recipes. You need to fix these recipes so that they use the expected :term:`LDFLAGS`. Depending on how the software is built, the build system used by the software (e.g. a Makefile) might need to be patched. However, sometimes making this fix is as simple as adding the following -to the recipe:: +to the recipe: + +.. code-block:: bitbake TARGET_CC_ARCH += "${LDFLAGS}" @@ -254,7 +257,9 @@ The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the :term:`KERNEL_IMAGETYPE` variable to create the image's base name. Because the OpenEmbedded build system can now build multiple kernel image types, this part of the kernel image base name as -been removed leaving only the following:: +been removed leaving only the following: + +.. code-block:: bitbake KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" diff --git a/documentation/migration-guides/migration-2.3.rst b/documentation/migration-guides/migration-2.3.rst index 60340b9592f1..641be4deb328 100644 --- a/documentation/migration-guides/migration-2.3.rst +++ b/documentation/migration-guides/migration-2.3.rst @@ -452,11 +452,15 @@ The following miscellaneous changes have occurred: tools. - The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig" - :term:`DISTRO_FEATURES` feature. Distributions that previously set:: + :term:`DISTRO_FEATURES` feature. Distributions that previously set: + + .. code-block:: bitbake USE_LDCONFIG = "0" - should now instead use the following:: + should now instead use the following: + + .. code-block:: bitbake DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" @@ -474,7 +478,9 @@ The following miscellaneous changes have occurred: order to allow module packages from multiple kernel versions to co-exist on a target system. If you wish to return to the previous naming scheme that does not include the version suffix, use the - following:: + following: + + .. code-block:: bitbake KERNEL_MODULE_PACKAGE_SUFFIX = "" diff --git a/documentation/migration-guides/migration-2.5.rst b/documentation/migration-guides/migration-2.5.rst index 8e182cd2bc4a..165f15708fc0 100644 --- a/documentation/migration-guides/migration-2.5.rst +++ b/documentation/migration-guides/migration-2.5.rst @@ -165,7 +165,9 @@ one of the packages provided by the Python recipe. You can no longer run ``bitbake python-foo`` or have a :term:`DEPENDS` on ``python-foo``, but doing either of the following causes the package to work as -expected:: +expected: + +.. code-block:: bitbake IMAGE_INSTALL_append = " python-foo" diff --git a/documentation/migration-guides/migration-2.6.rst b/documentation/migration-guides/migration-2.6.rst index ecb559dd4c32..ac899b0a02b3 100644 --- a/documentation/migration-guides/migration-2.6.rst +++ b/documentation/migration-guides/migration-2.6.rst @@ -162,7 +162,9 @@ The following changes have been made: allows easier and more direct changes. The :term:`IMAGE_VERSION_SUFFIX` variable is set in the ``bitbake.conf`` - configuration file as follows:: + configuration file as follows: + + .. code-block:: bitbake IMAGE_VERSION_SUFFIX = "-${DATETIME}" @@ -385,7 +387,9 @@ If you wish to disable Python profile-guided optimization regardless of the value of :term:`MACHINE_FEATURES`, then ensure that :term:`PACKAGECONFIG` for the ``python3`` recipe does not contain "pgo". You could accomplish the latter using the -following at the configuration level:: +following at the configuration level: + +.. code-block:: bitbake PACKAGECONFIG_remove_pn-python3 = "pgo" @@ -402,7 +406,9 @@ The following miscellaneous changes occurred: - Default to using the Thumb-2 instruction set for armv7a and above. If you have any custom recipes that build software that needs to be built with the ARM instruction set, change the recipe to set the - instruction set as follows:: + instruction set as follows: + + .. code-block:: bitbake ARM_INSTRUCTION_SET = "arm" diff --git a/documentation/migration-guides/migration-3.0.rst b/documentation/migration-guides/migration-3.0.rst index f5201dcac24c..5a991dd84367 100644 --- a/documentation/migration-guides/migration-3.0.rst +++ b/documentation/migration-guides/migration-3.0.rst @@ -261,7 +261,9 @@ The following miscellaneous changes have occurred. - The ``gnome`` class has been removed because it now does very little. You should update recipes that previously inherited this class to do - the following:: + the following: + + .. code-block:: bitbake inherit gnomebase gtk-icon-cache gconf mime diff --git a/documentation/migration-guides/migration-3.1.rst b/documentation/migration-guides/migration-3.1.rst index fdb959c4affa..ddb994c3ad2f 100644 --- a/documentation/migration-guides/migration-3.1.rst +++ b/documentation/migration-guides/migration-3.1.rst @@ -73,7 +73,9 @@ when building a simple image such as core-image-minimal. If you do not need runtime tests enabled for core components, then it is recommended that you remove "ptest" from :term:`DISTRO_FEATURES` to save a significant -amount of build time e.g. by adding the following in your configuration:: +amount of build time e.g. by adding the following in your configuration: + +.. code-block:: bitbake DISTRO_FEATURES_remove = "ptest" @@ -180,12 +182,16 @@ parameter instead of the earlier ``name`` which overlapped with the generic ``name`` parameter. All recipes using the npm fetcher will need to be changed as a result. -An example of the new scheme:: +An example of the new scheme: + +.. code-block:: bitbake SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \ npmsw://${THISDIR}/npm-shrinkwrap.json" -Another example where the sources are fetched from git rather than an npm repository:: +Another example where the sources are fetched from git rather than an npm repository: + +.. code-block:: bitbake SRC_URI = "git://github.com/foo/bar.git;protocol=https \ npmsw://${THISDIR}/npm-shrinkwrap.json" diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst index 5cb958e75047..5313c4ebdda2 100644 --- a/documentation/migration-guides/migration-3.2.rst +++ b/documentation/migration-guides/migration-3.2.rst @@ -97,7 +97,9 @@ is prefixed on the package names in the dependencies, for example RRECOMMENDS_${PN} = "${@bb.utils.contains('DISTRO_FEATURES', 'ldconfig', '${MLPREFIX}ldconfig', '', d)}" This also applies when conditionally adding packages to :term:`PACKAGES` where -those packages have dependencies, for example (from the ``alsa-plugins`` recipe):: +those packages have dependencies, for example (from the ``alsa-plugins`` recipe): + +.. code-block:: bitbake PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}" ... @@ -256,7 +258,9 @@ needs ``/etc/ld.so.conf`` to be present at image build time: When some recipe installs libraries to a non-standard location, and therefore installs in a file in ``/etc/ld.so.conf.d/foo.conf``, we -need ``/etc/ld.so.conf`` containing:: +need ``/etc/ld.so.conf`` containing: + +.. code-block:: bitbake include /etc/ld.so.conf.d/*.conf diff --git a/documentation/migration-guides/migration-3.3.rst b/documentation/migration-guides/migration-3.3.rst index d1e589d7b486..9c4d449eabb7 100644 --- a/documentation/migration-guides/migration-3.3.rst +++ b/documentation/migration-guides/migration-3.3.rst @@ -87,14 +87,18 @@ source tree. Previously this was handled in recipes by setting :term:`S` to point to the subdirectory within the source where ``setup.py`` is located. However with the recent :ref:`pseudo ` changes, some Python modules make changes to files beneath ``${S}``, for -example:: +example: + +.. code-block:: bitbake S = "${WORKDIR}/git/python/pythonmodule" then in ``setup.py`` it works with source code in a relative fashion, such as ``../../src``. This causes pseudo to fail as it isn't able to track the paths properly. This release introduces a new ``DISTUTILS_SETUP_PATH`` -variable so that recipes can specify it explicitly, for example:: +variable so that recipes can specify it explicitly, for example: + +.. code-block:: bitbake S = "${WORKDIR}/git" DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule" diff --git a/documentation/migration-guides/migration-3.4.rst b/documentation/migration-guides/migration-3.4.rst index e9cb3a109ea9..4f970b9d4663 100644 --- a/documentation/migration-guides/migration-3.4.rst +++ b/documentation/migration-guides/migration-3.4.rst @@ -11,16 +11,22 @@ Override syntax changes In this release, the ``:`` character replaces the use of ``_`` to refer to an override, most commonly when making a conditional assignment -of a variable. This means that an entry like:: +of a variable. This means that an entry like: + +.. code-block:: bitbake SRC_URI_qemux86 = "file://somefile" -now becomes:: +now becomes: + +.. code-block:: bitbake SRC_URI:qemux86 = "file://somefile" since ``qemux86`` is an override. This applies to any use of override -syntax, so the following:: +syntax, so the following: + +.. code-block:: bitbake SRC_URI_append = " file://somefile" SRC_URI_append_qemux86 = " file://somefile2" @@ -32,7 +38,9 @@ syntax, so the following:: SRCREV_pn-bash = "abc" BB_TASK_NICE_LEVEL_task-testimage = '0' -would now become:: +would now become: + +.. code-block:: bitbake SRC_URI:append = " file://somefile" SRC_URI:append:qemux86 = " file://somefile2" diff --git a/documentation/migration-guides/migration-4.0.rst b/documentation/migration-guides/migration-4.0.rst index c8c2b856d91c..89bc24e7669b 100644 --- a/documentation/migration-guides/migration-4.0.rst +++ b/documentation/migration-guides/migration-4.0.rst @@ -74,7 +74,9 @@ Fetching changes - Because of the uncertainty in future default branch names in git repositories, it is now required to add a branch name to all URLs described - by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example:: + by ``git://`` and ``gitsm://`` :term:`SRC_URI` entries. For example: + + .. code-block:: bitbake SRC_URI = "git://git.denx.de/u-boot.git;branch=master" @@ -91,7 +93,9 @@ Fetching changes - Network access from tasks is now disabled by default on kernels which support this feature (on most recent distros such as CentOS 8 and Debian 11 onwards). This means that tasks accessing the network need to be marked as such with the ``network`` - flag. For example:: + flag. For example: + + .. code-block:: bitbake do_mytask[network] = "1" @@ -216,7 +220,9 @@ Miscellaneous changes - ``blacklist.bbclass`` is removed and the functionality moved to the :ref:`ref-classes-base` class with a more descriptive ``varflag`` variable named :term:`SKIP_RECIPE` which will use the `bb.parse.SkipRecipe()` - function. The usage remains the same, for example:: + function. The usage remains the same, for example: + + .. code-block:: bitbake SKIP_RECIPE[my-recipe] = "Reason for skipping recipe" diff --git a/documentation/migration-guides/migration-4.1.rst b/documentation/migration-guides/migration-4.1.rst index 86721b9873d0..635c08821238 100644 --- a/documentation/migration-guides/migration-4.1.rst +++ b/documentation/migration-guides/migration-4.1.rst @@ -88,12 +88,16 @@ Other than knowing where to look when manually browsing the class files, this is not likely to require any changes to your configuration. However, if in your configuration you were using some classes in the incorrect context, you will now receive an error during parsing. For example, the following in ``local.conf`` will -now cause an error:: +now cause an error: + +.. code-block:: bitbake INHERIT += "testimage" Since :ref:`ref-classes-testimage` is a class intended solely to -affect image recipes, this would be correctly specified as:: +affect image recipes, this would be correctly specified as: + +.. code-block:: bitbake IMAGE_CLASSES += "testimage" diff --git a/documentation/migration-guides/migration-4.2.rst b/documentation/migration-guides/migration-4.2.rst index f5f12c88710a..6a4de4d8f01c 100644 --- a/documentation/migration-guides/migration-4.2.rst +++ b/documentation/migration-guides/migration-4.2.rst @@ -184,7 +184,9 @@ release we limit qemu port forwarding to localhost (127.0.0.1). However, if you need the qemu machine to be reachable from the network, then it can be enabled via ``conf/local.conf`` or machine -config variable ``QB_SLIRP_OPT``:: +config variable ``QB_SLIRP_OPT``: + +.. code-block:: bitbake QB_SLIRP_OPT = "-netdev user,id=net0,hostfwd=tcp::2222-:22" @@ -233,7 +235,9 @@ Miscellaneous changes - The :term:`IMAGE_NAME` variable is now set based on :term:`IMAGE_LINK_NAME`. This means that if you are setting :term:`IMAGE_LINK_NAME` to "" to disable unversioned image symlink creation, you also now need to set :term:`IMAGE_NAME` to still have - a reasonable value e.g.:: + a reasonable value e.g.: + + .. code-block:: bitbake IMAGE_LINK_NAME = "" IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" @@ -271,6 +275,8 @@ Miscellaneous changes scons in order to fix an issue with scons and command line lengths when ccache is enabled. However, some recipes may be using older scons versions which don't support this argument. If that is the case you can set the following in the recipe in order - to disable this:: + to disable this: + + .. code-block:: bitbake SCONS_MAXLINELENGTH = "" diff --git a/documentation/migration-guides/migration-5.1.rst b/documentation/migration-guides/migration-5.1.rst index 70e034bc846f..9ea68d8d5aca 100644 --- a/documentation/migration-guides/migration-5.1.rst +++ b/documentation/migration-guides/migration-5.1.rst @@ -18,7 +18,9 @@ S = ${WORKDIR} no longer supported ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If a recipe has :term:`S` set to be :term:`WORKDIR`, this is no longer -supported, and an error will be issued. The recipe should be changed to:: +supported, and an error will be issued. The recipe should be changed to: + +.. code-block:: bitbake S = "${UNPACKDIR}" @@ -59,7 +61,9 @@ longer the case. This means the check in ``do_unpack_qa`` triggers where :term:`S` is not created by a recipe while it didn't happen before. This can require to add an :term:`S` definition to a recipe that only uses ``file://`` :term:`SRC_URI` entries. To be consistent, the following pattern is -recommended:: +recommended: + +.. code-block:: bitbake S = "${UNPACKDIR}" @@ -105,7 +109,9 @@ Go language changes - After dropping the custom :ref:`ref-tasks-unpack` from the :ref:`ref-classes-go` class, go recipes should now add ``destsuffix=${GO_SRCURI_DESTSUFFIX}`` to their :term:`SRC_URI` to extract - them in the appropriate path. An example would be:: + them in the appropriate path. An example would be: + + .. code-block:: bitbake SRC_URI = "git://go.googlesource.com/example;branch=master;protocol=https;destsuffix=${GO_SRCURI_DESTSUFFIX}" diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst index 77a11fe27047..c30f4097aac1 100644 --- a/documentation/migration-guides/migration-5.2.rst +++ b/documentation/migration-guides/migration-5.2.rst @@ -29,7 +29,9 @@ should be manually added to the :term:`IMAGE_FEATURES` variable. These are: - ``empty-root-password`` - ``post-install-logging`` -Such a statement would be:: +Such a statement would be: + +.. code-block:: bitbake IMAGE_FEATURES += "allow-empty-password allow-root-login empty-root-password post-install-logging" @@ -177,11 +179,15 @@ c++/binutils)" ` in ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :term:`UBOOT_ENTRYPOINT` variable should now be defined with a leading -``0x`` to its value. For example, consider the following assignment:: +``0x`` to its value. For example, consider the following assignment: + +.. code-block:: bitbake UBOOT_ENTRYPOINT ?= "20008000" -This should now be replaced by:: +This should now be replaced by: + +.. code-block:: bitbake UBOOT_ENTRYPOINT ?= "0x20008000" @@ -191,7 +197,9 @@ Git fetcher: support for multiple revisions per URL removed The support for having multiple Git revisions per URL in :term:`SRC_URI` was removed from BitBake, which means the following syntax is not supported -anymore:: +anymore: + +.. code-block:: bitbake SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY" SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx" @@ -203,7 +211,9 @@ take care of the Git checkout. This removal simplifies the code logic in several places. If one of your recipes is using this mechanism, you can split the code source -fetching into two separate entries:: +fetching into two separate entries: + +.. code-block:: bitbake SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \ git://some.host/somepath;bareclone=1;branch=branchY;name=nameY" @@ -214,7 +224,9 @@ Git fetcher: Branch parameter now required in :term:`SRC_URI` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``branch`` parameter is now required when specifying a Git repository in -:term:`SRC_URI`, for example:: +:term:`SRC_URI`, for example: + +.. code-block:: bitbake SRC_URI = "git://some.host/somepath;branch=branchX" diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst index 38c7d6771667..d947a4de7a1a 100644 --- a/documentation/migration-guides/migration-5.3.rst +++ b/documentation/migration-guides/migration-5.3.rst @@ -50,7 +50,9 @@ in: https://lists.openembedded.org/g/openembedded-architecture/message/2179 If a recipe has :term:`S` set to be ``${``\ :term:`WORKDIR`\ ``}/something``, this is no longer supported, and an error will be issued. The recipe should be -changed to:: +changed to: + +.. code-block:: bitbake S = "${UNPACKDIR}/something" @@ -69,7 +71,9 @@ This location matches the default value of :term:`S` set by bitbake.conf, so :te setting in recipes can and should be removed. Note that when :term:`S` is set to a subdirectory of the git checkout, then it -should be instead adjusted according to the previous point:: +should be instead adjusted according to the previous point: + +.. code-block:: bitbake S = "${UNPACKDIR}/${BP}/something" @@ -112,13 +116,17 @@ assignment in recipes:: : has a lack of whitespace around the assignment: '' -For example, the following assignments would print a warning:: +For example, the following assignments would print a warning: + +.. code-block:: bitbake FOO="bar" FOO= "bar" FOO ="bar" -These should be replaced by:: +These should be replaced by: + +.. code-block:: bitbake FOO = "bar" @@ -179,14 +187,18 @@ overview of the removed firmware. The :term:`CPPFLAGS`, :term:`CFLAGS`, :term:`CXXFLAGS` and :term:`LDFLAGS` variables used to have hard assignments in the :ref:`ref-classes-native` and -:ref:`ref-classes-nativesdk` classes, respectively:: +:ref:`ref-classes-nativesdk` classes, respectively: + +.. code-block:: bitbake CPPFLAGS = "${BUILD_CPPFLAGS}" CFLAGS = "${BUILD_CFLAGS}" CXXFLAGS = "${BUILD_CXXFLAGS}" LDFLAGS = "${BUILD_LDFLAGS}" -and:: +and: + +.. code-block:: bitbake CPPFLAGS = "${BUILDSDK_CPPFLAGS}" CFLAGS = "${BUILDSDK_CFLAGS}" @@ -206,11 +218,15 @@ three**: target, :ref:`ref-classes-native` and :ref:`ref-classes-nativesdk` contexts. Recipes that unknowingly relied on this behavior should change these assignments -to use ``TARGET_`` variables instead, for example:: +to use ``TARGET_`` variables instead, for example: + +.. code-block:: bitbake CFLAGS += "something" -to:: +to: + +.. code-block:: bitbake TARGET_CFLAGS += "something" @@ -305,7 +321,9 @@ The following classes have been removed in this release: #. Make sure to include ``kernel-fit-extra-artifacts`` in your :term:`KERNEL_CLASSES` variable to ensure the required files are exposed to the :term:`DEPLOY_DIR_IMAGE` - directory:: + directory: + + .. code-block:: bitbake KERNEL_CLASSES += "kernel-fit-extra-artifacts" diff --git a/documentation/migration-guides/migration-6.0.rst b/documentation/migration-guides/migration-6.0.rst index 5ad284600002..54323d5961aa 100644 --- a/documentation/migration-guides/migration-6.0.rst +++ b/documentation/migration-guides/migration-6.0.rst @@ -88,7 +88,9 @@ This does not change the default init manager of the :term:`Poky` distribution, which remains :wikipedia:`SysVinit `. Reverting to :wikipedia:`SysVinit ` can be done by specifying the -:term:`INIT_MANAGER` in your own :term:`DISTRO` configuration file:: +:term:`INIT_MANAGER` in your own :term:`DISTRO` configuration file: + +.. code-block:: bitbake INIT_MANAGER = "sysvinit" @@ -189,7 +191,9 @@ Previously, setting :term:`DEBUG_BUILD` to "1" globally would prevent the changed so that only **target** binaries are stripped when this variable is set. This change can be reverted by setting the two following lines in a -:term:`configuration file`:: +:term:`configuration file`: + +.. code-block:: bitbake INHIBIT_SYSROOT_STRIP:class-cross = "${@oe.utils.vartrue('DEBUG_BUILD', '1', '', d)}" INHIBIT_SYSROOT_STRIP:class-native = "${@oe.utils.vartrue('DEBUG_BUILD', '1', '', d)}" @@ -202,13 +206,17 @@ U-Boot configuration flow changes (:ref:`ref-classes-uboot-config`) ------------------------------------------------------------------- Declaring multiple U-Boot configurations used to be entirely defined by -one :term:`UBOOT_CONFIG` variable flag per configuration, e.g.:: +one :term:`UBOOT_CONFIG` variable flag per configuration, e.g.: + +.. code-block:: bitbake UBOOT_CONFIG ??= "foo bar" UBOOT_CONFIG[foo] = "config,images,binary" UBOOT_CONFIG[bar] = "config2,images2,binary2" -This has now been split into more variable flags, e.g.:: +This has now been split into more variable flags, e.g.: + +.. code-block:: bitbake UBOOT_CONFIG ??= "foo bar" UBOOT_CONFIG[foo] = "config" @@ -233,7 +241,9 @@ See commit :oecore_rev:`cd9e7304481b24b27df61c03ad73496d18e4d47c` for more infor .. note:: Single configuration builds have not changed and are still declared using the - following statements:: + following statements: + + .. code-block:: bitbake UBOOT_MACHINE = "config" UBOOT_BINARY = "u-boot.bin" @@ -249,7 +259,9 @@ Variables to the Environment>` directive. These ``export`` statements have been moved to the :ref:`ref-classes-pkgconfig` class, meaning recipes using these variables that not yet inheriting the -:ref:`ref-classes-pkgconfig` class should now inherit it with:: +:ref:`ref-classes-pkgconfig` class should now inherit it with: + +.. code-block:: bitbake inherit pkgconfig @@ -322,11 +334,15 @@ The ``cve-check`` class was removed and replaced by the Users currently using the ``cve-check`` class are advised to switch to :ref:`ref-classes-sbom-cve-check`: -- The following assignment:: +- The following assignment: + + .. code-block:: bitbake INHERIT += "cve-check" - Should be removed and replaced by:: + Should be removed and replaced by: + + .. code-block:: bitbake OE_FRAGMENTS += "core/yocto/sbom-cve-check" @@ -345,7 +361,9 @@ Users currently using the ``cve-check`` class are advised to switch to - The ``cve-check`` class output summary file (deployed in the :term:`DEPLOY_DIR_IMAGE`) ending with ``.cve.txt`` is no longer deployed by default but can be brought back by adding the following statement - to a configuration file:: + to a configuration file: + + .. code-block:: bitbake SBOM_CVE_CHECK_EXPORT_VARS:append = " SBOM_CVE_CHECK_EXPORT_SUMMARY" @@ -395,11 +413,15 @@ the console when used:: Using the ``--sector-size`` command-line argument can be done through the :term:`WIC_CREATE_EXTRA_ARGS` variable. -For example, a previous assignment to :term:`WIC_SECTOR_SIZE`:: +For example, a previous assignment to :term:`WIC_SECTOR_SIZE`: + +.. code-block:: bitbake WIC_SECTOR_SIZE = "4096" -Should be replaced by:: +Should be replaced by: + +.. code-block:: bitbake WIC_CREATE_EXTRA_ARGS += "--sector-size 4096" diff --git a/documentation/migration-guides/migration-6.1.rst b/documentation/migration-guides/migration-6.1.rst index 025b8f70926c..019a3495cc76 100644 --- a/documentation/migration-guides/migration-6.1.rst +++ b/documentation/migration-guides/migration-6.1.rst @@ -44,17 +44,23 @@ version 4.20. The same functionality provided by ``groupmems`` can be achieved with the ``usermod`` command. Assignments made to the :term:`GROUPMEMS_PARAM` variable can be converted to use -:term:`USERMOD_PARAMS`, by replacing:: +:term:`USERMOD_PARAMS`, by replacing: + +.. code-block:: bitbake GROUPMEMS_PARAM:${PN} = "--add user --group group1; \ --add user --group group2" -With:: +With: + +.. code-block:: bitbake USERMOD_PARAM:${PN} = "--append --groups group1 user; \ --append --groups group2 user" -Or written more simply as:: +Or written more simply as: + +.. code-block:: bitbake USERMOD_PARAM:${PN} = "--append --groups group1,group2 user" diff --git a/documentation/migration-guides/release-notes-4.0.rst b/documentation/migration-guides/release-notes-4.0.rst index e9e694952799..683873e94c70 100644 --- a/documentation/migration-guides/release-notes-4.0.rst +++ b/documentation/migration-guides/release-notes-4.0.rst @@ -21,7 +21,9 @@ New Features / Enhancements in 4.0 its autobuilder. If the network connection between our server and your machine is faster than you would build recipes from source, you can try to speed up your builds by using such Shared State and Hash - Equivalence by setting:: + Equivalence by setting: + + .. code-block:: bitbake BB_SIGNATURE_HANDLER = "OEEquivHash" BB_HASHSERVE = "auto" diff --git a/documentation/migration-guides/release-notes-4.3.rst b/documentation/migration-guides/release-notes-4.3.rst index 76afd16e84fc..9ec3f3a0a2ad 100644 --- a/documentation/migration-guides/release-notes-4.3.rst +++ b/documentation/migration-guides/release-notes-4.3.rst @@ -45,7 +45,9 @@ New Features / Enhancements in 4.3 Code can now know which layer a recipe is coming from through the newly added :term:`FILE_LAYERNAME` variable. This has been added as an override of the form ``layer-``. In particular, - this means QA checks can now be layer specific, for example:: + this means QA checks can now be layer specific, for example: + + .. code-block:: bitbake ERROR_QA:layer-core:append = " patch-status" diff --git a/documentation/migration-guides/release-notes-5.0.rst b/documentation/migration-guides/release-notes-5.0.rst index b802e7c1718e..29d53df58b97 100644 --- a/documentation/migration-guides/release-notes-5.0.rst +++ b/documentation/migration-guides/release-notes-5.0.rst @@ -195,7 +195,9 @@ New Features / Enhancements in 5.0 - New ``inherit_defer`` statement which works as :ref:`inherit ` does, except that it is only evaluated at the end of parsing - --- recommended where a conditional expression is used, e.g.:: + --- recommended where a conditional expression is used, e.g.: + + .. code-block:: bitbake inherit_defer ${@bb.utils.contains('PACKAGECONFIG', 'python', 'python3targetconfig', '', d)} diff --git a/documentation/migration-guides/release-notes-5.3.rst b/documentation/migration-guides/release-notes-5.3.rst index ee9df424ee2e..8d098cd7fec8 100644 --- a/documentation/migration-guides/release-notes-5.3.rst +++ b/documentation/migration-guides/release-notes-5.3.rst @@ -92,7 +92,9 @@ New Features / Enhancements in |yocto-ver| distro/... Sets DISTRO = ... In the above example, this means that the :term:`MACHINE` of - :term:`DISTRO` can be overridden with:: + :term:`DISTRO` can be overridden with: + + .. code-block:: bitbake OE_FRAGMENTS += "machine/qemuarm64 distro/poky-bleeding" @@ -928,7 +930,9 @@ New Features / Enhancements in |yocto-ver| :ref:`qa-check-pep517-backend` QA check. - The :ref:`ref-classes-ccache` class now supports using `Ccache` for native - recipes when the local build configuration contains:: + recipes when the local build configuration contains: + + .. code-block:: bitbake ASSUME_PROVIDED += "ccache-native" HOSTTOOLS += "ccache" From patchwork Wed Aug 26 01:34:50 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96333 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id A8F03C61DBD for ; Wed, 26 Aug 2026 01:35:21 +0000 (UTC) Received: from mail-qk1-f176.google.com (mail-qk1-f176.google.com [209.85.222.176]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3403.1787708117293531127 for ; Tue, 25 Aug 2026 18:35:17 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=e7WNjn/3; spf=pass (domain: gmail.com, ip: 209.85.222.176, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f176.google.com with SMTP id af79cd13be357-92f03daaa97so21852285a.2 for ; Tue, 25 Aug 2026 18:35:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708116; x=1788312916; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=8tiEudje76MWH4u4545z/gdOUxrvHhOkO2l6SJNQQZI=; b=e7WNjn/3oc5E5nhRV5qXsiZfToFQZzSFhhmsfh/Erbmfu+3qD17rD4PZ0iyYE4ZPMw wUzNVlT5B2UfeH3bkDDrmQNaaBx5RVWS7IGM866TqDv5J8YLjUwbiGzCM+xQO3p+RZTX fcQNuuYoxgyM5I1c9ZgfdYLTX9h/XKCxXmPxT8lNc3UhaW+BW7ICZUIxp0lftTKvpnAF u0v3S76216EgrsTjvnKvZJOVa6R1kkJgDYgQgJcYFbS3oGs6lUrY1/uFOIbMQPzQzgvq No18+D8LutwCXIGvVqxjFA6yhFik8HSvMI5DMnPhrH6ZG60kGF4bUmZ0suuIJrlePNy4 GxWQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708116; x=1788312916; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=8tiEudje76MWH4u4545z/gdOUxrvHhOkO2l6SJNQQZI=; b=UV3TqWQHpJRaxzWMekG+rKsrzY1utrmL5tRM4sh95XjsLaw9IxLzxxFS/zpnOrhkO4 PEu/4qFERneqUcNexqyyLnUMlRRe+Z8fWT23ndDhcgNapMcHfgmZKR3iA8/h0D7lF41p Ae4PKDB0eOZr4iR3/HkE72xNnbMQp6IwFyUXE+jZgRKDG4DbUu82lLuPP0yHxyObDHCB f+F05IkDg3PfG5EGKar9/5Bp++yk65VvlIQdRZlJwT56Y8uymfATb+WXBbIDe3LxsKyE G4lCqDIjF+9c1u+YL9gwfl2n9FzvbGapPQW8YrqAqwgrbuPYZ+G4KJrPCVPH+LihaxXt 6KHA== X-Gm-Message-State: AFuF++mOFR0fLpJUb+P+ci4774PzAz4zMiDW+V4pUsJuyzo2AH4bA9P9 2rbI1i6crmfustCTHR0NVbeAduaGlY6egBwhlMpntdn1+Lu2NI4nCELcDXw5Tj2S X-Gm-Gg: AR+sD13+ljFNy9B0NPHqHZSM3xXhzQeSDAtRRcLZiSnCQzep82j1aH6OxDr6ehcML43 xeyyS8kECMOLRKm+Z1iXaH8mXdAe3Of5aLxIrl4Q9zxl7R+MvRsP6CpBypB1BZ49GDBQCWVM7lB aNyTfQpbOfZjaQ+dEoOgJXthI2xfHJQScskGoVJ0iPfRF6JXQn3imbGduP5JFLjA5Iy0dbPhnl9 Lm68+9/mC3vZg/0HO3TZDIZDDoBz3aij8qdKTOXYZky4klA7PZ7lxqo5Ni70s15dpGb8Udy0+c2 pEqofKPSfGToWtQEB4V80gxnRGDmJXhK42aUuUbLyk2S6F2gieb6Q8uSIFbErb3e+ancMnu5a2E x9UDjXho0dUYaKg81M4hJ7W2zTBT8sOCnbQ0ZKYu6FDe6cEFXizx+EXf0ObNrecaqbYW8uH0lal +IeKW44GCS08KzF6j5qSPEgYqqiMA7/zuwFQkeh0OVg/vFLvq06TjOtK1BsR+Ow1skghOf1zH+X To2niv3pC4rtpaKRb70qvtDBJbi48v8+hnZeE4GDQ== X-Received: by 2002:a05:620a:2702:b0:934:ab73:ac53 with SMTP id af79cd13be357-9377fe450a4mr311824985a.0.1787708115888; Tue, 25 Aug 2026 18:35:15 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.14 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:15 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 05/10] kernel-dev: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:50 -0400 Message-ID: <20260826013502.2674000-6-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:21 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10350 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 41 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- documentation/kernel-dev/advanced.rst | 48 +++++++++++---- documentation/kernel-dev/common.rst | 88 ++++++++++++++++++++------- documentation/kernel-dev/faq.rst | 8 ++- 3 files changed, 108 insertions(+), 36 deletions(-) diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst index b36bea67ccd2..644fa2bd0a3d 100644 --- a/documentation/kernel-dev/advanced.rst +++ b/documentation/kernel-dev/advanced.rst @@ -66,7 +66,9 @@ to indicate the branch. .. note:: You can use the :term:`KBRANCH` value to define an alternate branch typically - with a machine override as shown here from the ``meta-yocto-bsp`` layer:: + with a machine override as shown here from the ``meta-yocto-bsp`` layer: + + .. code-block:: bitbake KBRANCH:beaglebone-yocto = "standard/beaglebone" @@ -103,13 +105,17 @@ You can use the variable to include features (configuration fragments, patches, or both) that are not already included by the :term:`KMACHINE` and :term:`LINUX_KERNEL_TYPE` variable combination. For example, to include a -feature specified as "features/netfilter/netfilter.scc", specify:: +feature specified as "features/netfilter/netfilter.scc", specify: + +.. code-block:: bitbake KERNEL_FEATURES += "features/netfilter/netfilter.scc" To include a feature called "cfg/sound.scc" just for the ``qemux86`` machine, -specify:: +specify: + +.. code-block:: bitbake KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc" @@ -359,13 +365,17 @@ variable in the kernel recipe selects the kernel type. For example, in the ``linux-yocto_4.12.bb`` kernel recipe found in ``meta/recipes-kernel/linux``, a :ref:`require ` directive includes the ``meta/recipes-kernel/linux/linux-yocto.inc`` file, -which has the following statement that defines the default kernel type:: +which has the following statement that defines the default kernel type: + +.. code-block:: bitbake LINUX_KERNEL_TYPE ??= "standard" Another example would be the real-time kernel (i.e. ``linux-yocto-rt_4.12.bb``). This kernel recipe directly sets the kernel -type as follows:: +type as follows: + +.. code-block:: bitbake LINUX_KERNEL_TYPE = "preempt-rt" @@ -514,7 +524,9 @@ description file match. To separate your kernel policy from your hardware configuration, you include a kernel type (``ktype``), such as "standard". In the previous -example, this is done using the following:: +example, this is done using the following: + +.. code-block:: bitbake include ktypes/standard/standard.scc @@ -524,11 +536,15 @@ policy. See the ":ref:`kernel-dev/advanced:kernel types`" section for more information. To aggregate common configurations and features specific to the kernel -for `mybsp`, use the following:: +for `mybsp`, use the following: + +.. code-block:: bitbake include mybsp.scc -You can see that in the BeagleBone example with the following:: +You can see that in the BeagleBone example with the following: + +.. code-block:: bitbake include beaglebone.scc @@ -713,7 +729,9 @@ value when changing the content of files not explicitly listed in the If the BSP description is in recipe space, you cannot simply list the ``*.scc`` in the :term:`SRC_URI` statement. You need to use the following -form from your kernel append file:: +form from your kernel append file: + +.. code-block:: bitbake SRC_URI:append:myplatform = " \ file://myplatform;type=kmeta;destsuffix=myplatform \ @@ -739,7 +757,9 @@ reside in a separate repository. The OpenEmbedded build system adds the Metadata to the build as a "type=kmeta" repository through the :term:`SRC_URI` variable. As an example, consider the following :term:`SRC_URI` statement from the -``linux-yocto_5.15.bb`` kernel recipe:: +``linux-yocto_5.15.bb`` kernel recipe: + +.. code-block:: bitbake SRC_URI = "git://git.yoctoproject.org/linux-yocto.git;name=machine;branch=${KBRANCH};protocol=https \ git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-5.15;destsuffix=${KMETA};protocol=https" @@ -784,7 +804,9 @@ This is why a recipe-space BSP description must be delivered as a :term:`SRC_URI` (see the ":ref:`kernel-dev/advanced:recipe-space metadata`" section). To have your description discovered, place it in a ``type=kmeta`` directory and set -:term:`KMACHINE` so the tools locate it:: +:term:`KMACHINE` so the tools locate it: + +.. code-block:: bitbake KMACHINE:myplatform ?= "myplatform" @@ -868,7 +890,9 @@ patches into a feature. Once you have a new branch, you can set up your kernel Metadata to use the branch a couple different ways. In the recipe, you can specify the -new branch as the :term:`KBRANCH` to use for the board as follows:: +new branch as the :term:`KBRANCH` to use for the board as follows: + +.. code-block:: bitbake KBRANCH = "mynewbranch" diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst index 948718433440..8b80a4afde59 100644 --- a/documentation/kernel-dev/common.rst +++ b/documentation/kernel-dev/common.rst @@ -60,7 +60,9 @@ section: In this example we wish to build for qemux86 so we must set the :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``:: + As described we do this by appending to ``conf/local.conf``: + + .. code-block:: bitbake MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" @@ -156,7 +158,9 @@ section: In this example we wish to build for qemux86 so we must set the :term:`MACHINE` variable to "qemux86" and also add the "kernel-modules". - As described we do this by appending to ``conf/local.conf``:: + As described we do this by appending to ``conf/local.conf``: + + .. code-block:: bitbake MACHINE = "qemux86" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules" @@ -302,7 +306,9 @@ home directory: ``meta-mylayer/recipes-kernel/linux`` directory and create the kernel's append file. This example uses the ``linux-yocto-4.12`` kernel. Thus, the name of the append file is - ``linux-yocto_4.12.bbappend``:: + ``linux-yocto_4.12.bbappend``: + + .. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" @@ -354,7 +360,9 @@ The append file should initially extend the :term:`FILESPATH` search path by prepending the directory that contains your files to the :term:`FILESEXTRAPATHS` -variable as follows:: +variable as follows: + +.. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" @@ -380,7 +388,9 @@ As an example, consider the following append file used by the BSPs in Here are the contents of this file. Be aware that the actual commit ID strings in this example listing might be different than the actual -strings in the file from the ``meta-yocto-bsp`` layer upstream:: +strings in the file from the ``meta-yocto-bsp`` layer upstream: + +.. code-block:: bitbake KBRANCH:genericx86 = "v6.1/standard/base" KBRANCH:genericx86-64 = "v6.1/standard/base" @@ -436,7 +446,9 @@ For example, suppose you had some configuration options in a file called ``network_configs.cfg``. You can place that file inside a directory named ``linux-yocto`` and then add a :term:`SRC_URI` statement such as the following to the append file. When the OpenEmbedded build system builds -the kernel, the configuration options are picked up and applied:: +the kernel, the configuration options are picked up and applied: + +.. code-block:: bitbake SRC_URI += "file://network_configs.cfg" @@ -444,7 +456,9 @@ To group related configurations into multiple files, you perform a similar procedure. Here is an example that groups separate configurations specifically for Ethernet and graphics into their own files and adds the configurations by using a :term:`SRC_URI` statement like -the following in your append file:: +the following in your append file: + +.. code-block:: bitbake SRC_URI += "file://myconfig.cfg \ file://eth.cfg \ @@ -488,7 +502,9 @@ reference them in :term:`SRC_URI` statements. For example, you can apply a three-patch series by adding the following -lines to your linux-yocto ``.bbappend`` file in your layer:: +lines to your linux-yocto ``.bbappend`` file in your layer: + +.. code-block:: bitbake SRC_URI += "file://0001-first-change.patch" SRC_URI += "file://0002-second-change.patch" @@ -518,7 +534,9 @@ If you have a complete, working Linux kernel ``.config`` file you want to use for the configuration, as before, copy that file to the appropriate ``${PN}`` directory in your layer's ``recipes-kernel/linux`` directory, and rename the copied file to "defconfig". Then, add the -following lines to the linux-yocto ``.bbappend`` file in your layer:: +following lines to the linux-yocto ``.bbappend`` file in your layer: + +.. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" SRC_URI += "file://defconfig" @@ -535,7 +553,9 @@ You can also use a regular ``defconfig`` file, as generated by the task instead of a complete ``.config`` file. This only specifies the non-default configuration values. You need to additionally set :term:`KCONFIG_MODE` -in the linux-yocto ``.bbappend`` file in your layer:: +in the linux-yocto ``.bbappend`` file in your layer: + +.. code-block:: bitbake KCONFIG_MODE = "alldefconfig" @@ -565,7 +585,9 @@ with the following content (without indentation):: Next, include this configuration fragment and extend the :term:`FILESPATH` variable in your -``.bbappend`` file:: +``.bbappend`` file: + +.. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" SRC_URI += "file://8250.cfg" @@ -584,7 +606,9 @@ It might be desirable to have kernel configuration fragment support through a ``defconfig`` file that is pulled from the kernel source tree for the configured machine. By default, the OpenEmbedded build system looks for ``defconfig`` files in the layer used for Metadata, which is -"out-of-tree", and then configures them using the following:: +"out-of-tree", and then configures them using the following: + +.. code-block:: bitbake SRC_URI += "file://defconfig" @@ -604,7 +628,9 @@ form:: Here is an example that assigns the :term:`KBUILD_DEFCONFIG` variable utilizing an override for the "raspberrypi2" :term:`MACHINE` and provides the path to the "in-tree" ``defconfig`` file to be used for a Raspberry Pi 2, which is based on -the Broadcom 2708/2709 chipset:: +the Broadcom 2708/2709 chipset: + +.. code-block:: bitbake KBUILD_DEFCONFIG:raspberrypi2 ?= "bcm2709_defconfig" @@ -841,7 +867,9 @@ Section. $ cd bitbake-builds/build/conf - Add the following to the ``local.conf``:: + Add the following to the ``local.conf``: + + .. code-block:: bitbake SRC_URI:pn-linux-yocto = "git:///path-to/linux-yocto-4.12;protocol=file;name=machine;branch=standard/base; \ git:///path-to/yocto-kernel-cache;protocol=file;type=kmeta;name=meta;branch=yocto-4.12;destsuffix=${KMETA}" @@ -912,7 +940,9 @@ Section. the OpenEmbedded build system to find the patch. The append file needs to be in your layer's ``recipes-kernel/linux`` directory and it must be named ``linux-yocto_4.12.bbappend`` and have the following - contents:: + contents: + + .. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" SRC_URI += "file://0001-calibrate.c-Added-some-printk-statements.patch" @@ -1087,7 +1117,9 @@ your layer's ``recipes-kernel/linux`` directory, and rename the copied file to "defconfig" (e.g. ``~/meta-mylayer/recipes-kernel/linux/linux-yocto/defconfig``). Then, add the following lines to the linux-yocto ``.bbappend`` file in your -layer:: +layer: + +.. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" SRC_URI += "file://defconfig" @@ -1197,7 +1229,9 @@ options in a file called ``myconfig.cfg``. If you put that file inside a directory named ``linux-yocto`` that resides in the same directory as the kernel's append file within your layer and then add the following statements to the kernel's append file, those configuration options will -be picked up and applied when the kernel is built:: +be picked up and applied when the kernel is built: + +.. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" SRC_URI += "file://myconfig.cfg" @@ -1206,7 +1240,9 @@ As mentioned earlier, you can group related configurations into multiple files and name them all in the :term:`SRC_URI` statement as well. For example, you could group separate configurations specifically for Ethernet and graphics into their own files and add those by using a -:term:`SRC_URI` statement like the following in your append file:: +:term:`SRC_URI` statement like the following in your append file: + +.. code-block:: bitbake SRC_URI += "file://myconfig.cfg \ file://eth.cfg \ @@ -1510,7 +1546,9 @@ Here are some basic steps you can use to work with your own sources: triggers an explicit build failure. You must change it to match a list of the machines that your new recipe supports. For example, to support the ``qemux86`` and ``qemux86-64`` machines, use the - following form:: + following form: + + .. code-block:: bitbake COMPATIBLE_MACHINE = "qemux86|qemux86-64" @@ -1622,7 +1660,9 @@ them appropriately for your machine configuration file: - :term:`MACHINE_EXTRA_RRECOMMENDS` Modules are often not required for boot and can be excluded from certain -build configurations. The following allows for the most flexibility:: +build configurations. The following allows for the most flexibility: + +.. code-block:: bitbake MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" @@ -1769,7 +1809,9 @@ build. a similarly named configuration fragment file ``test.cfg``. #. *Add the Feature File to SRC_URI:* Add the ``.scc`` file to the - recipe's :term:`SRC_URI` statement:: + recipe's :term:`SRC_URI` statement: + + .. code-block:: bitbake SRC_URI += "file://test.scc" @@ -1778,7 +1820,9 @@ build. #. *Specify the Feature as a Kernel Feature:* Use the :term:`KERNEL_FEATURES` statement to specify the feature as a kernel - feature:: + feature: + + .. code-block:: bitbake KERNEL_FEATURES += "test.scc" diff --git a/documentation/kernel-dev/faq.rst b/documentation/kernel-dev/faq.rst index 4dffa90dbd03..a5cd09dcfbaa 100644 --- a/documentation/kernel-dev/faq.rst +++ b/documentation/kernel-dev/faq.rst @@ -57,7 +57,9 @@ These other variables are useful for installing specific modules: For example, set the following in the ``qemux86.conf`` file to include the ``ab123`` kernel modules with images built for the ``qemux86`` -machine:: +machine: + +.. code-block:: bitbake MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123" @@ -70,7 +72,9 @@ How do I change the Linux kernel command line? The Linux kernel command line is typically specified in the machine config using the :term:`APPEND` variable. For example, you can add some helpful debug information doing the -following:: +following: + +.. code-block:: bitbake APPEND += "printk.time=y initcall_debug debug" From patchwork Wed Aug 26 01:34:51 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96334 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id C856EC61DC6 for ; Wed, 26 Aug 2026 01:35:21 +0000 (UTC) Received: from mail-qk1-f177.google.com (mail-qk1-f177.google.com [209.85.222.177]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.3465.1787708120058549870 for ; Tue, 25 Aug 2026 18:35:20 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=E4mTmzq0; spf=pass (domain: gmail.com, ip: 209.85.222.177, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f177.google.com with SMTP id af79cd13be357-92e50a650a0so18693885a.1 for ; Tue, 25 Aug 2026 18:35:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708119; x=1788312919; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=M5UmsDj0RVhN7agTi1yCgmdh8H45nE3aVZ/trzv8HXs=; b=E4mTmzq0a3k+QEzn4JlMTRCYlkQ4mS3sT+wndH4CQoh1/FpM+m6b8b6IA4nOFaUyiQ LUskyuaJPBiUE8FenFFzvTXHVKlqZ0doG2L4pcU02RLxwmHyNMx50QN+KicmlOLS0wVd yPRZ0wtyGeronA2tfzAWNlI12dvFAvbVdwaDkSdbR8JaT41DPKO3nWQD1iCRcK82Ajgs MYd9hSoAmf3RKIQJawLwp1WddNwdyc57JIOzZIoOGlvh9fCxAx4WoKceyhWc4/wNDFjK jpD2mLhie3IRRU9eGk9qruO4tUIGKWpizSq/FpRi8LlObRbYJtZc2Y6A+plhjA/srm/b HbTQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708119; x=1788312919; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=M5UmsDj0RVhN7agTi1yCgmdh8H45nE3aVZ/trzv8HXs=; b=qMxdSGHFgAt93j0bF/DoxbXglQIxYsq1Wzu8hRgggmvciC3CxKyAzwG8OIXRhm2rQd hkqM2TLzSP9fCZx8VBI4/zWk0CykzCuTRcir7f9sC7cGkTGnrxUqfWwkwloyobT4Zn4A CPXAtjCweJ5uBol1O3MIDpnfUCWNiyrCV5JA5qsYPQG0R+bDkYH5IyPnWeppO9Du8P8N TuQ4yDH0qcqrkTuvZnRrqJHp3OaOBTI6qPsVkaPzqdfsVjDyZwymysmTQluoL8ej2Hwe Ft5DJTdiYXk6nRoWgTQ/ooGPY6gEWq0z1FFql/qg2zYZMkVagOSwK94Kmx2fVdhiq0AN M8oA== X-Gm-Message-State: AFuF++nmVdXqGi/BMYoibvZwdgXoz33yojjpGXTsKSBdY0LmvCww9jeb WASGmmqBPYNOkeVUQYL7ruwGchU/kK2j2QlMo+HmSNSeIrnRRjVHUI5rOFQVltvD X-Gm-Gg: AR+sD10UX21Xk+VpfCJe2nb+eJoVkm2kbMzhMcHfZAMl4B6EtdSywk6dZUwnts7YpLM hHRg+EVKFxDnY07Z7EsYbVEjMoDdXh4xFBGgJJh15HIS2wUB3fkGz7I5y3ZJoscpmleCAc12q2C 5HfkJ3PzlKctWJJEzJy80D5aC+e9EA9n58uGAfXBOuK/GRmElanEsLyhl8JTkEoXE6QEczEQ0ux KO9jTe6bowfX55RcDClHmWrlwgr0B/eY1Cn2cFEESJ8PYzSPPrM3PuOotedVzDZoDCa0IOg9DOE h4vfPaM49bgRmaCc2Yp9Xg7D80ZH9gOerKPu1930g+MH9uxFcfFXFx1hQSXwbRazeXLNAcgt4Ik 7cY5Xja9/ArTd6RPorVs8vtMLQqPm5q0iDhF7xtq/IOEraaZEmN6FkzkiCazD28rLwLYa2Zllkp tPPeEH3ANC2sy3DOUdw9IKISe20cW3ScMPF1S1+HruN+KEC+D/AU9NP5Nh9o6Wj16aZESOuYI+2 UrUropT4ZrA6b3pBzTjTnmgOecU2NBH X-Received: by 2002:a05:620a:57c3:b0:937:1995:227b with SMTP id af79cd13be357-9377fe3d757mr242856185a.0.1787708118817; Tue, 25 Aug 2026 18:35:18 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.16 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:16 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 06/10] test-manual: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:51 -0400 Message-ID: <20260826013502.2674000-7-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:21 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10351 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 27 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- documentation/test-manual/intro.rst | 4 +- documentation/test-manual/ptest.rst | 24 ++++++--- .../test-manual/reproducible-builds.rst | 8 ++- documentation/test-manual/runtime-testing.rst | 52 ++++++++++++++----- 4 files changed, 66 insertions(+), 22 deletions(-) diff --git a/documentation/test-manual/intro.rst b/documentation/test-manual/intro.rst index 4ddc9851f824..614622daabfb 100644 --- a/documentation/test-manual/intro.rst +++ b/documentation/test-manual/intro.rst @@ -253,7 +253,9 @@ Tests map into the codebase as follows: - The code for these tests resides in ``meta/lib/oeqa/runtime/cases/``. - - You need to set the :term:`IMAGE_CLASSES` variable as follows:: + - You need to set the :term:`IMAGE_CLASSES` variable as follows: + + .. code-block:: bitbake IMAGE_CLASSES += "testimage" diff --git a/documentation/test-manual/ptest.rst b/documentation/test-manual/ptest.rst index 2b86722145da..9c4b74f44c58 100644 --- a/documentation/test-manual/ptest.rst +++ b/documentation/test-manual/ptest.rst @@ -38,7 +38,9 @@ Adding package testing to your image is done in two steps: #. Identify which of those ptest packages to add to your image. First, in order to build all ptest packages, add the following line -to a :term:`configuration file`:: +to a :term:`configuration file`: + +.. code-block:: bitbake DISTRO_FEATURES:append = " ptest" @@ -46,12 +48,16 @@ Note that this will cause all ptest packages to be built and packaged, but will not add any of those packages to your image; that comes in the next step. You can then add ptest packages to your image in one of two ways. -#. If you want to add *all* of the generated ptest packages, add the line:: +#. If you want to add *all* of the generated ptest packages, add the line: + + .. code-block:: bitbake EXTRA_IMAGE_FEATURES += "ptest-pkgs" #. On the other hand, if you want to add only a select few of the ptest - packages, you can use some variation of:: + packages, you can use some variation of: + + .. code-block:: bitbake IMAGE_INSTALL:append = " e2fsprogs-ptest zlib-ptest" @@ -95,7 +101,9 @@ you need to prepare the recipes that build the packages you want to test. Here is what you have to do for each recipe: - *Be sure the recipe inherits the* :ref:`ref-classes-ptest` *class:* - Include the following line in each recipe:: + Include the following line in each recipe: + + .. code-block:: bitbake inherit ptest @@ -148,7 +156,9 @@ test. Here is what you have to do for each recipe: :term:`DEPENDS` and :term:`RDEPENDS` variables in your recipe in order for the package to meet the dependencies. Here - is an example where the package has a runtime dependency on "make":: + is an example where the package has a runtime dependency on "make": + + .. code-block:: bitbake RDEPENDS:${PN}-ptest += "make" @@ -169,7 +179,9 @@ test. Here is what you have to do for each recipe: Regardless, you still must add a ``do_compile_ptest`` function to build the test suite. Add a function similar to the following to your - recipe:: + recipe: + + .. code-block:: bitbake do_compile_ptest() { oe_runmake buildtest-TESTS diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst index 84523ff13f9d..9e2502802390 100644 --- a/documentation/test-manual/reproducible-builds.rst +++ b/documentation/test-manual/reproducible-builds.rst @@ -95,7 +95,9 @@ This defaults to including a ``world`` build so, if other layers are added, it would also run the tests for recipes in the additional layers. Different build targets can be defined using the :term:`OEQA_REPRODUCIBLE_TEST_TARGET` variable in ``local.conf``. For example, running reproducibility tests for only the -``python3-numpy`` recipe can be done by setting:: +``python3-numpy`` recipe can be done by setting: + +.. code-block:: bitbake OEQA_REPRODUCIBLE_TEST_TARGET = "python3-numpy" @@ -150,7 +152,9 @@ Using :term:`OEQA_REPRODUCIBLE_TEST_* ` var ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to test the reproducibility of a set of recipes, you can define -:term:`OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS`, in your local.conf:: +:term:`OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS`, in your local.conf: + +.. code-block:: bitbake OEQA_REPRODUCIBLE_TEST_LEAF_TARGETS = "my-recipe" diff --git a/documentation/test-manual/runtime-testing.rst b/documentation/test-manual/runtime-testing.rst index a64a97c80833..e1c1d3b85625 100644 --- a/documentation/test-manual/runtime-testing.rst +++ b/documentation/test-manual/runtime-testing.rst @@ -185,7 +185,9 @@ not need any information in this section. You can skip down to the If you did set :term:`TEST_TARGET` to "SystemdbootTarget", you also need to perform a one-time setup of your controller image by doing the following: -#. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows:: +#. *Set EFI_PROVIDER:* Be sure that :term:`EFI_PROVIDER` is as follows: + + .. code-block:: bitbake EFI_PROVIDER = "systemd-boot" @@ -223,7 +225,9 @@ The final thing you need to do when setting :term:`TEST_TARGET` to "SystemdbootTarget" is to set up the test image: #. *Set up your local.conf file:* Make sure you have the following - statements in your ``local.conf`` file:: + statements in your ``local.conf`` file: + + .. code-block:: bitbake IMAGE_FSTYPES += "tar.gz" IMAGE_CLASSES += "testimage" @@ -244,7 +248,9 @@ power: :term:`TEST_POWERCONTROL_EXTRA_ARGS` as a command that runs on the host and does power cycling. The test code passes one argument to that command: off, on or cycle (off then on). Here is an example that - could appear in your ``local.conf`` file:: + could appear in your ``local.conf`` file: + + .. code-block:: bitbake TEST_POWERCONTROL_CMD = "powercontrol.exp test 10.11.12.1 nuc1" @@ -277,7 +283,9 @@ wish to experiment with automated hardware testing, you can use the the required power action. This script requires either KDialog or Zenity to be installed. To use this script, set the :term:`TEST_POWERCONTROL_CMD` -variable as follows:: +variable as follows: + +.. code-block:: bitbake TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control" @@ -299,7 +307,9 @@ connecting to a remote console server. Regardless of the case, the command simply needs to connect to the serial console and forward that connection to standard input and output as any normal terminal program does. For example, to use the picocom terminal program on serial device -``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: +``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: + +.. code-block:: bitbake TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" @@ -307,7 +317,9 @@ For local devices where the serial port device disappears when the device reboots, an additional "serdevtry" wrapper script is provided. To use this wrapper, simply prefix the terminal command with -``${COREBASE}/scripts/contrib/serdevtry``:: +``${COREBASE}/scripts/contrib/serdevtry``: + +.. code-block:: bitbake TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b 115200 /dev/ttyUSB0" @@ -319,7 +331,9 @@ You can start the tests automatically or manually: - *Automatically running tests:* To run the tests automatically after the OpenEmbedded build system successfully creates an image, first set the :term:`TESTIMAGE_AUTO` variable to "1" in your ``local.conf`` file in the - :term:`Build Directory`:: + :term:`Build Directory`: + + .. code-block:: bitbake TESTIMAGE_AUTO = "1" @@ -330,7 +344,9 @@ You can start the tests automatically or manually: - *Manually running tests:* To manually run the tests, first globally inherit the :ref:`ref-classes-testimage` class by editing your - ``local.conf`` file:: + ``local.conf`` file: + + .. code-block:: bitbake IMAGE_CLASSES += "testimage" @@ -377,15 +393,21 @@ handling. Here are some things to keep in mind when running tests: -- The default tests for the image are defined as:: +- The default tests for the image are defined as: + + .. code-block:: bitbake DEFAULT_TEST_SUITES:pn-image = "ping ssh df connman syslog xorg scp vnc date rpm dnf dmesg" -- Add your own test to the list of the by using the following:: +- Add your own test to the list of the by using the following: + + .. code-block:: bitbake TEST_SUITES:append = " mytest" -- Run a specific list of tests as follows:: +- Run a specific list of tests as follows: + + .. code-block:: bitbake TEST_SUITES = "test1 test2 test3" @@ -401,7 +423,9 @@ test execution off to a scheduler. You can only export tests that are defined in :term:`TEST_SUITES`. If your image is already built, make sure the following are set in your -``local.conf`` file:: +``local.conf`` file: + +.. code-block:: bitbake IMAGE_CLASSES += "testexport" TEST_TARGET_IP = "IP-address-for-the-test-target" @@ -427,7 +451,9 @@ You can now run the tests outside of the build environment:: hardware before you can run the tests. Here is a complete example that shows IP addresses and uses the -``core-image-sato`` image:: +``core-image-sato`` image: + +.. code-block:: bitbake IMAGE_CLASSES += "testexport" TEST_TARGET_IP = "192.168.7.2" From patchwork Wed Aug 26 01:34:52 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96339 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id AF748C61DBD for ; Wed, 26 Aug 2026 01:35:32 +0000 (UTC) Received: from mail-qk1-f178.google.com (mail-qk1-f178.google.com [209.85.222.178]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3409.1787708126105113914 for ; Tue, 25 Aug 2026 18:35:26 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=IAW1pWAV; spf=pass (domain: gmail.com, ip: 209.85.222.178, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f178.google.com with SMTP id af79cd13be357-9309d4ea213so29391685a.1 for ; Tue, 25 Aug 2026 18:35:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708125; x=1788312925; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=3XSR08E7r1RgV8Y5/hOJT3YYkP3uNQEOnQIejqVtbBs=; b=IAW1pWAVRUNyFtpgRgxhM+rjdRKiIEmGvwyuT7XwQOoiPJxMPkrCCaY4z8yP3nPGXC dch2IXyrLyla1tfGAorjPmpIxTchouWnY210eiLVyc1p4hCmHOee9ecYRs8enEUD/ARP FRZwrn8cpjDx2B7FmgYfGez5Dcqi/JSvWWlX02ODibdzMQtgh3n3D5GfOLyaGW6xdD8z TBqSkgeazHfZUQ/HjC8aWBKWWMzyZPQyKQcvLZT2qAE9BCGxgsTPN3Zda9hzdp0W0tFP dRF4YWvL91BqCmd8ctw8iSkBSuGtFva1kB+RAgUFBbOqJJaZ1N4VIgUyKebE+BxfXbWi SE/A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708125; x=1788312925; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=3XSR08E7r1RgV8Y5/hOJT3YYkP3uNQEOnQIejqVtbBs=; b=qqybVDoWQ/lB01JMulGUzsBUhdBdxYPsuFQ+caZk/v1V78BDTpqe64uMmvz5g4Zpcu rIg0EpU+UrhFDzOpkMgIPIb0xZ2NkYUdGgo2lJIKxErILj1mKcAN/UGf4lWCgCg0XX29 i97G/+u0a/WClmCaz2LI5gboFaqb0XAoZMKsLcOaLRwTDVjL99P0Bk1P1qsWYcGoIxrz LDDvSFXXyBPVWx2KgK5PqBIUrraASkeT03JUnNi8qyCaz7JkeLa9EagT5bxgUkqDZoe/ VQ4dA5Gn3XjUGnRK0iEjeJGHQWqxZKPXGP34EwsYrDPPqu08kPwLc7uYJOwtnOdF1mag Vwlg== X-Gm-Message-State: AFuF++l8n1msTJDgagxEfWC9pPBF1JttFRMxBFnf7fTDGrlakYTP9yxY /i0PI0ev0KuF25o3iFceCoWy61AI9KtBlDHm7ZStW9kVdh9l6haSx5OpNHcJSYTD X-Gm-Gg: AR+sD11DCM5xaouinvjh7Rs0Fn6x3bSTqlk2wzlX6Ic6OYkqDsvfwXD73P3sWgTU1Nq EAVeo/Rm2pmV+yJ98JuRE82q48PRhkcZf7YbFm8U0/lBjC8WwZcbo+mtJvpv2DIiIj0XJOAdFog TjXlhlJm+xuhv7ZF7wyMv6wvuQii4C+eM+U2wwucFdkovps/pjc5SN37p/wQvfE3Te7I0Pb1o7R zTwtgvyfF8YH0EG9qcY/R5SLwXy5YW8Yg0sv96hsZnxO7laDwpyryyuefUmzBbmAmiDZEkdrHic 2fDexSdSsbt1vWMwmToDJ9EnP705ZZR3AAT6ixKmkFxot3nE2qJd9OuPRusnf1hTHVi7vQXOgRH ebDzYi1pFQDNJ7Ex1dg1wlj474+5zFmDkFGLV0lb6I6xtwvBVcaB/koemIUyGC+dOySw00XFrnu nz962uZN0x6C5yVLfFGTuPsETmwRjnBV08JwrDyFWuQ3GW7VStnfRz05J3SHOSPWIaKYB6PsPqN gcK5X/5kUQSLBiXO1as8tTrjjcfFgg= X-Received: by 2002:a05:620a:6083:b0:930:db8a:c608 with SMTP id af79cd13be357-937801092cfmr307937285a.7.1787708119982; Tue, 25 Aug 2026 18:35:19 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.18 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:19 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 07/10] overview-manual: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:52 -0400 Message-ID: <20260826013502.2674000-8-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:32 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10353 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 18 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- documentation/overview-manual/concepts.rst | 68 ++++++++++++++++------ 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index d4530e97fed9..c82f26961a3c 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst @@ -894,7 +894,9 @@ the analysis and package splitting process use several areas: Packages for a recipe are listed in the :term:`PACKAGES` variable. The :oe_git:`bitbake.conf ` -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 -`, is defined as follows:: +`, 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 = ":" @@ -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 () { ... From patchwork Wed Aug 26 01:34:53 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96340 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 86D9BC61DBE for ; Wed, 26 Aug 2026 01:35:32 +0000 (UTC) Received: from mail-qk1-f170.google.com (mail-qk1-f170.google.com [209.85.222.170]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3408.1787708123777822801 for ; Tue, 25 Aug 2026 18:35:23 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=C2jNgQKf; spf=pass (domain: gmail.com, ip: 209.85.222.170, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f170.google.com with SMTP id af79cd13be357-936623c6dd3so90021785a.0 for ; Tue, 25 Aug 2026 18:35:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708123; x=1788312923; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=W8BZ53eKaABDX+Ef6lZ+BvHSUyl0J8a+UgRDw8IZAUc=; b=C2jNgQKfOHkcAYk/YSTUk6UjnBjWvPuwJIfNRA/lSLKdoMJgo11KAqci8mopgPL78G oRd78bCq/vlrb+tZSDGgL7ksyHzOfgEwXJqeJz4f+gUSEcFPJEEF8UN/sUSovHWWViGr 5ipNWStW7rL3oYyev/QXQd5x/24jg2KPSQBJ//nSuYKPE3s/gKE/0oMi52fi5xFmKcqA 42G2zCAYzpczVGEwXwEO7Ia+KTq0kfT1j8QT6niV6omDt+dbX5/k+xJirl4BAlWoQwDf 1kfU0+R/WncBJb1ap9JynyJ/JOfshKo2OTZm9Gg7HA4mc6fI+1nXya4EFkVsd1dhVHd6 qoig== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708123; x=1788312923; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=W8BZ53eKaABDX+Ef6lZ+BvHSUyl0J8a+UgRDw8IZAUc=; b=noPQwu93C0ZgSFh0ZD4x1MQOigEac6Insn6Uq/qnRDlHapsIAEe+3Lvt5q+KTqPOpE aUZ0hAcv7NumWMoZzisXzNJpWSFu7/IRCOIgYlFKzNIyFyd/cTWAawf+ZGKSvw9teOdV hM1C3HPLzhZbuNFImL828zprux97TmHakHq0OTjTarjpxrqiTChDiHaj5IvxU3LLoH9E JhrCUY8QCgMOjRfPtN22bUYeH0KZxFCEJZRQLA99l8kgi9ouTw+YHBALCB2VKPmiRE2D oH5MU4ul/zcpDUfaJjO04MubVjTcOyXMcNMOEYcNudIr7xkfD2jvt7aa4pSUB1f8HNXm 3zmg== X-Gm-Message-State: AFuF++mbHWWvGWgaNhhFdII1tdduJQbC8tdqC/izqd1119hEKEQ01+5k uSgq0LmDw1pjbEkTJPAzXjRjM84Iy8IOBXTSXODTvjsIB8LHg1BNHn4D/pr/Z/SM X-Gm-Gg: AR+sD13Kd6EMjj5mB07mxBMk/jXgxk/LeiJslicpbFkTmLgqG0sRZLfMNwF3Q6F5n9t fwjvSfhFp2G3I6IrTFfaG40YBSeO+lulJZBDdUXYAVVz2tG6B8qHMT3CSDtxMKGHY7anZYLcSyW MHlbRorD5SFKXI+hjW6WRQJ1ykuKo/gu1+wryLaUpSk+sYCLpUGAWBzeZwEy7UAK6uuvJfxYjnT 7r491pgQ6yDSA97D9uz9m6HgRE2+1OpSY9tkUCoiihyetEYPmG61xRqI2RtpSK3gS5O0e3saET4 U5wu9rskgMBVIG4lMyu1q51SBZkgGe6jrRQtJ7yJKR6N+FnvCE50/id0mGd8ryCghgkSTLw/4ro YLMaawlOhwVItEMqRpY7jt+aNYTGfVbYI18Axl9QRxLCGfQqtcdNxHnR+yyJIPF0CBmT+tgmuMw K4Y4UWmDRtBKc2Y95dUf5kZ+iwecS9OjfU6ZAnRbCXtTeFPzVVeEvxfrrPeV4svAOoyA/kY/Azs v/eDRFy3ZsG5kaD0liQ0j9WJ5kcMjk= X-Received: by 2002:a05:620a:f0f:b0:936:cf9c:a994 with SMTP id af79cd13be357-9377e9e7274mr385470985a.19.1787708122551; Tue, 25 Aug 2026 18:35:22 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.20 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:20 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 08/10] security-manual: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:53 -0400 Message-ID: <20260826013502.2674000-9-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:32 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10352 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 16 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- .../security-manual/read-only-rootfs.rst | 8 +++-- .../security-manual/securing-images.rst | 8 +++-- .../security-manual/sstate-signing.rst | 16 +++++++--- .../security-manual/vulnerabilities.rst | 32 ++++++++++++++----- 4 files changed, 48 insertions(+), 16 deletions(-) diff --git a/documentation/security-manual/read-only-rootfs.rst b/documentation/security-manual/read-only-rootfs.rst index 251178ed5458..55eb853dc239 100644 --- a/documentation/security-manual/read-only-rootfs.rst +++ b/documentation/security-manual/read-only-rootfs.rst @@ -23,13 +23,17 @@ Creating the Root Filesystem To create the read-only root filesystem, simply add the "read-only-rootfs" feature to your image, normally in one of two ways. The first way is to add the "read-only-rootfs" image feature in the -image's recipe file via the :term:`IMAGE_FEATURES` variable:: +image's recipe file via the :term:`IMAGE_FEATURES` variable: + +.. code-block:: bitbake IMAGE_FEATURES += "read-only-rootfs" As an alternative, you can add the same feature from within your :term:`Build Directory`'s ``local.conf`` file with the -associated :term:`EXTRA_IMAGE_FEATURES` variable, as in:: +associated :term:`EXTRA_IMAGE_FEATURES` variable, as in: + +.. code-block:: bitbake EXTRA_IMAGE_FEATURES = "read-only-rootfs" diff --git a/documentation/security-manual/securing-images.rst b/documentation/security-manual/securing-images.rst index 13ab63ddd8be..3c01c1f643bd 100644 --- a/documentation/security-manual/securing-images.rst +++ b/documentation/security-manual/securing-images.rst @@ -82,7 +82,9 @@ your build output more secure. The security flags are in the Use the following line in your ``local.conf`` file or in your custom distribution configuration file to enable the security compiler and -linker flags for your build:: +linker flags for your build: + +.. code-block:: bitbake require conf/distro/include/security_flags.inc @@ -96,7 +98,9 @@ system to make your images more secure: and allow the use of empty passwords or root logins. This is typically done by adding the values "allow-empty-password", "allow-root-login", and "empty-root-password" to your build's image features, commonly with the - addition of the line:: + addition of the line: + + .. code-block:: bitbake EXTRA_IMAGE_FEATURES = "allow-empty-password empty-root-password allow-root-login" diff --git a/documentation/security-manual/sstate-signing.rst b/documentation/security-manual/sstate-signing.rst index 74a5d6bf07da..565f51e843ab 100644 --- a/documentation/security-manual/sstate-signing.rst +++ b/documentation/security-manual/sstate-signing.rst @@ -86,7 +86,9 @@ they are generated. The generation of new artifacts is done once a task has finished being executed. For the following sections let's assume that the build system has the shared -state directory location (:term:`SSTATE_DIR`) defined as follows:: +state directory location (:term:`SSTATE_DIR`) defined as follows: + +.. code-block:: bitbake SSTATE_DIR = "${TOPDIR}/sstate-cache" @@ -120,7 +122,9 @@ Enabling Shared State Signing ----------------------------- Create a new :term:`configuration file` on your host **in a safe location** and -add the two following statements:: +add the two following statements: + +.. code-block:: bitbake SSTATE_VERIFY_SIG = "1" SSTATE_SIG_KEY = "4049A47E3AAA99D0250966DC5B97632FA7F4E942" @@ -196,7 +200,9 @@ you can verify them with the public key counterpart of the private key. shared between multiple hosts. From a :term:`configuration file` such as the :ref:`site configuration file -`, include the following statements:: +`, include the following statements: + +.. code-block:: bitbake SSTATE_VERIFY_SIG = "1" SSTATE_VALID_SIGS = "5B97632FA7F4E942" @@ -255,7 +261,9 @@ Let's verify that signature verification works: .. note:: To make sure shared state verification is working, you can set a "fake" - public key identifier in :term:`SSTATE_VALID_SIGS`:: + public key identifier in :term:`SSTATE_VALID_SIGS`: + + .. code-block:: bitbake SSTATE_VALID_SIGS = "CAFECAFECAFECAFE" diff --git a/documentation/security-manual/vulnerabilities.rst b/documentation/security-manual/vulnerabilities.rst index 38fbd2c7e358..e3fc6fe768b8 100644 --- a/documentation/security-manual/vulnerabilities.rst +++ b/documentation/security-manual/vulnerabilities.rst @@ -35,7 +35,9 @@ Directory`: $ bitbake-config-build enable-fragment core/yocto/sbom-cve-check -Or add the following statement to a :term:`configuration file`:: +Or add the following statement to a :term:`configuration file`: + +.. code-block:: bitbake OE_FRAGMENTS += "core/yocto/sbom-cve-check" @@ -44,7 +46,9 @@ recommended settings to use it. The CVE database contains some old incomplete entries which have been deemed not to impact :term:`OpenEmbedded-Core (OE-Core)`. These CVE entries can be excluded -from the check by adding the following statement:: +from the check by adding the following statement: + +.. code-block:: bitbake include conf/distro/include/cve-extra-exclusions.inc @@ -165,7 +169,9 @@ in the recipe name to CVE product mapping. These mapping issues can be fixed by the :term:`CVE_PRODUCT` variable inside the recipe. This defines the name of the software component in the upstream `NIST CVE database `__. -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 `:: +an example from the :oe_layerindex:`ffmpeg recipe for dunfell `: + +.. 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//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" From patchwork Wed Aug 26 01:34:54 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96341 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id C42B7C61DC6 for ; Wed, 26 Aug 2026 01:35:32 +0000 (UTC) Received: from mail-qk1-f176.google.com (mail-qk1-f176.google.com [209.85.222.176]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.3467.1787708127327608792 for ; Tue, 25 Aug 2026 18:35:27 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=FjKSdNat; spf=pass (domain: gmail.com, ip: 209.85.222.176, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f176.google.com with SMTP id af79cd13be357-93695893ac1so28631885a.0 for ; Tue, 25 Aug 2026 18:35:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708126; x=1788312926; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=p0aQDObWFMDMNe10rbAPhiA5pWkQZtN+vnjchCYiaiA=; b=FjKSdNatVIW3k18NywYylCExsIBGAzp+HpUi6IXVZ3PhCtV3GK9JD5W8QKIjw3J5gM 91lxE6wDwKbYPqtVGl8GL4c3m58mKGOFPjRljB5C5VovCS9BAb9TnHoZ5W71V9mD7Owq Y7UpcyUEBVdQ5ZPcPXOrRputxjidpusToM6efCTQzXQnjc+trfOmwlh6+VJMeOOK+6/R ZApV94LZTtbkMAE3Q7+SUMVpYdUHEQKuK6MPZLSfS7TTr9dCjBCG3SWi47T4jy1aejYN bJWck3+G2+2XLcdbXFVnK5WG3CoDiyK5n9YfRXrB5Ip1pDcIDTxIXtg2ruMOB9ac0Nkn IDvw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708126; x=1788312926; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=p0aQDObWFMDMNe10rbAPhiA5pWkQZtN+vnjchCYiaiA=; b=mvRPKiRB33cjyH8UDIUBOj1Xhxp4FvsW9p91tdQztsEUzFoRPP2SamWP4qx9BGMf9W 96ddHsLiFd916POEFRJMM5B9faKegXwO51tt/Y0RTyd8s6YORNPh0+GMlXJKND5LQFWg ifswO1RsdG+7Gc4ferhCpl7mJRY1Ohi6mSlNjuLPqM1JSdGWGI1otp/QnHb+izT/VsT7 jfv0aJqPQdLOXnPHRD70UlSoSZhQdfCUYYqoexSVUsHm/mi7+6u2TZelC3zGtkPfmVSf E1dfMOI5oQ0N/FayWeuAQvBpEtggfjxPxVK38VDrXo1RofkuDIYIpLi41H/TyF3RtN87 AahA== X-Gm-Message-State: AFuF++mvoo+q+cF7SBUp4X6YcUbV9LwdJRoyvuL53bfSqkoEgqnov4Lo 2GaHTaNISsa9s93LB7tkGfOaH4pk3HtXCFKK+06sew6Xb1BlS12g333Z05GQElLa X-Gm-Gg: AR+sD12KEY+MiK69ibYVXWi2B34VUN9mkdhzkNe0v7L6S2Kg0BldvbPHh+rViVvnBxa onL2L21Z41aYc0wdirgAOOWPwlKK9S+jilP0eOkXjVgU1PHwvmgAr84JopSzPmux/JEkmMEgKGK fPZjU0DvES0odVrp05FoXFH1nC6UJ54UU53anMJa2rcGyrf9Fvq0T7v/9qKT5pmx+QpWH0haOZR 3W5CEvmiv3PN3BOEj0Om2nzXs3u40GjXC0PF2jE1V/G+EQ7N1/pn/RYbBBzOfKvt3yCVVTaH4tf X2uu/9uzTTayziUwsqkOFb3IICw2uNkg/axyxkfBw0Kfpga+DCZ+vrhHberb84uM68XKNQMYK5B 5hIqUL4/9c5qwrtPWbO022pz94PMMSXWbV17znFn5WTbtWQQrDL1c0vERkhJWjeDbB2bnvZnvJU IQtaKvYfGcQNg7V7b9hxaFS0Abm1bitvLYqqWLvuSsGjn+FaIq77wx87+52kek4WdoheDD1SVPi jnC6vMqLRTxWgdTbDJ00tlf+rXC/a8= X-Received: by 2002:a05:620a:818e:b0:936:e8e6:a4df with SMTP id af79cd13be357-937800f692amr225621585a.7.1787708126202; Tue, 25 Aug 2026 18:35:26 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.22 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:24 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 09/10] sdk-manual: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:54 -0400 Message-ID: <20260826013502.2674000-10-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:32 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10354 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 9 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- .../sdk-manual/appendix-customizing-standard.rst | 4 +++- .../sdk-manual/appendix-customizing.rst | 16 ++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/documentation/sdk-manual/appendix-customizing-standard.rst b/documentation/sdk-manual/appendix-customizing-standard.rst index 90b73dc20d7a..e0437270d1dd 100644 --- a/documentation/sdk-manual/appendix-customizing-standard.rst +++ b/documentation/sdk-manual/appendix-customizing-standard.rst @@ -27,7 +27,9 @@ Adding API Documentation to the Standard SDK You can include API documentation as well as any other documentation provided by recipes with the standard SDK by adding "api-documentation" -to the :term:`DISTRO_FEATURES` variable:: +to the :term:`DISTRO_FEATURES` variable: + +.. code-block:: bitbake DISTRO_FEATURES:append = " api-documentation" diff --git a/documentation/sdk-manual/appendix-customizing.rst b/documentation/sdk-manual/appendix-customizing.rst index 467c5c10c32c..497db2fb9f50 100644 --- a/documentation/sdk-manual/appendix-customizing.rst +++ b/documentation/sdk-manual/appendix-customizing.rst @@ -149,7 +149,7 @@ The class defines the default value of the :term:`SDK_TITLE` variable as follows: -.. code-block:: none +.. code-block:: bitbake SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" @@ -163,7 +163,7 @@ does the default "poky" distribution. If so, you could update the ``~/meta-mydistro/conf/distro/mydistro.conf`` file using the following form: -.. code-block:: none +.. code-block:: bitbake SDK_TITLE = "your_title" @@ -220,7 +220,7 @@ within the :ref:`populate_sdk_base ` 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" From patchwork Wed Aug 26 01:34:55 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96342 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id D0AFDC61DCD for ; Wed, 26 Aug 2026 01:35:32 +0000 (UTC) Received: from mail-qk1-f172.google.com (mail-qk1-f172.google.com [209.85.222.172]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3410.1787708130371395563 for ; Tue, 25 Aug 2026 18:35:30 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=MOvv1yAu; spf=pass (domain: gmail.com, ip: 209.85.222.172, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f172.google.com with SMTP id af79cd13be357-93738ebbffaso18814585a.3 for ; Tue, 25 Aug 2026 18:35:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708129; x=1788312929; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to:content-type; bh=fS/1OV4fdZSl2PLqyxVSTNSK7b7Z05if4PVmnbK+i2s=; b=MOvv1yAuPuVVRJ1IS1v1KmUFn5hSDfOb4IVISTpIm7KPT6l6EqnXEhI9TmjIaj/wYR PD2J+Wfze8tAYg+el22m+QlYDmzKdoXS/tjpugyC962z8DDPF5xiuT9C6/Z4jnBRlibq BbqHIbGYta9m4nfkQy90huznZCpkPKe+j7IMbVJxCgvW5KgSYo0ZPw4h7oyjrVy8Vxf8 MJPPeDxrBCoQ1SP/Dh936g4KoRtSIeiIoETZGxil1RO3ySU0ihHCdnPvsbPXnQDElqhB KhSc7MZunc97QOTva6gdexORHfmmTot2B7514XOoyKXhcFZuiAmrgcGx6VSJwc/lUqF1 Qvmg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708129; x=1788312929; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-gg:x-gm-message-state:from:to :cc:subject:date:message-id:reply-to:content-type; bh=fS/1OV4fdZSl2PLqyxVSTNSK7b7Z05if4PVmnbK+i2s=; b=G98vcD9EkNbnAd8430PySEFepcbAp6zyBu4RpZDClwGa4qb0TPS24zVCR9EuvmHynA tg1DYiU79432Jm1ncUuEOQJnqNt6i2R9+GDFrNfb4zdpznUaJ0WI9VIuQYF40vJdWe1A qQ751dwmCMKJzfOSDGpV/GdTT5TelWfRwzpKIaGyqZN+JH64FF2c9mkZeet210BT42w0 kjacmzgFOgass6F+WvSo21BwPDltYX7JRU2RBOUz2hnuNMUq2VFrJSrezBqKIsy0Hdq2 7Z4SorYYA8Zeb2E1LMYguzTozzGvHkvGiU6bjVhZMLaplpCUAkMQseehQYtZbQoWhM5h OUaA== X-Gm-Message-State: AFuF++lF2Aq0UUT78Fh+ELtatPxp0auxm2xS1WtsWXJpIvS3yaw+UiV2 6lLzMo+B+wLg/xnYJrNCTWjCkF/P1gZkZrD7Y3Icb+ISYaJr+Ypj0LP4vtWnRuRv X-Gm-Gg: AR+sD107lniySGlSVcmq8RYSKJmzk4t1tlktM86jYYcX4jXYYjHzRO7s7iDLYmHYbf9 t/YrjrT4+r+eQlA87jOlXfwUTRCWxQ4WEZYvm2DRSn4O8G7WQOyk+Si4n04OlwkmhpZLkdpLsVd Ko/K7//d3nkRtDXmqEk3H+ijrn/JA/ArMK4fYB9zoQuTAkgBOu0jS8E0DNidwxMJSx8RSxiYtPA 7U6g55K0BErYIHidx/FUVf8LJqJz3xI4E5uPZ4WMIxP9ZgMmZS8OLOA7N6OHIfLbUFo8AtMyhp4 FNfQIZxwoG+L/X5uSp7wAWCD+J0iwC4RCcXp84Ov4EauGHrVvu4FM37UWkG5rKAk0ElVW05zlib kDusI//LB5po8lH0nhEylY3vHQwxu/o3LH2a9UeZAm82sVG6l8VPaR1FEkAz1XFev4L7AhXondV RfAhkY86svNgE6mqva8P2R0iOQJ5I/4awG/TYCdUJYQ9zz3tzxTWi2E3vX/S1Ah4uhxqjy3AhHM 1P1SL1tZQ6GLgveOEgyEIfZlHI8QgQ= X-Received: by 2002:a05:620a:346:b0:936:9525:e952 with SMTP id af79cd13be357-9378045c672mr244263985a.41.1787708129149; Tue, 25 Aug 2026 18:35:29 -0700 (PDT) Received: from localhost.localdomain (pppoe-209-91-167-254.vianet.ca. [209.91.167.254]) by smtp.gmail.com with ESMTPSA id af79cd13be357-9377e68053dsm104323785a.39.2026.08.25.18.35.26 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:35:26 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Subject: [PATCH 10/10] docs-wide: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:34:55 -0400 Message-ID: <20260826013502.2674000-11-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013502.2674000-1-twoerner@gmail.com> References: <20260826013502.2674000-1-twoerner@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from 45-33-107-173.ip.linodeusercontent.com [45.33.107.173] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Wed, 26 Aug 2026 01:35:32 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10355 BitBake snippets here render as unhighlighted text. A reStructuredText literal block carries no language, and Sphinx falls back to a default that cannot recognise BitBake metadata. Pygments 2.21 added a BitBake lexer, so tag these 19 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. Blocks that only look like BitBake are left alone, as are blocks already tagged "none" where the content is deliberately unhighlighted. This covers the remaining manuals, each with only a handful of snippets. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- documentation/brief-yoctoprojectqs/index.rst | 4 ++- documentation/bsp-manual/bsp.rst | 28 ++++++++++++++----- .../contributor-guide/recipe-style-guide.rst | 24 ++++++++++++---- documentation/profile-manual/intro.rst | 16 ++++++++--- 4 files changed, 54 insertions(+), 18 deletions(-) diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst index 4adec9714f2f..2dccff16c995 100644 --- a/documentation/brief-yoctoprojectqs/index.rst +++ b/documentation/brief-yoctoprojectqs/index.rst @@ -410,7 +410,9 @@ layer>`: `Synaptics` license. See the :yocto_git:`ipcompliance.md ` document for more information. Add the ``synaptics-killswitch`` value to the :term:`LICENSE_FLAGS_ACCEPTED` - variable, in the ``conf/local.conf`` file of your build directory:: + variable, in the ``conf/local.conf`` file of your build directory: + + .. code-block:: bitbake LICENSE_FLAGS_ACCEPTED = "synaptics-killswitch" diff --git a/documentation/bsp-manual/bsp.rst b/documentation/bsp-manual/bsp.rst index 168d64e6ed5a..030464b74283 100644 --- a/documentation/bsp-manual/bsp.rst +++ b/documentation/bsp-manual/bsp.rst @@ -84,7 +84,9 @@ established after you run the OpenEmbedded build environment setup script (i.e. :ref:`structure-core-script`). Adding the root directory allows the :term:`OpenEmbedded Build System` to recognize the BSP -layer and from it build an image. Here is an example:: +layer and from it build an image. Here is an example: + +.. code-block:: bitbake BBLAYERS ?= " \ /usr/local/src/yocto/meta \ @@ -112,7 +114,9 @@ are known as ":term:`container layers `". An example of this type of layer is OpenEmbedded's :oe_git:`meta-openembedded ` layer. The ``meta-openembedded`` layer contains many ``meta-*`` layers. In cases like this, you need to include the names of the actual layers -you want to work with, such as:: +you want to work with, such as: + +.. code-block:: bitbake BBLAYERS ?= " \ /usr/local/src/yocto/meta \ @@ -603,7 +607,9 @@ For example, many ``tune-*`` files (e.g. ``tune-arm1136jf-s.inc``, To use an include file, you simply include them in the machine configuration file. For example, the Raspberry Pi BSP -``raspberrypi3.conf`` contains the following statement:: +``raspberrypi3.conf`` contains the following statement: + +.. code-block:: bitbake include conf/machine/include/rpi-base.inc @@ -674,7 +680,9 @@ Suppose you are using the ``linux-yocto_6.12.bb`` recipe to build the kernel. In other words, you have selected the kernel in your ``"bsp_root_name".conf`` file by adding :term:`PREFERRED_PROVIDER` and :term:`PREFERRED_VERSION` -statements as follows:: +statements as follows: + +.. code-block:: bitbake PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_VERSION_linux-yocto ?= "6.12%" @@ -1027,7 +1035,9 @@ BSP-specific configuration file named ``interfaces`` to the also supports several other machines: #. Edit the ``init-ifupdown_1.0.bbappend`` file so that it contains the - following:: + following: + + .. code-block:: bitbake FILESEXTRAPATHS:prepend := "${THISDIR}/files:" @@ -1383,7 +1393,9 @@ BSP Kernel Recipe Example ------------------------- The kernel recipe used to build the kernel image for the BeagleBone -device was established in the machine configuration:: +device was established in the machine configuration: + +.. code-block:: bitbake PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" PREFERRED_VERSION_linux-yocto ?= "6.18%" @@ -1394,7 +1406,9 @@ metadata used to build the kernel. In this case, a kernel append file kernel recipe (i.e. ``linux-yocto_6.18.bb``), which is located in :oe_git:`/openembedded-core/tree/meta/recipes-kernel/linux`. -The contents of the append file are:: +The contents of the append file are: + +.. code-block:: bitbake COMPATIBLE_MACHINE:genericarm64 = "genericarm64" COMPATIBLE_MACHINE:beaglebone-yocto = "beaglebone-yocto" diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 84c6bb14e8b0..7cd3385787ee 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -48,7 +48,9 @@ Debian policy closely. When a recipe references a git revision that does not correspond to a released version of software (e.g. is not a tagged version), the :term:`PV` variable should include the sign ``+``, so :term:`bitbake` automatically includes package -version information during the packaging phase:: +version information during the packaging phase: + +.. code-block:: bitbake PV = "+git" @@ -95,13 +97,17 @@ Variable Formatting - When splitting a long variable over multiple lines, all continuation lines should be indented (with spaces) to align with the start of the quote on the - first line:: + first line: + + .. code-block:: bitbake FOO = "this line is \ long \ " - Instead of:: + Instead of: + + .. code-block:: bitbake FOO = "this line is \ long \ @@ -190,7 +196,9 @@ used tasks this would be: Custom tasks should be sorted similarly. -Package specific variables are typically grouped together, e.g.:: +Package specific variables are typically grouped together, e.g.: + +.. code-block:: bitbake RDEPENDS:${PN} = "foo" RDEPENDS:${PN}-libs = "bar" @@ -211,7 +219,9 @@ Recipes need to define both the :term:`LICENSE` and include ``COPYING``, :term:`LICENSE`, and ``README`` files. You could also find the information near the top of a source file. For example, given a piece of software licensed under the GNU General Public - License version 2, you would set :term:`LICENSE` as follows:: + License version 2, you would set :term:`LICENSE` as follows: + + .. code-block:: bitbake LICENSE = "GPL-2.0-only" @@ -255,7 +265,9 @@ Recipes need to define both the :term:`LICENSE` and See the ":ref:`dev-manual/new-recipe:fetching code`" section for additional information. - Here is an example that assumes the software has a ``COPYING`` file:: + Here is an example that assumes the software has a ``COPYING`` file: + + .. code-block:: bitbake LIC_FILES_CHKSUM = "file://COPYING;md5=xxx" diff --git a/documentation/profile-manual/intro.rst b/documentation/profile-manual/intro.rst index 31791255246e..24bbc952c9bd 100644 --- a/documentation/profile-manual/intro.rst +++ b/documentation/profile-manual/intro.rst @@ -41,7 +41,9 @@ an ``sdk`` image, perhaps one of:: $ bitbake core-image-rt-sdk Alternatively, you can add ``tools-profile`` to the :term:`EXTRA_IMAGE_FEATURES` line in -your ``local.conf`` file:: +your ``local.conf`` file: + +.. code-block:: bitbake EXTRA_IMAGE_FEATURES:append = " tools-profile" @@ -57,7 +59,9 @@ the tracing and profiling tools will be included in non-sdk images as well e.g.: You can prevent that by setting the :term:`INHIBIT_PACKAGE_STRIP` - variable to "1" in your ``local.conf`` when you build the image:: + variable to "1" in your ``local.conf`` when you build the image: + + .. code-block:: bitbake INHIBIT_PACKAGE_STRIP = "1" @@ -67,11 +71,15 @@ If you've already built a stripped image, you can generate debug packages (xxx-dbg) which you can manually install as needed. To generate debug info for packages, you can add ``dbg-pkgs`` to -:term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example:: +:term:`EXTRA_IMAGE_FEATURES` in ``local.conf``. For example: + +.. code-block:: bitbake EXTRA_IMAGE_FEATURES:append = " dbg-pkgs" Additionally, in order to generate the right type of debug info, we also need to -set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file:: +set :term:`PACKAGE_DEBUG_SPLIT_STYLE` in the ``local.conf`` file: + +.. code-block:: bitbake PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'