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" 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: 96332 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 7FF9EC61DCD for ; Wed, 26 Aug 2026 01:37:23 +0000 (UTC) Received: from mail-qk1-f173.google.com (mail-qk1-f173.google.com [209.85.222.173]) by mx.groups.io with SMTP id smtpd.msgproc02-g2.3498.1787708234335315277 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=LWcdzeLk; spf=pass (domain: gmail.com, ip: 209.85.222.173, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f173.google.com with SMTP id af79cd13be357-934956bee57so40829685a.2 for ; Tue, 25 Aug 2026 18:37:14 -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=Klk4pocGFx93zA1NK6FT16pFh19pwBinS01U8FnAKrs=; b=LWcdzeLkKyQqjWvdfLr0v6wNwDpxofjYTgt10w+cuRWOLb/KdcCUgBVZgd/j/kNIjw Z/qfr6NrXiHqyWPsW4ZjUF368btg4miUSD2axF+jnqLyh5l7d4bQN839PYK/ZFfKcZtn bhyXQQZ/KcH6u+FfnAcJvYpdF6YLbPBP/rpZMHlVJrdwgAQ5/uJK8HZ7GGwrwun5MeRj Y5Id81lU3dvEK/xuPxPJNI07BHQmRrkHAZZ2SfxR2fGZvu6IR3bSTLkaiLGzW7rcP8g1 GN9LRL1ApYLTG6S1SPfbOQ7ezBDdqfnvZ/5kIA/TsxJodaVMZahayuKYdt2j/7OabZBv CH7A== 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=Klk4pocGFx93zA1NK6FT16pFh19pwBinS01U8FnAKrs=; b=PLenPYE/3UiW3pPMWzwnTxYg0RQQjw/HrEjXUaiKIaPsikF0/SLV7ZSZFTmUxn+ebt H4sfgIHnawYTtEAYBxy7GGlDxCrP2HuQKeo6Ipyhy/Ozkdg0skk6vQ0pn2qWEnUlBZIx WRDys9+hd4q/+PaXNjhBfn1G97165s/QWF2yoSJxkC4qwYzUk3av6F+tGPbTx69TKVB8 aHFL4eFGW3w7TzTqrqPSDWRtF7rxGY1OCHf1hV5SxJZpoQw/opV0YAjx8oA7CepFe8l3 jJxZp5bajYr160R5T4T9NEFvrUs3Qj7ovB6PivuUnn8uaUzY0q6o4UHV9aBuD6zRp9dp O4EA== X-Gm-Message-State: AFuF++k9cDi8cvCBZ244zoI69SCIGxMShHyRm9iDgJi+jRawZ5pR1dln yLJnedTsDPbdtx18edSxBWwEZHRgVXDAWzR+FQf+2znkZo8vU+C/vJqvdA2bg9yC X-Gm-Gg: AR+sD12HAyyBdPL8RzA7k7zxoQD/vBzOAb53VBJfirEOTT781w8oLT8Md5QZyYFzHYt DuBRiLD/tiNJOgYjofVp51nSZM9hjkr/ZKDpKF+5NB+VZDaFfRfYYXnF31zivh6BhnndwNHMs6G DPKDKraj0BsZB0qK4wB93Goxwycn3FCrrhLS84LErEY81oQtTnFPCgdcJG5iGD/KwaJA/3swThB ylWxenupHFLyOOJxwUcjZv892/g9L2/BM/bGK1JRGRXjti8Ji5J13Do9CdhwaYqA4hdtW5HfE2V 8/8U7s8hSuAAzqMvVn/KHZQaqsJIa4ybcNmyN/1amYYI5L1DeJ6ySeFn8U1Jpg5jYOhcAC8pUfo r+9GdE/1e3+0W1wu/i0JkZnOGdu+UOyARI2Jm/+BtgX7iK1y4BHyNn46ipDc8SSdtNdvt2WSuOF wMFyx2cDYy09B+iS6rJovSR6rRGLPm1JmzyHXWnfdocP99X1FB0fCf4lblD7exg4kL8sMJMDLsT HHQYmOCUP8n18uc8kwMsSsZT1w0vUg= 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.openembedded.org/g/bitbake-devel/message/20052 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: 96329 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 8C6F7C61DD3 for ; Wed, 26 Aug 2026 01:37:23 +0000 (UTC) Received: from mail-qk1-f176.google.com (mail-qk1-f176.google.com [209.85.222.176]) by mx.groups.io with SMTP id smtpd.msgproc01-g2.3438.1787708237068537459 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=BVdYaz+i; spf=pass (domain: gmail.com, ip: 209.85.222.176, mailfrom: twoerner@gmail.com) Received: by mail-qk1-f176.google.com with SMTP id af79cd13be357-930f618435cso22679885a.3 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.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=+MKszRxE5v+/ejGd2uRRZbnHvmyaYJJq3HcPThZvIsE=; b=BVdYaz+iGCbin+2afUPjMRCMw4uSzXdD1GFior9xyl0GMDGvsFEpdaOfX5UV0XLHRk 0VR8dXCHihaiy+0LCY8e4uD8+bcl31TeN3/eCdVpYd8QjlxL4a7nVbpfzoAzaAWIi0JZ 19aZCBEA/jIGjIn3d8NAgxJ/J8YrnWi89L2fZNxqgj7VbP5d9NdRKDsprWlfqvnUabSw bNjSZ1g1hnKa5JY2wZfotCOp+A7KjKMcTCxBpwUlhrhmZ0Xbk58udNNeymwtryKMss14 sSCgKgyvZJHJU+TD6iDe4ddpXupG+Om7A6ZWXuKDH8Ss+A9GGCeAiiFLO/+gY3M3QH9Q uZtA== 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=nI/V0tsZz6w5woi4Bu/W0wqGOjF+adm03GPofYKPcWU7JVUsunJGc4by3hytPYtSYu ONiYYzmHVwZYGe6yfk9vIEoejFLwuknLAacktW/HVI/5Fs5yxdid8nxDBrXDubzTMIe9 cVP8CA6l9QcDLsZlB15eK+c9Ltb57VxzcwHvTgV3me9T/xSz8Hd6H730T3vitiHfvLrZ nL/h+VefovHtQFHlPsoOhlAYAMOmkbFxalTuZlGlj68oAvTLXvM0aPc7gDMhRuR593pq lQbQ9Tx466hLWKZCJJCtKwiH0S2MwFTlwOml1yKoCnANagjHU6hpn9NnHoqFl+NiguAN 1+wA== X-Gm-Message-State: AFuF++mwpVd3xpTQKM2gXBDbKQTYpVwbBCRMZVAgwWVOrN2hf7xJceZx QKw2UMc7VR7RXVARgalYMSpiGF2r6E+YBqR77J4WYEeiKZkuX3NZrX6lt7Kabipw X-Gm-Gg: AR+sD11zjpe7yIKNI748z9Ed0G44gfbvie4dRbBFnU7PwfdwB6gineAgj+pQcfZoemP Mc0I2WviexMprEiOgAlUUDlhDcx0aKF45o4SjAvccri0gx2HrHxvEYTx0BZzQX/0FrlTKqulSAj T/6L/5l+W58P07KUnxGUUIOonOxBfu7rxusB5kR8zkaL+5fqaz3NnOvMHCdHrEO6xHptzuv0cz0 9YoAHaID2HLSd4dKZVmXkhYCZfPzaRD4bFXzwwseDOLyCaz+9RKrjInWvKyZlfPOc+CA8nZX7R7 xzDIuUvC4Ucf3oOlhQS8XivR1bIMDajsv5r92GuEY9iHMzIv0bPBkVrMqBUw1yHOPCT8iR/wGpu qjqaomXzaOnkBJF2Px33Mth/eX9vlRvwqaT2KrLahy/GsjNGWVoa2rp6KusiZG5NPbYL2qBVfsf a5EjLaqGah3OKhab5GCc4ftK17vz3lo234CFX9sYx9w9kM6h/rPx2XK68EWdlfL/nOH6wvFve/f 29Kxrm1LitotkOxAofb8yGV1Sj6YiE+iabC9Xb6lQ== 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:23 -0000 X-Groupsio-URL: https://lists.openembedded.org/g/bitbake-devel/message/20053 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: 96331 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 B2595C61DD2 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.3442.1787708242976605738 for ; Tue, 25 Aug 2026 18:37:23 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20251104 header.b=SdiWDoVF; 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-92ed3993c1eso21489985a.1 for ; Tue, 25 Aug 2026 18:37:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1787708242; x=1788313042; 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=sbjsmoITrXfjFHpfm5qFd1hErsqmf2LKciPriJErvkc=; b=SdiWDoVFcsGTSlqcbqJBokAfCMJds2h6xOz5FJRDwJhTOiWWg8ffVARqJWQ6Z2XEHx 3cWRq41/OhhpI33Q8oUj85t25aoJhoSlIjKE8OOCniwW9MTTZ4n1LF29wa/FX71rGNWa 9AZcKoFF2/LvPH1jvWx6tLNYtj0g8OVMAjRv35esEJ6xzK0F8UA2Lohon9NmezQBdg5H 1rPA8XExwqc+A77N6Ds8IKN9RVcBDhO3mLQlilyUPwk2P+91J8Lq0GzpYKijA2S2Tcan IctDkfDBk5H9xWR7SAL+oWxytY8VmuSz/IEbw62dtWxZ3D7dYxfcMoeq+16Q0zRO4bN2 UuQQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1787708242; x=1788313042; 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=ThNE59Fj6+enFS/dLOZGW0MriZxi/vs/+M8ISYudncwEBkkRfRIBDddI6qAshJ/TzM jAs5H0cHI2C/1t84PWic5DJ1xZKvJJ973B8LZ/QerrlVy4RaXHEiVaFzltFZ1A53DsCS 2G9ySUositHz1s4aQMmywFcyoYo3v6XHchmBAXRaJf5d8cuyvAG0oZNr7KP62W0zx06c T5S4UdzRPTzGgo0vd8K3OrXTLoSLqFeFNL/8EqULd7ZMPNow/u5SfDIF1hDJL0v8VC1T 8LJ/RUFqOWe9NQwIPpJDWrzJsqp9jtvFHkbhNgBefjUju2cOQmhRfaA5fl7ywcB/9wT1 iSAw== X-Gm-Message-State: AFuF++nOChB1FEW9uqcLYT/KZ8ACpRO5X67MBGNYnX/iVHJmK2hWAzVn jGTQxWxZx5n4BoGzxy8pL2fVm6ie9Obq3MWZI+PXx5N6YJE89dZTVA15 X-Gm-Gg: AR+sD10BMLQQXmV9atM27PfpdeTlUH2sQRa9JzRWNUDZS+3iaeywoOQiYtapwYeYWBf oqpMLYC2JsbyYoAMwJwzuiGZdbjgpr27hzvjCDSZ5ffSbXfnCiF35gJ24XknXm197Hg1Qa97Cds wLeZjnLKx6VzV1WiZVEZlL/ghPYzYwhTu8taqIhhpgwCL0a3TVEd2/TCvXjsoJpnQZ0vsdTJy+x KeCdPdbtpGw2zRkRDp6fZYhXkcVl9CTKAAa61px1OEqQ/oQ+q+eplctKQhoYE03hT6wDRQ6cVvq GwfhXMQLr5ADxIjwCmpBoXTaaWGf3xNtUgrF1/QZ0Z9hOY/c0IMIWaHl3sGn7fsRdvuRQOAqygI 3Efy8sfIfB54VdNdEvHEy97ukqjNZNqYc2q6CxMhcvUUH7Llbt7n2VuOgJXEwJJ4BR5w1PwsbZA gf1dDdmVBFEPU7KOlxiGXzVp8jF8F3Mfo5ViA9GDVP/s1/mmZ56bPBA8RoGShQ5ETdH0LTW+mZC fKPjYpU4AJ1ONpf0XutFwdNjPfiM08X 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.openembedded.org/g/bitbake-devel/message/20054 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"