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: 96330 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 5E613C61DC7 for ; Wed, 26 Aug 2026 01:37:23 +0000 (UTC) Received: from mail-qk1-f169.google.com (mail-qk1-f169.google.com [209.85.222.169]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3437.1787708233848207054 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=eW8YgS04; spf=pass (domain: gmail.com, ip: 209.85.222.169, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f169.google.com with SMTP id af79cd13be357-92edb12cdf2so23191685a.3 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.openembedded.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=eW8YgS04EcdWPwoTmXFEQstAWPYGNNoSeZ7jztstEuQ/+mj3LiEmkNrq2+T4pbSUjl 7X6Ps8yyUJpo6s+bg7oTNUUo10BSRRyg+FgO9g8bVkio9iuuBn+IPlt5qQao4N0NViR+ S30N77U3mO8FxUQfWzS4gSeRKtKH2V2f5IIiDK918sriBHduc4dDOQjrYqWO+oUFhdYs UYLikxH0zvPLsxpRZIdlKJ7qieh/rF3A8yEL590L9MttDhBsuEBVvv2KdGpYUoDUqn7z 79rRqjwVCE+1mQMjbUm3EDkkvn6ok6Hjh1Qd2RaGhq5LA5w0dwjjtAoDzH71Ipn/vuzC G7dw== 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=PvJFA/yCjcVGm22WXuwlS/T00g7Tkxh4Vc/C/y7MKzDZuiQNHkiJAvZyOSwz9R+lcd Or5poejdYKH5H+74lA6Z0WVWG9TqSbvyzsC2FWMRKh40AzFzTzUPYWQoI+ohCM/BSqVC /Q3a5kCaJONyVbnKIdL4hEHkwzEctY3TpCGuXn81Cta+meIC1pss/bcL+V1DeJs29chG R583yCWSDHNb52/dWh+7VoGFAO9HFcyN/2+baQlISNntujuAFOZGLOAIKbisFlICZupZ N5c2ZTCZugI3A/43+haSYoRBRhnW/FZTx865ngwidQUibRR1p4VIjQwDp3Y/Em7BC14I 0hqA== X-Gm-Message-State: AFuF++lD1RWi2UqEII2xqph6WvoN0Rfs2+DfnGrLmReJaDLj+8/CdPwy jwtRdpF5olEcbAyA0GG40Ve5L57C7ot/ZI/frC5uLa9YbO9YYwBtA1QQ X-Gm-Gg: AR+sD10ONvFpDe0Cc34g2DUv49oSIPXbmepHPCB5zBh9K2KuJS+TOjM4TLgu6hwOIT5 nvA5OFPpRwHzUlXZO4Mg5Oon0rbbSFbDm6XAVROtN2xphEKpN+89MnKlYIV6F0jWD9aIoa48LdO s4ZfaOgLox5YK6R5WD80lP+VPZmL4WtYyds26oKXzJwnJS3yznMtt01LXW76id0mbSLm562YgAk BTyoRA7DBzD3aGOGhPFb+SLFwpKaYgIAuRN7+WvU91NLsVGsEPbzDqrNDULFz334Mnsl88rURiR bIqRWAeEfc+n37SvWlc+chBCN2bkCM5hPeUYZGsa9s1/oP1tL3CZt8LPhUicYBi+PZeuLCzNGnz udxSSIePR1wnbO0hYNRTEjzJ4tdVZTZJemBtBsFY1NaNvJ3+66RyFLvXkJCfPhcRDv7snlAbes/ RcprixlNHXH632WEc00swUqGbywAbGXQ/tmDnZ7wvSBVdKVtjU4+5SkrM6mPPH150vZuZKkH/lq ocw8bBVlN2QZxvPnDdMDKAfo6E2HYc= 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:23 -0000 X-Groupsio-URL: https://lists.openembedded.org/g/bitbake-devel/message/20051 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"