doc: highlight BitBake snippets with the bitbake language
cover doc: highlight BitBake snippets with the bitbake language
Pygments 2.21.0 added a BitBake lexer, so BitBake snippets can now say what they are instead of rendering as plain literal blocks. The user manual is where the language is documented, so it seemed the wrong place to leave unhighlighted.
No prose changes, no reflowing, no reindenting - every hunk turns a literal-block introducer into a code-block directive and nothing else.
Which blocks were converted was decided by reading. Blocks that share BitBake's assignment shape but are another language were left alone, including the bitbake-setup settings files, which are INI and already tagged as such.
Please do not apply this yet
----------------------------
The autobuilder builds the docs with a pinned buildtools tarball that currently carries Pygments 2.19.2, which predates the BitBake lexer. run-docs-build also passes SPHINXOPTS="-j auto", dropping the -W the Makefile defaults to, so on that toolchain every one of these blocks would publish unhighlighted and the build would still succeed. I have asked separately about refreshing that tarball.
Sending now for review rather than to be merged. Once the toolchain can render it, this applies as-is.
Depends on
----------
"doc: state the language of six Python blocks explicitly", sent separately. That patch stands on its own and can go in independently; this series is based on it only so the two do not touch the same lines.
One block worth a second opinion
--------------------------------
bitbake-user-manual-ref-variables.rst has two blocks where one real assignment is followed by a long prose "where: ..." explanation. I have tagged them, but the same shape elsewhere was deliberately left as a plain literal block, so I may have called this one wrong.
Trevor Woerner (4):
doc: bitbake-user-manual-metadata: use the bitbake code-block language
doc: bitbake-user-manual-ref-variables: use the bitbake code-block
language
doc: bitbake-user-manual-fetching: use the bitbake code-block language
doc: use the bitbake code-block language in the remaining chapters
.../bitbake-user-manual-execution.rst | 44 ++- .../bitbake-user-manual-fetching.rst | 124 ++++-- .../bitbake-user-manual-hello.rst | 20 +- .../bitbake-user-manual-intro.rst | 24 +- .../bitbake-user-manual-metadata.rst | 372 +++++++++++++----- .../bitbake-user-manual-ref-variables.rst | 188 ++++++--- 6 files changed, 579 insertions(+), 193 deletions(-)
PATCH 1/4 doc: bitbake-user-manual-metadata: use the bitbake code-block language
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)
--- .../bitbake-user-manual-metadata.rst | 372 +++++++++++++----- 1 file changed, 279 insertions(+), 93 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +279 -93
@@ -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 <bitbake-user-manual/bitbake-user-manual-metadata:fun BitBake joins any line ending in a backslash character ("\\") with the following line before parsing statements. The most common use for the "\\" character is to split -variable assignments over multiple lines, as in the following example:: +variable assignments over multiple lines, as in the following example: + +.. code-block:: bitbake FOO = "bar \ baz \
@@ -117,7 +127,9 @@ character that follow it are removed when joining lines. Thus, no newline characters end up in the value of ``FOO``. Consider this additional example where the two assignments both assign -"barbaz" to ``FOO``:: +"barbaz" to ``FOO``: + +.. code-block:: bitbake FOO = "barbaz" FOO = "bar\
@@ -136,7 +148,9 @@ Variable Expansion Variables can reference the contents of other variables using a syntax that is similar to variable expansion in Bourne shells. The following assignments result in A containing "aval" and B evaluating to -"preavalpost". :: +"preavalpost". + +.. code-block:: bitbake A = "aval" B = "pre${A}post"
@@ -150,7 +164,9 @@ The "=" operator does not immediately expand variable references in the right-hand side. Instead, expansion is deferred until the variable assigned to is actually used. The result depends on the current values of the referenced variables. The following example should clarify this -behavior:: +behavior: + +.. code-block:: bitbake A = "${B} baz" B = "${C} bar"
@@ -168,7 +184,9 @@ expansion (:=)` operator. If the variable expansion syntax is used on a variable that does not exist, the string is kept as is. For example, given the following assignment, ``BAR`` expands to the literal string "${FOO}" as long as -``FOO`` does not exist. :: +``FOO`` does not exist. + +.. code-block:: bitbake BAR = "${FOO}"
@@ -178,7 +196,9 @@ Setting a default value (?=) You can use the "?=" operator to achieve a "softer" assignment for a variable. This type of assignment allows you to define a variable if it is undefined when the statement is parsed, but to leave the value alone -if the variable has a value. Here is an example:: +if the variable has a value. Here is an example: + +.. code-block:: bitbake A ?= "aval"
@@ -198,7 +218,9 @@ Setting a weak default value (??=) The weak default value of a variable is the value which that variable will expand to if no value has been assigned to it via any of the other assignment operators. The "??=" operator takes effect immediately, replacing -any previously defined weak default value. Here is an example:: +any previously defined weak default value. Here is an example: + +.. code-block:: bitbake W ??= "x" A := "${W}" # Immediate variable expansion
@@ -208,7 +230,9 @@ any previously defined weak default value. Here is an example:: C = "${W}" W ?= "i" -After parsing we will have:: +After parsing we will have: + +.. code-block:: bitbake A = "x" B = "y"
@@ -216,22 +240,30 @@ After parsing we will have:: W = "i" Appending and prepending non-override style will not substitute the weak -default value, which means that after parsing:: +default value, which means that after parsing: + +.. code-block:: bitbake W ??= "x" W += "y" -we will have:: +we will have: + +.. code-block:: bitbake W = " y" On the other hand, override-style appends/prepends/removes are applied after -any active weak default value has been substituted:: +any active weak default value has been substituted: + +.. code-block:: bitbake W ??= "x" W:append = "y" -After parsing we will have:: +After parsing we will have: + +.. code-block:: bitbake W = "xy"
@@ -239,7 +271,9 @@ Immediate variable expansion (:=) --------------------------------- The ":=" operator results in a variable's contents being expanded -immediately, rather than when the variable is actually used:: +immediately, rather than when the variable is actually used: + +.. code-block:: bitbake T = "123" A := "test ${T}"
@@ -265,7 +299,9 @@ the "+=" and "=+" operators. These operators insert a space between the current value and prepended or appended value. These operators take immediate effect during parsing. Here are some -examples:: +examples: + +.. code-block:: bitbake B = "bval" B += "additionaldata"
@@ -284,7 +320,9 @@ If you want to append or prepend values without an inserted space, use the ".=" and "=." operators. These operators take immediate effect during parsing. Here are some -examples:: +examples: + +.. code-block:: bitbake B = "bval" B .= "additionaldata"
@@ -302,7 +340,9 @@ style syntax. When you use this syntax, no spaces are inserted. These operators differ from the ":=", ".=", "=.", "+=", and "=+" operators in that their effects are applied at variable expansion time -rather than being immediately applied. Here are some examples:: +rather than being immediately applied. Here are some examples: + +.. code-block:: bitbake B = "bval" B:append = " additional data"
@@ -338,7 +378,9 @@ value to be removed from the variable. Unlike ":append" and ":prepend", there is no need to add a leading or trailing space to the value. When you use this syntax, BitBake expects one or more strings. -Surrounding spaces and spacing are preserved. Here is an example:: +Surrounding spaces and spacing are preserved. Here is an example: + +.. code-block:: bitbake FOO = "123 456 789 123456 123 456 123 456" FOO:remove = "123"
@@ -362,7 +404,9 @@ expansion time. This implies it is not possible to re-append previously removed strings. However, one can undo a ":remove" by using an intermediate variable whose content is passed to the ":remove" so that modifying the intermediate - variable equals to keeping the string in:: + variable equals to keeping the string in: + + .. code-block:: bitbake FOOREMOVE = "123 456 789" FOO:remove = "${FOOREMOVE}"
@@ -385,27 +429,35 @@ An advantage of the override style operations ":append", ":prepend", and ":remove" as compared to the "+=" and "=+" operators is that the override style operators provide guaranteed operations. For example, consider a class ``foo.bbclass`` that needs to add the value "val" to -the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows:: +the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows: + +.. code-block:: bitbake inherit foo FOO = "initial" If ``foo.bbclass`` uses the "+=" operator, as follows, then the final value of ``FOO`` will be "initial", which is -not what is desired:: +not what is desired: + +.. code-block:: bitbake FOO += "val" If, on the other hand, ``foo.bbclass`` uses the ":append" operator, then the final value of ``FOO`` will be -"initial val", as intended:: +"initial val", as intended: + +.. code-block:: bitbake FOO:append = " val" .. note:: It is never necessary to use "+=" together with ":append". The following - sequence of assignments appends "barbaz" to FOO:: + sequence of assignments appends "barbaz" to FOO: + + .. code-block:: bitbake FOO:append = "bar" FOO:append = "baz"
@@ -432,7 +484,9 @@ standard syntax operations previously mentioned work for variable flags except for override style syntax (i.e. ":prepend", ":append", and ":remove"). -Here are some examples showing how to set variable flags:: +Here are some examples showing how to set variable flags: + +.. code-block:: bitbake FOO[a] = "abc" FOO[b] = "123"
@@ -444,7 +498,9 @@ respectively. The ``[a]`` flag becomes "abc 456". No need exists to pre-define variable flags. You can simply start using them. One extremely common application is to attach some brief -documentation to a BitBake variable as follows:: +documentation to a BitBake variable as follows: + +.. code-block:: bitbake CACHE[doc] = "The directory holding the cache of the metadata."
@@ -458,7 +514,9 @@ Inline Python Variable Expansion -------------------------------- You can use inline Python variable expansion to set variables. Here is -an example:: +an example: + +.. code-block:: bitbake DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
@@ -467,7 +525,9 @@ This example results in the ``DATE`` variable being set to the current date. Probably the most common use of this feature is to extract the value of variables from BitBake's internal data dictionary, ``d``. The following lines select the values of a package name and its version number, -respectively:: +respectively: + +.. 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'}"
@@ -476,12 +536,16 @@ respectively:: Inline Python expressions work just like variable expansions insofar as the "=" and ":=" operators are concerned. Given the following assignment, foo() - is called each time FOO is expanded:: + is called each time FOO is expanded: + + .. code-block:: bitbake FOO = "${@foo()}" Contrast this with the following immediate assignment, where foo() is only - called once, while the assignment is parsed:: + called once, while the assignment is parsed: + + .. code-block:: bitbake FOO := "${@foo()}"
@@ -509,7 +573,9 @@ When specifying pathnames for use with BitBake, do not use the tilde cause BitBake to not recognize the path since BitBake does not expand this character in the same way a shell would. -Instead, provide a fuller path as the following example illustrates:: +Instead, provide a fuller path as the following example illustrates: + +.. code-block:: bitbake BBLAYERS ?= " \ /home/scott-lenovo/LayerA \
@@ -520,7 +586,9 @@ Exporting Variables to the Environment You can export variables to the environment of running tasks by using the ``export`` keyword. For example, in the following example, the -``do_foo`` task prints "value from the environment" when run:: +``do_foo`` task prints "value from the environment" when run: + +.. code-block:: bitbake export ENV_VARIABLE ENV_VARIABLE = "value from the environment"
@@ -538,7 +606,9 @@ It does not matter whether ``export ENV_VARIABLE`` appears before or after assignments to ``ENV_VARIABLE``. It is also possible to combine ``export`` with setting a value for the -variable. Here is an example:: +variable. Here is an example: + +.. code-block:: bitbake export ENV_VARIABLE = "variable-value"
@@ -575,7 +645,9 @@ variable. to satisfy conditions. Thus, if you have a variable that is conditional on "arm", and "arm" is in :term:`OVERRIDES`, then the "arm"-specific version of the variable is used rather than the - non-conditional version. Here is an example:: + non-conditional version. Here is an example: + + .. code-block:: bitbake OVERRIDES = "architecture:os:machine" TEST = "default"
@@ -592,7 +664,9 @@ variable. an OpenEmbedded metadata-based Linux kernel recipe file. The following lines from the recipe file first set the kernel branch variable ``KBRANCH`` to a default value, then conditionally override - that value based on the architecture of the build:: + that value based on the architecture of the build: + + .. code-block:: bitbake KBRANCH = "standard/base" KBRANCH:qemuarm = "standard/arm-versatile-926ejs"
@@ -604,7 +678,9 @@ variable. - *Appending and Prepending:* BitBake also supports append and prepend operations to variable values based on whether a specific item is - listed in :term:`OVERRIDES`. Here is an example:: + listed in :term:`OVERRIDES`. Here is an example: + + .. code-block:: bitbake DEPENDS = "glibc ncurses" OVERRIDES = "machine:local"
@@ -614,14 +690,18 @@ variable. Again, using an OpenEmbedded metadata-based kernel recipe file as an example, the following lines will conditionally append to the - ``KERNEL_FEATURES`` variable based on the architecture:: + ``KERNEL_FEATURES`` variable based on the architecture: + + .. code-block:: bitbake KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc cfg/paravirt_kvm.scc" - *Setting a Variable for a Single Task:* BitBake supports setting a - variable just for the duration of a single task. Here is an example:: + variable just for the duration of a single task. Here is an example: + + .. code-block:: bitbake FOO:task-configure = "val 1" FOO:task-compile = "val 2"
@@ -637,7 +717,9 @@ variable. ``do_compile`` task. You can also use this syntax with other combinations (e.g. - "``:prepend``") as shown in the following example:: + "``:prepend``") as shown in the following example: + + .. code-block:: bitbake EXTRA_OEMAKE:prepend:task-compile = "${PARALLEL_MAKE} "
@@ -655,7 +737,9 @@ Key Expansion ------------- Key expansion happens when the BitBake datastore is finalized. To better -understand this, consider the following example:: +understand this, consider the following example: + +.. code-block:: bitbake A${B} = "X" B = "2"
@@ -681,7 +765,9 @@ There is often confusion concerning the order in which overrides and various "append" operators take effect. Recall that an append or prepend operation using ":append" and ":prepend" does not result in an immediate assignment as would "+=", ".=", "=+", or "=.". Consider the following -example:: +example: + +.. code-block:: bitbake OVERRIDES = "foo" A = "Z"
@@ -698,7 +784,9 @@ Applying overrides, however, changes things. Since "foo" is listed in version, which is equal to "X". So effectively, ``A:foo`` replaces ``A``. -This next example changes the order of the override and the append:: +This next example changes the order of the override and the append: + +.. code-block:: bitbake OVERRIDES = "foo" A = "Z"
@@ -711,7 +799,9 @@ appended with "X". Consequently, ``A`` becomes "ZX". Notice that spaces are not appended. This next example has the order of the appends and overrides reversed -back as in the first example:: +back as in the first example: + +.. code-block:: bitbake OVERRIDES = "foo" A = "Y"
@@ -725,7 +815,9 @@ leaving the variable set to "ZX". Finally, applying the override for "foo" results in the conditional variable ``A`` becoming "ZX" (i.e. ``A`` is replaced with ``A:foo``). -This final example mixes in some varying operators:: +This final example mixes in some varying operators: + +.. code-block:: bitbake A = "1" A:append = "2"
@@ -781,7 +873,9 @@ file and then have your recipe inherit that class file. As an example, your recipes could use the following directive to inherit an ``autotools.bbclass`` file. The class file would contain common -functionality for using Autotools that could be shared across recipes:: +functionality for using Autotools that could be shared across recipes: + +.. code-block:: bitbake inherit autotools
@@ -795,7 +889,9 @@ In this case, BitBake would search for the directory If you want to use the directive to inherit multiple classes, separate them with spaces. The following example shows how to inherit both the -``buildhistory`` and ``rm_work`` classes:: +``buildhistory`` and ``rm_work`` classes: + +.. code-block:: bitbake inherit buildhistory rm_work
@@ -825,12 +921,16 @@ This allows conditional expressions to be evaluated "late", meaning changes to the variable after the line is parsed will take effect. With the :ref:`inherit <ref-bitbake-user-manual-metadata-inherit>` 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 <bitbake-user-manual/bitbake-user-manual-metadata:\`\`require\`\` directive>` -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 <ref-include-all-directive>` 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 <bitbake-user-manual/bitbake-user-manual- that have been promoted to tasks by using the ``addtask`` command. The ``addtask`` command can also optionally describe dependencies between the task and other tasks. Here is an example that shows how to define a -task and declare some dependencies:: +task and declare some dependencies: + +.. code-block:: bitbake python do_printdate () { import datetime
@@ -1598,7 +1756,9 @@ Additionally, the ``do_printdate`` task becomes dependent upon the rerun for experimentation purposes, you can make BitBake always consider the task "out-of-date" by using the :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>` - 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"
PATCH 3/4 doc: bitbake-user-manual-fetching: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- .../bitbake-user-manual-fetching.rst | 124 +++++++++++++----- 1 file changed, 93 insertions(+), 31 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +93 -31
@@ -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 ``[email protected]: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://[email protected]/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=<skoid>&sig=<signature>" -Here is an example URL:: +Here is an example URL: + +.. code-block:: bitbake SRC_URI = "az://<azure-storage-account>.blob.core.windows.net/<foo_container>/<bar_file>"
@@ -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://<bucket name>/PATH \ " -The fetcher can also be used in recipes:: +The fetcher can also be used in recipes: + +.. code-block:: bitbake SRC_URI = "gs://<bucket name>/<foo_container>/<bar_file>" -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] = "<sha256 string>"
@@ -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 <https://en.wikipedia.org/wiki/Npm_(software)>`__ 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 \
PATCH 2/4 doc: bitbake-user-manual-ref-variables: use the bitbake code-block language
In reply to Trevor WoernerBitBake 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)
--- .../bitbake-user-manual-ref-variables.rst | 188 +++++++++++++----- 1 file changed, 141 insertions(+), 47 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +141 -47
@@ -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 <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` 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=<skoid>&sig=<signature>""
@@ -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. <ref-bitbake-user-manual-metadata-inherit-defer>` 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 = "<action>,<dir>,<threshold> [...]"
@@ -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 = "<disk_space_interval>,<disk_inode_interval>"
@@ -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 \
PATCH 4/4 doc: use the bitbake code-block language in the remaining chapters
In reply to Trevor WoernerBitBake 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)
--- .../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(-)
doc/bitbake-user-manual/bitbake-user-manual-execution.rst +33 -11
@@ -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"
doc/bitbake-user-manual/bitbake-user-manual-hello.rst +15 -5
@@ -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/<you>/mylayer \
doc/bitbake-user-manual/bitbake-user-manual-intro.rst +18 -6
@@ -215,7 +215,9 @@ BitBake supports class files installed in three different directories: :term:`INHERIT` variable in a :ref:`configuration file <bitbake-user-manual/bitbake-user-manual-intro:Configuration Files>`. 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 <ref-bitbake-user-manual-metadata-inherit>` or :ref:`inherit_defer <ref-bitbake-user-manual-metadata-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"