From patchwork Wed Aug 26 01:37:00 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96344 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 D50DBC61DBD for ; Wed, 26 Aug 2026 01:37:22 +0000 (UTC) Received: from mail-qk1-f180.google.com (mail-qk1-f180.google.com [209.85.222.180]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3436.1787708233806789687 for ; Tue, 25 Aug 2026 18:37:14 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=kknG7p7i; spf=pass (domain: gmail.com, ip: 209.85.222.180, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f180.google.com with SMTP id af79cd13be357-92e6c4a867cso22557285a.0 for ; Tue, 25 Aug 2026 18:37:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708233; x=1788313033; darn=lists.yoctoproject.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to:content-type; bh=HJAI4gbP4KQjRT4wLKrGXW+Aqt+Lpicisi4grc9e62s=; b=kknG7p7izFp+vd80B919MtjR/cRWXcJuf+KJ/yKwD2SsJ3cPx6VvBeRCOWhZ3rZ6Aw fBvwgYUSWmEj6G3r3CzpDJp2z/ouRtgbJ3yvfRrhRJCgLO4BVaKE70B5Fsz6aAHJ689y vyaFuJG4R+cfgEEOYQ7D9DA+FEIPO71jHEj/sRu8BHiC7VTkZqPza4MGEdNeXCZkvR1t yVFsFCibGeHWPtACL8JBcN1u64KKk1PUYvprTSGrjNbfQmww446GeXSE0R49fE/X/Ctl xxrqFlqSHmgB39ml15tIOtqCjX64fopPcExXOVqwA8Zs5haLPlM9eUJdbQ0RjHXTYdcG HknA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708233; x=1788313033; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=HJAI4gbP4KQjRT4wLKrGXW+Aqt+Lpicisi4grc9e62s=; b=BLPMaRQmOJNpnf6r3RGfgzu2Dmn+U5RFXI2FXc3Ih4lAEFgCKb3z+eDru3NwyqpeJC nVKetu27zszi8/Ci+89pGnJhfE86m/uCDN8gB/de7NfJvOdhb6If4Ig41i2AFlTFcFPP RxxrxSccnks2VbXoWc6vMQtqAoqLEaVKxYGfp9vZecXtOqy3FOuZplnCviI1dkgDNyJk hD7nSS9r8edBveyOXlzJ2RnC1Y/i1jY/NNa55ora0FQiUYeuyKADMZa3FdPO0sNkj3Dd sgZ/yhDJhXNe5LDuHN0Z3EzqwnPnXKYwXEFTg5gl8DL8v5dwqRXGCecn/kK3e9NUK9ai JVEg== X-Gm-Message-State: AFuF++m/uK9i8u3ouP/45zwPCqLdpgKdk4FgebC8FJXQYWWKrPCCgUXK gYTSBEAdy82nqfNhMCtVBguiwc89sZ0uof9aumsTl/e3LRBPqRaB86EjhpZ9+4xj X-Gm-Gg: AR+sD13fkVJWVOGNIY+A5dXeKE1eXf+0Q8QWxWOGbdriwDv0APlTBA7erX+8MohNFCh QvT9Wqiq/NFRM+QkQRbcj63QJtOrtFOQI563muH6pZsjyRZxHHPMScXApctt20qvKDyrS+Ah9VE 7SKUhTxph8D0qr88FMBWj+Xdd8R4Crw3DgEJDFV1Pzz4+5KvHul37cE7SiL09wz9vBy0nbwzY55 ncC0y3L8L3cDRmr2tfVRYkfVbGlJbt9WazWgFhTVe6eD0s05y+IQd9OGQyKfjtSsm9RK9Eyruam 2hBB+XFYeCnvvKwFmry1lb+xLhh3Ad9CmswSVaYp+zblAnh8t7Er/ZXII2sdLmnz9v63pTOeYls 2fFdsSYaE2beAHwpv2+KGzDO9oTcHkpPWHZM+kq2TRAY2upcC476CJlmf2hvHaJqqYyAekVH8au HV7B6pmF4GaVkiRe1dqbTJl0kh8KkNHZuKlEVZ1KlRwjMEbSkl1kVIWCAJrJvULTEFIKLrFxDxu 1JVFuFeQy4oJh2TXjcCv9FsaysobSE= X-Received: by 2002:a05:620a:1b84:b0:937:6772:d8d with SMTP id af79cd13be357-93780162998mr326679485a.20.1787708231274; Tue, 25 Aug 2026 18:37:11 -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-9377e67c50esm103863685a.37.2026.08.25.18.37.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:37:09 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Cc: bitbake-devel@lists.openembedded.org Subject: [PATCH 1/4] doc: bitbake-user-manual-metadata: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:37:00 -0400 Message-ID: <20260826013703.2674786-2-twoerner@gmail.com> X-Mailer: git-send-email 2.51.0 In-Reply-To: <20260826013703.2674786-1-twoerner@gmail.com> References: <20260826013703.2674786-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:37:22 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/10357 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 95 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. The syntax chapter is where the language itself is described, so almost every example in it is BitBake. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- .../bitbake-user-manual-metadata.rst | 372 +++++++++++++----- 1 file changed, 279 insertions(+), 93 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst index a146b897c884..08534a8681b4 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst @@ -21,26 +21,34 @@ Basic Variable Setting The following example sets ``VARIABLE`` to "value". This assignment occurs immediately as the statement is parsed. It is a "hard" -assignment. :: +assignment. + +.. code-block:: bitbake VARIABLE = "value" As expected, if you include leading or -trailing spaces as part of an assignment, the spaces are retained:: +trailing spaces as part of an assignment, the spaces are retained: + +.. code-block:: bitbake VARIABLE = " value" VARIABLE = "value " Setting ``VARIABLE`` to "" sets it to an empty string, while setting the variable to " " sets it to a -blank space (i.e. these are not the same values). :: +blank space (i.e. these are not the same values). + +.. code-block:: bitbake VARIABLE = "" VARIABLE = " " You can use single quotes instead of double quotes when setting a variable's value. Doing so allows you to use values that contain the -double quote character:: +double quote character: + +.. code-block:: bitbake VARIABLE = 'I have a " in my value' @@ -106,7 +114,9 @@ Outside of :ref:`functions ` directive this is not the case. -Here is an example:: +Here is an example: + +.. code-block:: bitbake inherit_defer ${VARNAME} One way to achieve a conditional inherit in this case is to use -overrides:: +overrides: + +.. code-block:: bitbake VARNAME = "" VARNAME:someoverride = "myclass" @@ -841,11 +941,15 @@ parsing. Assuming ``someoverride`` is in :term:`OVERRIDES`, ``${VARNAME}`` expands to ``myclass``, which is then inherited. Alternatively, you could use an inline Python expression in the -following form:: +following form: + +.. code-block:: bitbake inherit_defer ${@'classname' if condition else ''} -Or:: +Or: + +.. code-block:: bitbake inherit_defer ${@bb.utils.contains('VARIABLE', 'something', 'classname', '', d)} @@ -876,7 +980,9 @@ encapsulated functionality or configuration that does not suit a ``.bbclass`` file. For example, if you needed a recipe to include some self-test definitions, -you might write:: +you might write: + +.. code-block:: bitbake include test_defs.inc @@ -917,7 +1023,9 @@ As a realistic example of this directive, imagine that all of your active layers contain a file ``conf/distro/include/maintainers.inc``, containing maintainer information for the recipes in that layer, and you wanted to collect all of the content from all of those files across all of those layers. -You could use the statement:: +You could use the statement: + +.. code-block:: bitbake include_all conf/distro/include/maintainers.inc @@ -958,7 +1066,9 @@ include file named ``foo.inc`` that contains the common definitions needed to build "foo". You need to be sure ``foo.inc`` is located in the same directory as your two recipe files as well. Once these conditions are set up, you can share the functionality using a ``require`` -directive from within each recipe:: +directive from within each recipe: + +.. code-block:: bitbake require foo.inc @@ -971,7 +1081,9 @@ class. BitBake only supports this directive when used within a configuration file. As an example, suppose you needed to inherit a class file called -``abc.bbclass`` from a configuration file as follows:: +``abc.bbclass`` from a configuration file as follows: + +.. code-block:: bitbake INHERIT += "abc" @@ -989,7 +1101,9 @@ subdirectory in one of the directories specified in :term:`BBPATH`. If you want to use the directive to inherit multiple classes, you can provide them on the same line in the ``local.conf`` file. Use spaces to separate the classes. The following example shows how to inherit both -the ``autotools`` and ``pkgconfig`` classes:: +the ``autotools`` and ``pkgconfig`` classes: + +.. code-block:: bitbake INHERIT += "autotools pkgconfig" @@ -1016,7 +1130,9 @@ go into ``bitbake.conf``, for example:: - name of variable that contains definitions for built-in fragments This allows listing enabled configuration fragments in ``OE_FRAGMENTS`` -variable like this:: +variable like this: + +.. code-block:: bitbake OE_FRAGMENTS = "core/domain/somefragment core/someotherfragment anotherlayer/anotherdomain/anotherfragment" @@ -1025,13 +1141,17 @@ where a fragment file is located, defined by :term:`BBFILE_COLLECTIONS` in ``lay The implementation then expands this list into :ref:`require ` -directives with full paths to respective layers:: +directives with full paths to respective layers: + +.. code-block:: bitbake require /path/to/core-layer/conf/fragments/domain/somefragment.conf require /path/to/core-layer/conf/fragments/someotherfragment.conf require /path/to/another-layer/conf/fragments/anotherdomain/anotherfragment.conf -The variable containing a list of fragment metadata variables could look like this:: +The variable containing a list of fragment metadata variables could look like this: + +.. code-block:: bitbake OE_FRAGMENTS_METADATA_VARS = "BB_CONF_FRAGMENT_SUMMARY BB_CONF_FRAGMENT_DESCRIPTION" @@ -1039,16 +1159,22 @@ The implementation will add a flag containing the fragment name to each of those when parsing fragments, so that the variables are namespaced by fragment name, and do not override each other when several fragments are enabled. -The variable containing a built-in fragment definitions could look like this:: +The variable containing a built-in fragment definitions could look like this: + +.. code-block:: bitbake OE_FRAGMENTS_BUILTIN = "someprefix:SOMEVARIABLE anotherprefix:ANOTHERVARIABLE" and then if 'someprefix/somevalue' is added to the variable that holds the list -of enabled fragments:: +of enabled fragments: + +.. code-block:: bitbake OE_FRAGMENTS = "... someprefix/somevalue" -bitbake will treat that as direct value assignment in its configuration:: +bitbake will treat that as direct value assignment in its configuration: + +.. code-block:: bitbake SOMEVARIABLE = "somevalue" @@ -1067,7 +1193,9 @@ BitBake also uses the :term:`BBPATH` variable. For these two directives, BitBake includes the first file it finds. Let's consider the following statement called from a recipe file located in -``/layers/meta-custom2/recipes-example/example/example_0.1.bb``:: +``/layers/meta-custom2/recipes-example/example/example_0.1.bb``: + +.. code-block:: bitbake require myfile.inc @@ -1084,7 +1212,9 @@ And let's assume that the value of :term:`BBPATH` is In this case the first path of the list matches and BitBake includes this file in ``example_0.1.bb``. -Another common example would be:: +Another common example would be: + +.. code-block:: bitbake require recipes-other/other/otherfile.inc @@ -1101,7 +1231,9 @@ This time, the second item of this list would be matched. Note that the first path is based on the location of the file with the ``require`` (or ``include``) directive. Imagine there's a -``/layers/meta-custom2/recipes-bbappend/example/example_0.1.bbappend`` with:: +``/layers/meta-custom2/recipes-bbappend/example/example_0.1.bbappend`` with: + +.. code-block:: bitbake require myappend.inc @@ -1120,7 +1252,9 @@ It is also possible to include *all* occurences of a file with the same name with the :ref:`include_all ` directive. Let's consider the following statement called from a recipe file located in -``/layers/meta-custom2/recipes-example/example/exampleall_0.1.bb``:: +``/layers/meta-custom2/recipes-example/example/exampleall_0.1.bb``: + +.. code-block:: bitbake include_all all.inc @@ -1213,7 +1347,9 @@ Shell Functions Functions written in shell script are executed either directly as functions, tasks, or both. They can also be called by other shell -functions. Here is an example shell function definition:: +functions. Here is an example shell function definition: + +.. code-block:: bitbake some_function () { echo "Hello World" @@ -1232,7 +1368,9 @@ can also be applied to shell functions. Most commonly, this application would be used in a ``.bbappend`` file to modify functions in the main recipe. It can also be used to modify functions inherited from classes. -As an example, consider the following:: +As an example, consider the following: + +.. code-block:: bitbake do_foo() { bbplain first @@ -1286,7 +1424,9 @@ BitBake-Style Python Functions These functions are written in Python and executed by BitBake or other Python functions using ``bb.build.exec_func()``. -An example BitBake function is:: +An example BitBake function is: + +.. code-block:: bitbake python some_python_function () { d.setVar("TEXT", "Hello World") @@ -1309,7 +1449,9 @@ import these modules. Also in these types of functions, the datastore Similar to shell functions, you can also apply overrides and override-style operators to BitBake-style Python functions. -As an example, consider the following:: +As an example, consider the following: + +.. code-block:: bitbake python do_foo:prepend() { bb.plain("first") @@ -1338,7 +1480,9 @@ Python Functions These functions are written in Python and are executed by other Python code. Examples of Python functions are utility functions that you intend to call from in-line Python or from within other Python functions. Here -is an example:: +is an example: + +.. code-block:: bitbake def get_depends(d): if d.getVar('SOMECONDITION'): @@ -1428,7 +1572,9 @@ Sometimes it is useful to set variables or perform other operations programmatically during parsing. To do this, you can define special Python functions, called anonymous Python functions, that run at the end of parsing. For example, the following conditionally sets a variable -based on the value of another variable:: +based on the value of another variable: + +.. code-block:: bitbake python () { if d.getVar('SOMEVAR') == 'value': @@ -1441,7 +1587,9 @@ the name "__anonymous", rather than no name. Anonymous Python functions always run at the end of parsing, regardless of where they are defined. If a recipe contains many anonymous functions, they run in the same order as they are defined within the -recipe. As an example, consider the following snippet:: +recipe. As an example, consider the following snippet: + +.. code-block:: bitbake python () { d.setVar('FOO', 'foo 2') @@ -1456,7 +1604,9 @@ recipe. As an example, consider the following snippet:: BAR = "bar 1" The previous example is conceptually -equivalent to the following snippet:: +equivalent to the following snippet: + +.. code-block:: bitbake FOO = "foo 1" BAR = "bar 1" @@ -1470,7 +1620,9 @@ available to tasks, which always run after parsing. Overrides and override-style operators such as "``:append``" are applied before anonymous functions run. In the following example, ``FOO`` ends -up with the value "foo from anonymous":: +up with the value "foo from anonymous": + +.. code-block:: bitbake FOO = "foo" FOO:append = " from outside" @@ -1518,13 +1670,17 @@ To make use of this technique, you need the following things in place: bar_do_foo - The class needs to contain the ``EXPORT_FUNCTIONS`` statement as - follows:: + follows: + + .. code-block:: bitbake EXPORT_FUNCTIONS functionname For example, continuing with the same example, the statement in the ``bar.bbclass`` would be as - follows:: + follows: + + .. code-block:: bitbake EXPORT_FUNCTIONS do_foo @@ -1567,7 +1723,9 @@ Tasks are either :ref:`shell functions ` - variable flag, as follows:: + variable flag, as follows: + + .. code-block:: bitbake do_printdate[nostamp] = "1" @@ -1612,7 +1772,9 @@ Additionally, the ``do_printdate`` task becomes dependent upon the name. You might wonder about the practical effects of using ``addtask`` -without specifying any dependencies as is done in the following example:: +without specifying any dependencies as is done in the following example: + +.. code-block:: bitbake addtask printdate @@ -1634,7 +1796,9 @@ on variable flags you can use with tasks. While it's infrequent, it's possible to define multiple tasks as dependencies when calling ``addtask``. For example, here's a snippet - from the OpenEmbedded class file ``package_tar.bbclass``:: + from the OpenEmbedded class file ``package_tar.bbclass``: + + .. code-block:: bitbake addtask package_write_tar before do_build after do_packagedata do_package @@ -1646,7 +1810,9 @@ Deleting a Task As well as being able to add tasks, you can delete them. Simply use the ``deltask`` command to delete a task. For example, to delete the example -task used in the previous sections, you would use:: +task used in the previous sections, you would use: + +.. code-block:: bitbake deltask printdate @@ -1662,7 +1828,9 @@ to run before ``do_a``. If you want dependencies such as these to remain intact, use the ``[noexec]`` varflag to disable the task instead of using the -``deltask`` command to delete it:: +``deltask`` command to delete it: + +.. code-block:: bitbake do_b[noexec] = "1" @@ -1774,7 +1942,9 @@ functionality of the task: The value set to the list is a file-boolean pair where the first value is the file name and the second is whether or not it - physically exists on the filesystem. :: + physically exists on the filesystem. + + .. code-block:: bitbake do_configure[file-checksums] += "${MY_DIRPATH}/my-file.txt:True" @@ -1898,7 +2068,9 @@ intent is to make it easy to do things like email notification on build failures. Following is an example event handler that prints the name of the event -and the content of the :term:`FILE` variable:: +and the content of the :term:`FILE` variable: + +.. code-block:: bitbake addhandler myclass_eventhandler python myclass_eventhandler() { @@ -2017,7 +2189,9 @@ BitBake supports multiple incarnations of a recipe file via the The :term:`BBCLASSEXTEND` variable is a space separated list of classes used to "extend" the recipe for each variant. Here is an example that results in a second incarnation of the current recipe being available. This second -incarnation will have the "native" class inherited. :: +incarnation will have the "native" class inherited. + +.. code-block:: bitbake BBCLASSEXTEND = "native" @@ -2057,7 +2231,9 @@ Dependencies Internal to the ``.bb`` File BitBake uses the ``addtask`` directive to manage dependencies that are internal to a given recipe file. You can use the ``addtask`` directive to indicate when a task is dependent on other tasks or when other tasks -depend on that recipe. Here is an example:: +depend on that recipe. Here is an example: + +.. code-block:: bitbake addtask printdate after do_fetch before do_build @@ -2095,7 +2271,9 @@ Build Dependencies BitBake uses the :term:`DEPENDS` variable to manage build time dependencies. The ``[deptask]`` varflag for tasks signifies the task of each item listed in :term:`DEPENDS` that must complete before -that task can be executed. Here is an example:: +that task can be executed. Here is an example: + +.. code-block:: bitbake do_configure[deptask] = "do_populate_sysroot" @@ -2113,7 +2291,9 @@ The :term:`PACKAGES` variable lists runtime packages. Each of those packages can have :term:`RDEPENDS` and :term:`RRECOMMENDS` runtime dependencies. The ``[rdeptask]`` flag for tasks is used to signify the task of each item runtime dependency which must have completed before that task can be -executed. :: +executed. + +.. code-block:: bitbake do_package_qa[rdeptask] = "do_packagedata" @@ -2137,7 +2317,9 @@ dependencies are discovered and added. The ``[recrdeptask]`` flag is most commonly used in high-level recipes that need to wait for some task to finish "globally". For example, -``image.bbclass`` has the following:: +``image.bbclass`` has the following: + +.. code-block:: bitbake do_rootfs[recrdeptask] += "do_packagedata" @@ -2146,7 +2328,9 @@ the current recipe and all recipes reachable (by way of dependencies) from the image recipe must run before the ``do_rootfs`` task can run. BitBake allows a task to recursively depend on itself by -referencing itself in the task list:: +referencing itself in the task list: + +.. code-block:: bitbake do_a[recrdeptask] = "do_a do_b" @@ -2163,7 +2347,9 @@ Inter-Task Dependencies BitBake uses the ``[depends]`` flag in a more generic form to manage inter-task dependencies. This more generic form allows for inter-dependency checks for specific tasks rather than checks for the -data in :term:`DEPENDS`. Here is an example:: +data in :term:`DEPENDS`. Here is an example: + +.. code-block:: bitbake do_patch[depends] = "quilt-native:do_populate_sysroot"