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" From patchwork Wed Aug 26 01:37:01 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96345 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 2A976C61DC6 for ; Wed, 26 Aug 2026 01:37:23 +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.msgproc01-g2.3440.1787708238839713647 for ; Tue, 25 Aug 2026 18:37:19 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=kQaPouVF; 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-934956bee57so40833785a.2 for ; Tue, 25 Aug 2026 18:37:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708238; x=1788313038; 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=Klk4pocGFx93zA1NK6FT16pFh19pwBinS01U8FnAKrs=; b=kQaPouVFhuXQW9lHT5wEXN7GQtA7C1IYgdZbCg5nlxw+6kP1ke3yWXZ6+7G+OK/l9w VPn6vVSL3PEY1BE2XO/OKvSYASfxufYAN1La4ckfCTYEVH+S/ZCVWOcnYVUmu1r2xkUU UiOKx/h3QJEtZ43wz6OWksxAEJ1qoUs74hBzMwe3mOa8Jrfio6m2ro31LUDrb2IAckOh 1U+4OrupkHXUI8lVk9MYXwcGaQ+URn4dwaFoyMg8Ael2yrJ302On+cFUJ/Q2wZas8IZ9 0GGyzqROWQyaKyk8yOtP8ML56pfqs48u+zOrs2crOIuaFn7xtSgP+3G6wQFeSxxU0P3+ mGew== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708238; x=1788313038; 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=Klk4pocGFx93zA1NK6FT16pFh19pwBinS01U8FnAKrs=; b=NBc7qVOw6odwgQJk9x6VSDlNPTd57O0Q1DDxACksA29y1YSeSq9ns1XQEkuVyl3xrR yhwBSH4XYp5Thgkb8/95meYs0/6y8g9gpvYw62QeZN4r+4qlXT5fZBhCeARyHr8iy7B2 axNc5o1Kus6nxwa7h9+odoNYcyXZxUvCXQOFy4mJijtkFLklhHBf5xQ4yEMV962lbsTP vTRk+itMrmwRAo7mKP7LmG6y407v+YY/YTNjLC/SJUMF2auy5GMpyFN6bEWHknFXMbb3 WM0mCXRQhUBr8f4TFYEgKQbq5n09jXJ3XlVcXFoko3YFv61UVKuDaWMj6duYIa38zBFf +aMA== X-Gm-Message-State: AFuF++nMBxbciXkFY2pLkE6BStXPX6uJ+y/3dIkEMNMeps245S+43Vl2 Vh/L0l2n+2Q8Jtbdn1us8HmNtLqwDDhV3fU9x+oXSaE1o4uOVvmd7ARfOwI/etw8 X-Gm-Gg: AR+sD13ElzNfG5B8BVulpTInnyPjC9rPIJsDvxYTBtSyyXk+9LJOQZ6yOV8eFhRRNPv T6XL7Ied9VVoFxVc64GH42r98T0KEhHy2oUINGPl+RDojfXgRg6vodmFmqjS0YCsdZOnvCEdn/e Ez7Phh3uB/5mKh7xQrS0GqXH7/pTwrT7wmx+T8wU38UbVgFIUgyd4mG3a7eQJAm07RQ8tF39OL/ FhNrP56NQHo2L2oAmFDzn+p0TVApdyABSbkmqropzSmuCM09vC5/8iZm0ts6esQR1TLioLT0zeH mYy6KpPBkZZl9Gyr/V5EBGXmiIzITe54zdjNNLGxasmjUr6YuFy1vut+fwNC+B8F/EYK0ViDhxo R++T0p+LofzrYo9rVYQKPdx4aCaX3dLbnmn60mO5rLknv4AsEjAhzk7ujhDI5FIgDJ2Y8warYuC dSVy9C3PNx6olT9Ikw7w0pxbMcvXtQ6jWwgIk8fvW7gNelk8oFsFsdwg+/n3ueYo4wg8FVJIq0E iSKRm951LoggZdRUSFITPmVEwwaK5M= X-Received: by 2002:a05:620a:a902:b0:936:ab1f:6aa4 with SMTP id af79cd13be357-93780186c71mr280002485a.1.1787708232981; Tue, 25 Aug 2026 18:37: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-9377e67c50esm103863685a.37.2026.08.25.18.37.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:37:11 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Cc: bitbake-devel@lists.openembedded.org Subject: [PATCH 2/4] doc: bitbake-user-manual-ref-variables: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:37:01 -0400 Message-ID: <20260826013703.2674786-3-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.yoctoproject.org/g/docs/message/10360 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 47 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- .../bitbake-user-manual-ref-variables.rst | 188 +++++++++++++----- 1 file changed, 141 insertions(+), 47 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index 5395ce5e395d..3fec02e5f533 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -40,7 +40,9 @@ overview of their function and contents. This is a special variable used during fetching. When :term:`SRCREV` is set to the value of this variable, the latest revision from the version controlled source code repository is used. - It should be set as follows:: + It should be set as follows: + + .. code-block:: bitbake SRCREV = "${AUTOREV}" @@ -48,7 +50,9 @@ overview of their function and contents. Azure Storage Shared Access Signature, when using the :ref:`Azure Storage fetcher ` 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="" @@ -72,7 +76,9 @@ overview of their function and contents. - Limited support for the "``*``" wildcard character for matching against the beginning of host names exists. For example, the following setting matches ``git.gnu.org``, ``ftp.gnu.org``, and - ``foo.git.gnu.org``. :: + ``foo.git.gnu.org``. + + .. code-block:: bitbake BB_ALLOWED_NETWORKS = "\*.gnu.org" @@ -127,7 +133,9 @@ overview of their function and contents. be included are those where the value is not significant for where the codeparser cache is used (i.e. when calculating variable dependencies for code fragments.) The value is space-separated without quoting values, for - example:: + example: + + .. code-block:: bitbake BB_HASH_CODEPARSER_VALS = "T=/ WORKDIR=/ DATE=1234 TIME=1234" @@ -170,15 +178,21 @@ overview of their function and contents. ` for more information on deferred inherits. - This means that if :term:`BB_DEFER_BBCLASSES` is set as follows:: + This means that if :term:`BB_DEFER_BBCLASSES` is set as follows: + + .. code-block:: bitbake BB_DEFER_BBCLASSES = "foo" - The following statement:: + The following statement: + + .. code-block:: bitbake inherit foo - Will automatically be equal to calling:: + Will automatically be equal to calling: + + .. code-block:: bitbake inherit_defer foo @@ -187,7 +201,9 @@ overview of their function and contents. you to control the build based on these parameters. Disk space monitoring is disabled by default. When setting this - variable, use the following form:: + variable, use the following form: + + .. code-block:: bitbake BB_DISKMON_DIRS = ",, [...]" @@ -223,7 +239,9 @@ 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 = "HALT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" @@ -264,7 +282,9 @@ overview of their function and contents. BB_DISKMON_WARNINTERVAL = "50M,5K" When specifying the variable in your configuration file, use the - following form:: + following form: + + .. code-block:: bitbake BB_DISKMON_WARNINTERVAL = "," @@ -280,7 +300,9 @@ 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" @@ -333,7 +355,9 @@ overview of their function and contents. wishing to create a source mirror would want to enable this variable. For performance reasons, creating and placing tarballs of the Git - repositories is not the default action by BitBake. :: + repositories is not the default action by BitBake. + + .. code-block:: bitbake BB_GENERATE_MIRROR_TARBALLS = "1" @@ -426,7 +450,9 @@ overview of their function and contents. variable is a space-separated list of refs, fully specified, and supports wildcards. - Example usage:: + Example usage: + + .. code-block:: bitbake BB_GIT_SHALLOW_EXTRA_REFS = "refs/tags/v1.0" BB_GIT_SHALLOW_EXTRA_REFS += "refs/heads/*" @@ -517,7 +543,9 @@ overview of their function and contents. and you wish the local server to query an upstream server for Hash Equivalence data. - Example usage:: + Example usage: + + .. code-block:: bitbake BB_HASHSERVE_UPSTREAM = "hashserv.yoctoproject.org:8686" @@ -624,7 +652,9 @@ overview of their function and contents. https://docs.kernel.org/accounting/psi.html for more information. A default value to limit the CPU pressure to be set in ``conf/local.conf`` - could be:: + could be: + + .. code-block:: bitbake BB_PRESSURE_MAX_CPU = "15000" @@ -665,7 +695,9 @@ overview of their function and contents. :term:`BB_PRESSURE_MAX_CPU` can help to reduce it. A default value to limit the IO pressure to be set in ``conf/local.conf`` - could be:: + could be: + + .. code-block:: bitbake BB_PRESSURE_MAX_IO = "15000" @@ -708,7 +740,9 @@ overview of their function and contents. occurring during builds. A default value to limit the memory pressure to be set in - ``conf/local.conf`` could be:: + ``conf/local.conf`` could be: + + .. code-block:: bitbake BB_PRESSURE_MAX_MEMORY = "15000" @@ -829,7 +863,9 @@ overview of their function and contents. This variable works similarly to the :term:`BB_TASK_NICE_LEVEL` variable except with a task's I/O priorities. - Set the variable as follows:: + Set the variable as follows: + + .. code-block:: bitbake BB_TASK_IONICE_LEVEL = "class.prio" @@ -894,7 +930,9 @@ overview of their function and contents. To build a different variant of the recipe with a minimal amount of code, it usually is as simple as adding the variable to your recipe. Here are two examples. The "native" variants are from the - OpenEmbedded-Core metadata:: + OpenEmbedded-Core metadata: + + .. code-block:: bitbake BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ "multilib:multilib_name" @@ -991,7 +1029,9 @@ overview of their function and contents. collection_name:filename_pattern The following example identifies two collection names and two filename - patterns:: + patterns: + + .. code-block:: bitbake BBFILES_DYNAMIC += "\ clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ @@ -999,7 +1039,9 @@ overview of their function and contents. " When the collection name is prefixed with "!" it will add the file pattern in case - the layer is absent:: + the layer is absent: + + .. code-block:: bitbake BBFILES_DYNAMIC += "\ !clang-layer:${LAYERDIR}/backfill/meta-clang/*/*/*.bb \ @@ -1029,7 +1071,9 @@ 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 build directory. - Here is an example:: + Here is an example: + + .. code-block:: bitbake BBLAYERS = " \ /home/scottrif/poky/meta \ @@ -1063,13 +1107,17 @@ 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 - ``recipes-bsp`` directory (recursively) of ``meta-ti-bsp``:: + ``recipes-bsp`` directory (recursively) of ``meta-ti-bsp``: + + .. code-block:: bitbake BBMASK = "${BBFILE_PATTERN_meta-ti-bsp}/recipes-bsp/" 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 += "${BBFILE_PATTERN_meta-ti-bsp}/recipes-graphics/libgal/" BBMASK += "${BBFILE_PATTERN_openembedded-layer}/recipes-support/" @@ -1093,12 +1141,16 @@ overview of their function and contents. Because these are complete regular expressions, if you want to match a directory and not a file, you must end the expression with a trailing - slash. That is:: + slash. That is: + + .. code-block:: bitbake BBMASK += "${BBFILE_PATTERN_meta-ti-bsp}/recipes-graphics/libgal/" Will match anything under ``recipes-graphics/ligbal/`` directory of - ``meta-ti-bsp``. And:: + ``meta-ti-bsp``. And: + + .. code-block:: bitbake BBMASK += "${BBFILE_PATTERN_meta-ti-bsp}/recipes-graphics/libgal" @@ -1119,7 +1171,9 @@ overview of their function and contents. Because these are complete regular expressions, failing to start the pattern with a ``^`` sign (which is usually the first character in :term:`BBFILE_PATTERN`) means it can match *any* portion of a path. - Take the following as an example:: + Take the following as an example: + + .. code-block:: bitbake BBMASK = "recipes-graphics/libgal/" @@ -1138,14 +1192,18 @@ overview of their function and contents. Because these are complete regular expressions, a leading slash does not mean the path is absolute. It simply forces the directory to be - named exactly that. Take:: + named exactly that. Take: + + .. code-block:: bitbake BBMASK = "recipes-graphics/libgal/" If you happen to have a directory ``foo-recipes-graphics/libgal/``, it will be matched. - Leading with a slash:: + Leading with a slash: + + .. code-block:: bitbake BBMASK = "/recipes-graphics/libgal/" @@ -1163,7 +1221,9 @@ overview of their function and contents. ``conf/local.conf`` configuration file. As an example, the following line specifies three multiconfigs, each - having a separate configuration file:: + having a separate configuration file: + + .. code-block:: bitbake BBMULTIFONFIG = "configA configB configC" @@ -1235,7 +1295,9 @@ overview of their function and contents. Consider this simple example for two recipes named "a" and "b" that produce similarly named packages. In this example, the :term:`DEPENDS` - statement appears in the "a" recipe:: + statement appears in the "a" recipe: + + .. code-block:: bitbake DEPENDS = "b" @@ -1394,7 +1456,9 @@ overview of their function and contents. this variable in your layer's ``conf/layer.conf`` configuration file. For the list, use the Yocto Project release name (e.g. "kirkstone", "mickledore"). To specify multiple OE-Core versions for the layer, use - a space-separated list:: + a space-separated list: + + .. code-block:: bitbake LAYERSERIES_COMPAT_layer_root_name = "kirkstone mickledore" @@ -1428,7 +1492,9 @@ overview of their function and contents. This variable has a specific syntax. Each line must contain a regular expression matching the original source URL and a replacement URL for it. - For example:: + For example: + + .. code-block:: bitbake MIRRORS:prepend = " \ git://git.openembedded.org/.* git:///mirrors/openembedded/BASENAME \ @@ -1462,7 +1528,9 @@ overview of their function and contents. ``git.openembedded.org.project.repo.git``. The rightmost part of the line can also be a bare URL that uses no special - keywords (usually ``https://`` or ``file://``). For example:: + keywords (usually ``https://`` or ``file://``). For example: + + .. code-block:: bitbake MIRRORS:prepend = " \ git://git.openembedded.org/.* file:///mirrors/openembedded/ \ @@ -1549,11 +1617,15 @@ overview of their function and contents. :term:`PREFERRED_PROVIDERS` is identical to :term:`PREFERRED_PROVIDER`. However, the :term:`PREFERRED_PROVIDERS` variable lets you define preferences for multiple situations using the following - form:: + form: + + .. code-block:: bitbake PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..." - This form is a convenient replacement for the following:: + This form is a convenient replacement for the following: + + .. code-block:: bitbake PREFERRED_PROVIDER_xxx = "yyy" PREFERRED_PROVIDER_aaa = "bbb" @@ -1569,7 +1641,9 @@ 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 = "2.7.3" PREFERRED_VERSION_linux-yocto = "4.12%" @@ -1593,7 +1667,9 @@ overview of their function and contents. Typically, you would add a specific server for the build system to attempt before any others by adding something like the following to - your configuration:: + your configuration: + + .. code-block:: bitbake PREMIRRORS:prepend = "\ git://.*/.* http://downloads.yoctoproject.org/mirror/sources/ \ @@ -1619,7 +1695,9 @@ overview of their function and contents. :term:`DEPENDS`. Consider the following example :term:`PROVIDES` statement from a recipe - file ``libav_0.8.11.bb``:: + file ``libav_0.8.11.bb``: + + .. code-block:: bitbake PROVIDES += "libpostproc" @@ -1642,7 +1720,9 @@ overview of their function and contents. :term:`PRSERV_HOST` The network based :term:`PR` service host and port. - Following is an example of how the :term:`PRSERV_HOST` variable is set:: + Following is an example of how the :term:`PRSERV_HOST` variable is set: + + .. code-block:: bitbake PRSERV_HOST = "localhost:0" @@ -1663,7 +1743,9 @@ overview of their function and contents. you should always use the variable in a form with an attached package name. 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:: + following :term:`RDEPENDS` statement: + + .. code-block:: bitbake RDEPENDS:${PN}-dev += "perl" @@ -1674,7 +1756,9 @@ overview of their function and contents. BitBake supports 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:: + with the :term:`RDEPENDS` variable: + + .. code-block:: bitbake RDEPENDS:${PN} = "package (operator version)" @@ -1687,7 +1771,9 @@ 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 RDEPENDS:${PN} = "foo (>= 1.2)" @@ -1716,7 +1802,9 @@ 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" @@ -1730,7 +1818,9 @@ overview of their function and contents. BitBake supports 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:: + with the :term:`RRECOMMENDS` variable: + + .. code-block:: bitbake RRECOMMENDS:${PN} = "package (operator version)" @@ -1743,7 +1833,9 @@ overview of their function and contents. >= For example, the following sets up a recommend on version - 1.2 or greater of the package ``foo``:: + 1.2 or greater of the package ``foo``: + + .. code-block:: bitbake RRECOMMENDS:${PN} = "foo (>= 1.2)" @@ -1829,7 +1921,9 @@ overview of their function and contents. - ``name``: Specifies a name to be used for association with :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one file or source control repository specified in :term:`SRC_URI`. - For example:: + For example: + + .. code-block:: bitbake SRC_URI = "git://example.com/foo.git;branch=main;name=first \ git://example.com/bar.git;branch=main;name=second \ From patchwork Wed Aug 26 01:37:02 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96343 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 D9573C61DBE for ; Wed, 26 Aug 2026 01:37:22 +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.msgproc02-g2.3499.1787708237073790774 for ; Tue, 25 Aug 2026 18:37:17 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=g+xlu2RH; 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-9371bcf1f8fso20416585a.1 for ; Tue, 25 Aug 2026 18:37:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708236; x=1788313036; 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=+MKszRxE5v+/ejGd2uRRZbnHvmyaYJJq3HcPThZvIsE=; b=g+xlu2RHTeKQO/rKMizj3Bx4Jdb8ReHCTL4RfJNfBUsDIu9uUmMPocNTsoBaXRenm8 EbiEIyQwHX5F/uSmdX0bJ5KmthOElwkOOfwu1C6sTPR1Bt/iVXvc8ozfGHXouR/2aqvN 7dT2dOn+/DApU2ulbGv9EoEthYGvBFryz0ENj7mVnEmheFuogalpAMpMgaJYBJQQEpXD OYT9ZzKLmZl+TLC0nBHMiD8R4h1oLcgyTjcg+eamkL8emMN2NER8p4VExkdJVhbwfPSk R8PI65TkEOkMZ8T8GkTMQbNJdcQs68+jCfQ3w65ie4BZW8vDuVlU7zgy8MeB+jMfi58x OZdQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708236; x=1788313036; 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=+MKszRxE5v+/ejGd2uRRZbnHvmyaYJJq3HcPThZvIsE=; b=nc+ZaZWta13loVwXMmXV3xXuMdbb2SK5Rn8ui1PsgLKP11RbtGaTH9pw7okHv0/VOW n7HAWJ6vryPvMShCrQ+QRigsRf3Cm3nfDtZ6kzMXB1Ei6oGQ5LB3Xxf5iPahOb4zIWbl VslEn3fn8f9VwCJpOB3CXlE7/j34k/IW/+1hJsn3duDbgF1ZnrNux+R9bu+B76WNBCAO vL4OVW29ig9bTWr8qYGFDSXs7WnX8oKk4DqFg3RUYgIejbiX9T5QoRb+QeDBQQroCmm7 VE98SZ86OPWbu9mRaUmL3YmXpx69ZUY3FT4QhtH0jBaOv6OR7N0iHqm694m3QnVnljAT aT+g== X-Gm-Message-State: AFuF++kJjPa6cBzy+huHfnjlApnK0MHA18glfDz5PttUJWaI8aAn3XMx i8BfjOPKAus+qDG46JYet+7FqlXpeGvJurw6KcGqn8726t0J0hYHKaUjT/SHSEk6 X-Gm-Gg: AR+sD114KPhiGdcv2o0urBtzWuqaIMZSdC+YOTqM8eUkAtU2Uw8elHTNM3SEpM7xySc EMo6t/K+kfpgg/VoH/a77OgRd5dqehbqIs9yVH2WH3sONnuHhB6OdFt9t3tN7VWpek8oyNfaTzU xsdTSKC7mh35qWpOEXJeXOgA9cMU0jRou1jLsMddy3NqAriplv8LNGc62k5aG//44t5MScuWv+j a+G1VdJwRp1+hfzo/B4SdutTcJtcSac2hxnNO8Gd6kGGfc5I5G1ntLYbE7NGhqn6Ht64T7opOJE XxbmD0NTgv99NeXG/bSy8EUXFXxIe0f2NQapXbNYAMj8+C494fSW3EWJtVQcBLxQrh4RUPUWt/1 lvtsqW/t/Bc/aRBRvaLC3odlQg0o0POpopZNklHJHLm56/Yjn1GLqXc0FO9968J36ZP3uoTc33g VWGH5+AoS3ZOmNdOcaeljRDDR8ue75mnq4T2HTRX442ysJanmTAgRbHfVzDc/bXeWmMzwEL7pbD avLFsWUMT77+4MYOeTBgkx/Lb6/Fmwl9kGxDDnoaw== X-Received: by 2002:a05:620a:701c:b0:92e:f372:7b5b with SMTP id af79cd13be357-93780107a2fmr272907985a.10.1787708235733; Tue, 25 Aug 2026 18:37: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-9377e67c50esm103863685a.37.2026.08.25.18.37.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:37:13 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Cc: bitbake-devel@lists.openembedded.org Subject: [PATCH 3/4] doc: bitbake-user-manual-fetching: use the bitbake code-block language Date: Tue, 25 Aug 2026 21:37:02 -0400 Message-ID: <20260826013703.2674786-4-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/10358 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 34 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- .../bitbake-user-manual-fetching.rst | 124 +++++++++++++----- 1 file changed, 93 insertions(+), 31 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index 2993eda49439..f98e3176333d 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -85,7 +85,9 @@ In the former case, the URL is passed to the ``wget`` fetcher, which does not understand "git". Therefore, the latter case is the correct form since the Git fetcher does know how to use HTTP as a transport. -Here are some examples that show commonly used mirror definitions:: +Here are some examples that show commonly used mirror definitions: + +.. code-block:: bitbake PREMIRRORS ?= "\ git://.*/.\* http://somemirror.org/sources/ \ @@ -112,19 +114,25 @@ File integrity is of key importance for reproducing builds. For non-local archive downloads, the fetcher code can verify SHA-256 and MD5 checksums to ensure the archives have been downloaded correctly. You can specify these checksums by using the :term:`SRC_URI` variable with the -appropriate varflags as follows:: +appropriate varflags as follows: + +.. code-block:: bitbake SRC_URI[md5sum] = "value" SRC_URI[sha256sum] = "value" You can also specify the checksums as -parameters on the :term:`SRC_URI` as shown below:: +parameters on the :term:`SRC_URI` as shown below: + +.. code-block:: bitbake SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d" If multiple URIs exist, you can specify the checksums either directly as in the previous example, or you can name the URLs. The following syntax -shows how you name the URIs:: +shows how you name the URIs: + +.. code-block:: bitbake SRC_URI = "http://example.com/foobar.tar.bz2;name=foo" SRC_URI[foo.md5sum] = 4a8e0f237e961fd7785d19d07fdb994d @@ -262,7 +270,9 @@ time the ``download()`` method is called. If you specify a directory, the entire directory is unpacked. Here are a couple of example URLs, the first relative and the second -absolute:: +absolute: + +.. code-block:: bitbake SRC_URI = "file://relativefile.patch" SRC_URI = "file:///Users/ich/very_important_software" @@ -288,7 +298,9 @@ Authorization header will be added to each request, including across redirects. To instead limit the Authorization header to the first request, add "redirectauth=0" to the list of parameters. -Some example URLs are as follows:: +Some example URLs are as follows: + +.. code-block:: bitbake SRC_URI = "http://oe.handhelds.org/not_there.aac" SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac" @@ -298,19 +310,25 @@ Some example URLs are as follows:: Because URL parameters are delimited by semi-colons, this can introduce ambiguity when parsing URLs that also contain semi-colons, - for example:: + for example: + + .. code-block:: bitbake SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47" Such URLs should should be modified by replacing semi-colons with '&' - characters:: + characters: + + .. code-block:: bitbake SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47" In most cases this should work. Treating semi-colons and '&' in queries identically is recommended by the World Wide Web Consortium (W3C). Note that due to the nature of the URL, you may have to - specify the name of the downloaded file as well:: + specify the name of the downloaded file as well: + + .. code-block:: bitbake SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2" @@ -351,7 +369,9 @@ The supported parameters are as follows: username is different than the username used in the main URL, which is passed to the subversion command. -Following are three examples using svn:: +Following are three examples using svn: + +.. code-block:: bitbake SRC_URI = "svn://myrepos/proj1;module=vip;protocol=http;rev=667" SRC_URI = "svn://myrepos/proj1;module=opie;protocol=svn+ssh" @@ -385,7 +405,9 @@ This fetcher supports the following parameters: by the Git server to fetch from. For example, the URL returned by GitLab server for ``mesa`` when cloning over SSH is ``git@gitlab.freedesktop.org:mesa/mesa.git``, however the expected URL in - :term:`SRC_URI` is the following:: + :term:`SRC_URI` is the following: + + .. code-block:: bitbake SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;branch=main;protocol=ssh;..." @@ -439,7 +461,9 @@ This fetcher supports the following parameters: parameter implies no branch and only works when the transfer protocol is ``file://``. -Here are some example URLs:: +Here are some example URLs: + +.. code-block:: bitbake SRC_URI = "git://github.com/fronteed/icheck.git;protocol=https;branch=${PV};tag=${PV}" SRC_URI = "git://github.com/asciidoc/asciidoc-py;protocol=https;branch=main" @@ -496,7 +520,9 @@ repository. To use this fetcher, make sure your recipe has proper :term:`SRC_URI`, :term:`SRCREV`, and -:term:`PV` settings. Here is an example:: +:term:`PV` settings. Here is an example: + +.. code-block:: bitbake SRC_URI = "ccrc://cc.example.org/ccrc;vob=/example_vob;module=/example_module" SRCREV = "EXAMPLE_CLEARCASE_TAG" @@ -570,7 +596,9 @@ the server's URL and port number, and you can specify a username and password directly in your recipe within :term:`SRC_URI`. Here is an example that relies on ``P4CONFIG`` to specify the server URL -and port, username, and password, and fetches the Head Revision:: +and port, username, and password, and fetches the Head Revision: + +.. code-block:: bitbake SRC_URI = "p4://example-depot/main/source/..." SRCREV = "${AUTOREV}" @@ -578,7 +606,9 @@ and port, username, and password, and fetches the Head Revision:: S = "${UNPACKDIR}/p4" Here is an example that specifies the server URL and port, username, and -password, and fetches a Revision based on a Label:: +password, and fetches a Revision based on a Label: + +.. code-block:: bitbake P4PORT = "tcp:p4server.example.net:1666" SRC_URI = "p4://user:passwd@example-depot/main/source/..." @@ -604,7 +634,9 @@ paths locally is desirable, the fetcher supports two parameters: paths locally for the specified location, even in combination with the ``module`` parameter. -Here is an example use of the the ``module`` parameter:: +Here is an example use of the the ``module`` parameter: + +.. code-block:: bitbake SRC_URI = "p4://user:passwd@example-depot/main;module=source/..." @@ -612,7 +644,9 @@ In this case, the content of the top-level directory ``source/`` will be fetched to ``${P4DIR}``, including the directory itself. The top-level directory will be accesible at ``${P4DIR}/source/``. -Here is an example use of the the ``remotepath`` parameter:: +Here is an example use of the the ``remotepath`` parameter: + +.. code-block:: bitbake SRC_URI = "p4://user:passwd@example-depot/main;module=source/...;remotepath=keep" @@ -640,7 +674,9 @@ This fetcher supports the following parameters: - *"manifest":* Name of the manifest file (default: ``default.xml``). -Here are some example URLs:: +Here are some example URLs: + +.. code-block:: bitbake SRC_URI = "repo://REPOROOT;protocol=git;branch=some_branch;manifest=my_manifest.xml" SRC_URI = "repo://REPOROOT;protocol=file;branch=some_branch;manifest=my_manifest.xml" @@ -663,11 +699,15 @@ Such functionality is set by the variable: delegate access to resources, if this variable is set, the Az Fetcher will use it when fetching artifacts from the cloud. -You can specify the AZ_SAS variable prefixed with a ? as shown below:: +You can specify the AZ_SAS variable prefixed with a ? as shown below: + +.. code-block:: bitbake AZ_SAS = "?se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=&sig=" -Here is an example URL:: +Here is an example URL: + +.. code-block:: bitbake SRC_URI = "az://.blob.core.windows.net//" @@ -694,17 +734,23 @@ chosen bucket. Instructions for authentication can be found in the If it used from the OpenEmbedded build system, the fetcher can be used for fetching sstate artifacts from a GCS bucket by specifying the -``SSTATE_MIRRORS`` variable as shown below:: +``SSTATE_MIRRORS`` variable as shown below: + +.. code-block:: bitbake SSTATE_MIRRORS ?= "\ file://.* gs:///PATH \ " -The fetcher can also be used in recipes:: +The fetcher can also be used in recipes: + +.. code-block:: bitbake SRC_URI = "gs:////" -However, the checksum of the file should be also be provided:: +However, the checksum of the file should be also be provided: + +.. code-block:: bitbake SRC_URI[sha256sum] = "" @@ -718,7 +764,9 @@ This submodule fetches code for corresponding to Rust libraries and programs to compile. Such crates are typically shared on https://crates.io/ but this fetcher supports other crate registries too. -The format for the :term:`SRC_URI` setting must be:: +The format for the :term:`SRC_URI` setting must be: + +.. code-block:: bitbake SRC_URI = "crate://REGISTRY/NAME/VERSION" @@ -727,7 +775,9 @@ This fetcher supports the following parameters: - *"protocol":* The protocol used to fetch the crates. The default is "https". You can also use "http". -Here is an example URL:: +Here is an example URL: + +.. code-block:: bitbake SRC_URI = "crate://crates.io/glob/0.2.11" @@ -746,7 +796,9 @@ This submodule fetches source code from an `NPM `__ Javascript package registry. -The format for the :term:`SRC_URI` setting must be:: +The format for the :term:`SRC_URI` setting must be: + +.. code-block:: bitbake SRC_URI = "npm://some.registry.url;ParameterA=xxx;ParameterB=xxx;..." @@ -763,7 +815,9 @@ This fetcher supports the following parameters: Note that NPM fetcher only fetches the package source itself. The dependencies can be fetched through the `npmsw-fetcher`_. -Here is an example URL with both fetchers:: +Here is an example URL with both fetchers: + +.. code-block:: bitbake SRC_URI = " \ npm://registry.npmjs.org/;package=cute-files;version=${PV} \ @@ -792,7 +846,9 @@ This submodule fetches source code from an description file, which lists the dependencies of an NPM package while locking their versions. -The format for the :term:`SRC_URI` setting must be:: +The format for the :term:`SRC_URI` setting must be: + +.. code-block:: bitbake SRC_URI = "npmsw://some.registry.url;ParameterA=xxx;ParameterB=xxx;..." @@ -804,7 +860,9 @@ This fetcher supports the following parameters: (``${S}`` by default). Note that the shrinkwrap file can also be provided by the recipe for -the package which has such dependencies, for example:: +the package which has such dependencies, for example: + +.. code-block:: bitbake SRC_URI = " \ npm://registry.npmjs.org/;package=cute-files;version=${PV} \ @@ -840,7 +898,9 @@ Auto Revisions For recipes which need to use the latest revision of their source code, the way to achieve it is to use :term:`AUTOREV` as the value of the -source code repository's :term:`SRCREV`:: +source code repository's :term:`SRCREV`: + +.. code-block:: bitbake SRCREV = "${AUTOREV}" @@ -862,7 +922,9 @@ the different SCM revisions in its package version string, instead of its usual approach with a single :term:`SRCREV`. For this purpose, the recipe must set the :term:`SRCREV_FORMAT` -variable. Consider the following example:: +variable. Consider the following example: + +.. code-block:: bitbake SRC_URI = " \ git://git.some.example.com/source-tree.git;name=machine \ From patchwork Wed Aug 26 01:37:03 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Trevor Woerner X-Patchwork-Id: 96346 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 0681FC61DB9 for ; Wed, 26 Aug 2026 01:37:23 +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.3439.1787708238523878100 for ; Tue, 25 Aug 2026 18:37:18 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=G8nzP48E; 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-92edb12cdf2so23193685a.3 for ; Tue, 25 Aug 2026 18:37:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708237; x=1788313037; 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=sbjsmoITrXfjFHpfm5qFd1hErsqmf2LKciPriJErvkc=; b=G8nzP48Ee0mnVe02t4TrPIh6jC9KkZcVwtE44Vee+gIMztXFpLvQ6ZflcK4UgVs+nO jW6gQkPOCKPdhN6BrToqvaBGgCpqMpE7wTyJXC36lFbHbevaYKYAvhWIMcqCZ9cm1FHG F2w3lN2+qQhPNgVRL6cv2UJrGTC3ciu0OHxcSYNRcBuGZuu+KskQtrWWGVwRkczhPR0y B+9x/SRTx9/dgY9hNXcAZxFhIruei0443UysV79yh/suMbCNbBdAw4W3BVsOIv/IOZdE 1A4idpM11ehCns9JdjKm2+F2DOTpeKGcZd4YOeJYIIkE9MhhGsmneNBobj/7PfmS9VXk ty3Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708237; x=1788313037; 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=sbjsmoITrXfjFHpfm5qFd1hErsqmf2LKciPriJErvkc=; b=DEXRBlh4QylsYZyupTg3EbZO0IRvFVL2aWThnliyVUcTt+3mxRhOsDAKT6Hjx4y4rv T5EuRjTu4+CFF8OPF9Kl9lcnVY+6NqNX5YNUCQsvWZCVcVfyT/ocJVWHD/fMZ1iSfYL7 qF9Okp3ac1LSdpYEN7VzGiu7gqu/jAIHNMRintrA7i0A/NZaC3xvR/tQo6ryyY3JMLnD NBww+lgajlPqe7JNYj3mJNTOmbuT0SDZApdHHEejuIOj2O/ThMKt4qcRvpRJ/s/WkKLT WpRyrvihz659I/pZToQjol99+XT8BmAdwZSKDgGnbCQdW4LLRTdm9fgofm5bs3SMLKrV 57UQ== X-Gm-Message-State: AFuF++mgL/rN8Z/pfmIxCw4JgofMFzE3uuL/ImRHEoAz/6ETbWLbuMyb o6pbC+sQicmSX8zblWlzwED91U4piJgDEu+gB4H9XxYaNQyvJ8O6rUTPSUzsggUd X-Gm-Gg: AR+sD10lUZgIlDC8Aff30PD7/tfG77ztgDdnDsAEEUBY84W6pL2NyehR0JgT0q0VBOg 2ZjgyBSVw9XgTHTstMxj32BkaYMHWLs3Z5UH9oBCCgTQx+Sfg+kDA4Aukd9myA6U6jw68Hm91Ya yq9ov9zeHNok3F8rvm6+5qvyZQJnp9iZW+lMr79SsiBOWrP+KNA8UwkzdgJB8Q4ZZ3P7k2iS/YH w6CkBx3cfbr3jrYbUC4gdF3dIei7mqrM82XawKFGHxNRc/Bt6A2rNPnCVt9eOmbdM5PgV1cTMFR jyqkBjvQP2DbVGqQYrtIVAOucjlrMxKvTazBpTg2tSaDLLeu0/nH/RIBjNewyj2Ox6aT8m29Q8L 0KkdSF2WOIMjGI4d+ONH1h2GuniTnEElIDoccOksFjsagCi/KiSD+jiuNGoDsLrcbtvZ5LnmyGV UIyjXkCyod2bqIeSEBC9W8ZjUhOo1KXn8mvarecQJVGrCPhmLZmonvFcJ0/iIbhC0131LAXf+HB MBTXAmSiUzm3QnUuSe2D5VqVFt2d7b4 X-Received: by 2002:a05:620a:2945:b0:936:695a:185a with SMTP id af79cd13be357-9378046b550mr243111185a.44.1787708237162; Tue, 25 Aug 2026 18:37:17 -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.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Aug 2026 18:37:16 -0700 (PDT) From: Trevor Woerner To: docs@lists.yoctoproject.org Cc: bitbake-devel@lists.openembedded.org Subject: [PATCH 4/4] doc: use the bitbake code-block language in the remaining chapters Date: Tue, 25 Aug 2026 21:37:03 -0400 Message-ID: <20260826013703.2674786-5-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.yoctoproject.org/g/docs/message/10359 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 28 blocks explicitly. Variable names, assignment operators, override chains, expansions and shell or Python task bodies are then highlighted. AI-Generated: codex/claude-opus 5 (xhigh) Signed-off-by: Trevor Woerner --- .../bitbake-user-manual-execution.rst | 44 ++++++++++++++----- .../bitbake-user-manual-hello.rst | 20 ++++++--- .../bitbake-user-manual-intro.rst | 24 +++++++--- 3 files changed, 66 insertions(+), 22 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst index 1638a8f5cc01..b24d1e283685 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-execution.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-execution.rst @@ -155,7 +155,9 @@ execution environment. pair of curly braces in a shell function, the closing curly brace must not be located at the start of the line without leading spaces. - Here is an example that causes BitBake to produce a parsing error:: + Here is an example that causes BitBake to produce a parsing error: + + .. code-block:: bitbake fakeroot create_shar() { cat << "EOF" > ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh @@ -185,7 +187,9 @@ During the configuration phase, BitBake will have set :term:`BBFILES`. BitBake now uses it to construct a list of recipes to parse, along with any append files (``.bbappend``) to apply. :term:`BBFILES` is a space-separated list of available files and -supports wildcards. An example would be:: +supports wildcards. An example would be: + +.. code-block:: bitbake BBFILES = "/path/to/bbfiles/*.bb /path/to/appends/*.bbappend" @@ -206,7 +210,9 @@ parses in order any append files found in :term:`BBFILES`. One common convention is to use the recipe filename to define pieces of metadata. For example, in ``bitbake.conf`` the recipe name and version are used to set the variables :term:`PN` and -:term:`PV`:: +:term:`PV`: + +.. code-block:: bitbake PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" PV = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" @@ -238,7 +244,9 @@ Recipe file collections exist to allow the user to have multiple repositories of ``.bb`` files that contain the same exact package. For example, one could easily use them to make one's own local copy of an upstream repository, but with custom modifications that one does not -want upstream. Here is an example:: +want upstream. Here is an example: + +.. code-block:: bitbake BBFILES = "/stuff/openembedded/*/*.bb /stuff/openembedded.modified/*/*.bb" BBFILE_COLLECTIONS = "upstream local" @@ -270,7 +278,9 @@ variable, which is optional. When a recipe uses :term:`PROVIDES`, that recipe's functionality can be found under an alternative name or names other than the implicit :term:`PN` name. As an example, suppose a recipe named ``keyboard_1.0.bb`` -contained the following:: +contained the following: + +.. code-block:: bitbake PROVIDES += "fullkeyboard" @@ -331,7 +341,9 @@ If the first recipe is named ``a_1.1.bb``, then the Thus, if a recipe named ``a_1.2.bb`` exists, BitBake will choose 1.2 by default. However, if you define the following variable in a ``.conf`` -file that BitBake parses, you can change that preference:: +file that BitBake parses, you can change that preference: + +.. code-block:: bitbake PREFERRED_VERSION_a = "1.1" @@ -499,7 +511,9 @@ to the task. Like the working directory case, situations exist where dependencies should be ignored. For these cases, you can instruct the build process -to ignore a dependency by using a line like the following:: +to ignore a dependency by using a line like the following: + +.. code-block:: bitbake PACKAGE_ARCHS[vardepsexclude] = "MACHINE" @@ -509,7 +523,9 @@ even if it does reference it. Equally, there are cases where we 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" @@ -537,7 +553,9 @@ configuration file, we 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 --- variables never included in any checksum. This example uses variables from OpenEmbedded -to help illustrate the concept:: +to help illustrate the concept: + +.. 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 \ @@ -558,7 +576,9 @@ OpenEmbedded-Core uses: "OEBasicHash". By default, there is a dummy "noop" signature handler 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:: +``bitbake.conf`` file: + +.. code-block:: bitbake BB_SIGNATURE_HANDLER ?= "OEBasicHash" @@ -724,7 +744,9 @@ or higher priority to a file called ``hashequiv.log``:: } } -Then set the :term:`BB_LOGCONFIG` variable in ``conf/local.conf``:: +Then set the :term:`BB_LOGCONFIG` variable in ``conf/local.conf``: + +.. code-block:: bitbake BB_LOGCONFIG = "hashequiv.json" diff --git a/doc/bitbake-user-manual/bitbake-user-manual-hello.rst b/doc/bitbake-user-manual/bitbake-user-manual-hello.rst index 654196ca24d3..015cf907eb25 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-hello.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-hello.rst @@ -197,7 +197,9 @@ Following is the complete "Hello World" example. From within the ``conf`` directory, use some editor to create the ``bitbake.conf`` so that it contains - the following:: + the following: + + .. code-block:: bitbake PN = "${@bb.parse.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" @@ -263,7 +265,9 @@ Following is the complete "Hello World" example. $ mkdir classes Move to the ``classes`` directory and then create the - ``base.bbclass`` file by inserting this single line:: + ``base.bbclass`` file by inserting this single line: + + .. code-block:: bitbake addtask build @@ -304,7 +308,9 @@ Following is the complete "Hello World" example. $ mkdir conf Move to the ``conf`` directory and create a ``layer.conf`` file that has the - following:: + following: + + .. code-block:: bitbake BBPATH .= ":${LAYERDIR}" BBFILES += "${LAYERDIR}/*.bb" @@ -326,7 +332,9 @@ Following is the complete "Hello World" example. You need to create the recipe file next. Inside your layer at the top-level, use an editor and create a recipe file named - ``printhello.bb`` that has the following:: + ``printhello.bb`` that has the following: + + .. code-block:: bitbake DESCRIPTION = "Prints Hello World" PN = 'printhello' @@ -367,7 +375,9 @@ Following is the complete "Hello World" example. ``hello/conf`` for this example). Set your working directory to the ``hello/conf`` directory and then - create the ``bblayers.conf`` file so that it contains the following:: + create the ``bblayers.conf`` file so that it contains the following: + + .. code-block:: bitbake BBLAYERS ?= " \ /home//mylayer \ diff --git a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst index 6801323e2fb9..d83050d45ca2 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-intro.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-intro.rst @@ -215,7 +215,9 @@ BitBake supports class files installed in three different directories: :term:`INHERIT` variable in a :ref:`configuration file `. These classes are included for every recipe being built. For example, you would use - the global class named ``myclass`` like so:: + the global class named ``myclass`` like so: + + .. code-block:: bitbake INHERIT += "myclass" @@ -223,7 +225,9 @@ BitBake supports class files installed in three different directories: :ref:`inherit ` or :ref:`inherit_defer ` directive. They do not support being inherited globally. For example, you - would use the recipe class named ``myclass`` like so:: + would use the recipe class named ``myclass`` like so: + + .. code-block:: bitbake inherit myclass @@ -673,7 +677,9 @@ accomplished by setting the configuration files for ``target1`` and ``target2`` defined in the build directory. The following statement in the ``local.conf`` file both enables BitBake to perform multiple configuration builds and specifies -the two extra multiconfigs:: +the two extra multiconfigs: + +.. code-block:: bitbake BBMULTICONFIG = "target1 target2" @@ -704,12 +710,16 @@ multiconfig. 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 an example with two -multiconfigs: ``target1`` and ``target2``:: +multiconfigs: ``target1`` and ``target2``: + +.. code-block:: bitbake image_task[mcdepends] = "mc:target1:target2:image2:rootfs_task" @@ -730,7 +740,9 @@ the ``rootfs_task`` for the "target2" multiconfig build. Having a recipe depend on the root filesystem of another build might not seem that useful. Consider this change to the statement in the image1 -recipe:: +recipe: + +.. code-block:: bitbake image_task[mcdepends] = "mc:target1:target2:image2:image_task"