doc/bitbake-user-manual/bitbake-user-manual-metadata.rst

19 Basic Variable Setting
22 The following example sets ``VARIABLE`` to "value". This assignment
26    VARIABLE = "value"
31    VARIABLE = " value"
32    VARIABLE = "value "
34 Setting ``VARIABLE`` to "" sets
35 it to an empty string, while setting the variable to " " sets it to a
38    VARIABLE = ""
39    VARIABLE = " "
42 variable's value. Doing so allows you to use values that contain the
45    VARIABLE = 'I have a " in my value'
50    quotes in all other ways. They do not suppress variable expansions.
56 cases where you might find you want to modify an existing variable:
58 -  Customize a recipe that uses the variable.
60 -  Change a variable's default value used in a ``*.bbclass`` file.
62 -  Change the variable in a ``*.bbappend`` file to override the variable
65 -  Change the variable in a configuration file so that the value
68 Changing a variable value can sometimes depend on how the value was
70 particular, when you append a value to a variable that has a default
75 If after you have changed a variable's value and something unexplained
77 variable. You can make these checks for both configuration and recipe
85    command displays variable values after the configuration files (i.e.
94 -  To find changes to a given variable in a specific recipe, use the
99    This command checks to see if the variable actually makes
109 variable assignments over multiple lines, as in the following example::
128    BitBake does not interpret escape sequences like "\\n" in variable
133 Variable Expansion
137 that is similar to variable expansion in Bourne shells. The following
149 The "=" operator does not immediately expand variable references in the
150 right-hand side. Instead, expansion is deferred until the variable
165 :ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable
168 If the variable expansion syntax is used on a variable that does not
179 variable. This type of assignment allows you to define a variable if it
181 if the variable has a value. Here is an example::
186 set at the time this statement is parsed, the variable retains its
187 value. However, if ``A`` is not set, the variable is set to "aval".
192    assignments to a single variable exist, the first of those ends up
198 The weak default value of a variable is the value which that variable
204    A := "${W}" # Immediate variable expansion
206    B := "${W}" # Immediate variable expansion
238 Immediate variable expansion (:=)
241 The ":=" operator results in a variable's contents being expanded
242 immediately, rather than when the variable is actually used::
252 of :term:`T` is "456". The variable :term:`B` will end up containing "456
255 Make, where undefined variables expand to nothing. The variable ``C``
275 The variable :term:`B` contains "bval additionaldata" and ``C`` contains "test
294 The variable :term:`B` contains "bvaladditionaldata" and ``C`` contains
300 You can also append and prepend a variable's value using an override
304 operators in that their effects are applied at variable expansion time
314 The variable :term:`B`
316 The variable ``D`` becomes "dvaladditional data".
333 value to be removed from the variable.
348 The variable ``FOO`` becomes
351 Like ":append" and ":prepend", ":remove" is applied at variable
361 the variable ``FOO``, and a recipe that uses ``foo.bbclass`` as follows::
395 Variable Flag Syntax
398 Variable flags are BitBake's implementation of variable properties or
399 attributes. It is a way of tagging extra information onto a variable.
400 You can find more out about variable flags in general in the
401 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section.
403 You can define, append, and prepend values to variable flags. All the
404 standard syntax operations previously mentioned work for variable flags
408 Here are some examples showing how to set variable flags::
414 The variable ``FOO`` has two flags:
418 No need exists to pre-define variable flags. You can simply start using
420 documentation to a BitBake variable as follows::
424 Inline Python Variable Expansion
427 You can use inline Python variable expansion to set variables. Here is
432 This example results in the ``DATE`` variable being set to the current date.
444    Inline Python expressions work just like variable expansions insofar as the
462 It is possible to completely remove a variable or a variable flag from
508 variable. Here is an example::
510    export ENV_VARIABLE = "variable-value"
531 a variable and to conditionally append or prepend the value of a
532 variable.
538    separate overrides from each other and from the variable name.
540 -  *Selecting a Variable:* The :term:`OVERRIDES` variable is a
542    to satisfy conditions. Thus, if you have a variable that is
544    "arm"-specific version of the variable is used rather than the
553    variable lists three overrides: "architecture", "os", and "machine".
554    The variable ``TEST`` by itself has a default value of "default". You
555    select the os-specific version of the ``TEST`` variable by appending
556    the "os" override to the variable (i.e. ``TEST:os``).
561    variable ``KBRANCH`` to a default value, then conditionally override
573    operations to variable values based on whether a specific item is
584    ``KERNEL_FEATURES`` variable based on the architecture::
590 -  *Setting a Variable for a Single Task:* BitBake supports setting a
591    variable just for the duration of a single task. Here is an example::
641 variable definitions, it can be hard to work out exactly what happens
642 when variable operators, conditional overrides, and unconditional
644 along with explanations for variable interactions that typically confuse
659 immediately appended to the variable ``A:foo``. Because overrides have
664 :term:`OVERRIDES`, the conditional variable ``A`` is replaced with the "foo"
691 leaving the variable set to "ZX". Finally, applying the override for
692 "foo" results in the conditional variable ``A`` becoming "ZX" (i.e.
729 BitBake uses the :term:`BBPATH` variable to locate
735    The BBPATH variable is analogous to the environment variable PATH .
778 accomplish this by using a variable expression after the ``inherit``
788    VARIABLE = ""
789    VARIABLE:someoverride = "myclass"
795            d.setVar('VARIABLE', 'myclass')
797            d.setVar('VARIABLE', '')
999 ("d") is a global variable and is always automatically available.
1003    Variable expressions (e.g.  ``${X}`` ) are no longer expanded within Python
1005    variable values to expandable expressions without having them expanded
1006    prematurely. If you do wish to expand a variable within a Python function,
1077 -  :ref:`Variable flags <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>` such as
1130 of parsing. For example, the following conditionally sets a variable
1131 based on the value of another variable::
1186 the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:inline python variable expansion`" sect…
1300    :ref:`[nostamp] <bitbake-user-manual/bitbake-user-manual-metadata:Variable Flags>`
1301    variable flag, as follows::
1330 See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section for inform…
1331 on variable flags you can use with tasks.
1381    "cleaning" by setting the :term:`BB_PRESERVE_ENV` variable.
1392    the environment variable ``CCACHE_DIR`` to BitBake's passthrough
1393    list to allow that variable into the datastore::
1410       variable as a dependency of the build process in things like the
1412       tasks, you can also flag the variable so that the setscene code
1417 environment into a special variable named :term:`BB_ORIGENV`.
1419 The :term:`BB_ORIGENV` variable returns a datastore object that can be
1422 find the original ``DISPLAY`` variable. Here is an example::
1430 Variable Flags
1433 Variable flags (varflags) help control a task's functionality and
1437    variable = d.getVarFlags("variable")
1443 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:variable flag syntax`" section for details.
1454    :term:`DEPENDS` variable and the
1459 …:term:`DEPENDS` variable and the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:build dep…
1469    released. You can use this variable flag to accomplish mutual
1492    :term:`BB_NUMBER_THREADS` variable but is task-specific.
1504          the :term:`BB_NUMBER_THREADS` variable causes ``number_threads`` to
1513    :term:`RDEPENDS` variable, the
1514    :term:`RRECOMMENDS` variable, and the
1519    :term:`RDEPENDS` variable, the
1520    :term:`RRECOMMENDS` variable, and the
1529    See the :term:`RDEPENDS` variable, the
1530    :term:`RRECOMMENDS` variable, and the
1545    variables to add to a variable's dependencies for the purposes of
1547    for example, when a function refers to a variable in a manner that
1548    does not allow BitBake to automatically determine that the variable
1552    that should be excluded from a variable's dependencies for the
1556    value of the variable and instead use the specified value when
1557    calculating the variable's signature.
1560    strings to exclude from the variable's value when calculating the
1561    variable's signature.
1574 and the content of the :term:`FILE` variable::
1588 event matching the eventmask is triggered. A global variable "e" is
1623    ``BB_HEARTBEAT_EVENT`` variable. The event's "time" attribute is the
1688 :term:`BBCLASSEXTEND` variable.
1690 The :term:`BBCLASSEXTEND` variable is a space separated list of classes used
1768 BitBake uses the :term:`DEPENDS` variable to manage
1785 The :term:`PACKAGES` variable lists runtime packages. Each of those packages
1870      - Returns the value of variable "X". Using "expand=True" expands the
1871        value. Returns "None" if the variable "X" does not exist.
1873      - Sets the variable "X" to "value"
1875      - Adds "value" to the end of the variable "X". Acts like ``d.setVar("X",
1876        "value")`` if the variable "X" does not exist.
1878      - Adds "value" to the start of the variable "X". Acts like
1879        ``d.setVar("X","value")`` if the variable "X" does not exist.
1881      - Deletes the variable "X" from the datastore. Does nothing if the variable
1884      - Renames the variable "X" to "Y". Does nothing if the variable "X" does
1887      - Returns the value of variable "X". Using "expand=True" expands the
1888        value. Returns "None" if either the variable "X" or the named flag does
1891      - Sets the named flag for variable "X" to "value".
1893      - Appends "value" to the named flag on the variable "X". Acts like
1896      - Prepends "value" to the named flag on the variable "X". Acts like
1899      - Deletes the named flag on the variable "X" from the datastore.
1905      - Returns a ``flagsdict`` of the flags for the variable "X". Returns "None"
1906        if the variable "X" does not exist.
1908      - Deletes all the flags for the variable "X". Does nothing if the variable
1911      - Expands variable references in the specified string
1914        ${X}" if the variable "X" does not exist.
1943 reveals that the "CC" variable is part of the inputs that are hashed.
1944 Any changes to this variable would invalidate the stamp and cause the
1958    this variable holds the hash of the task as returned by the currently