2.7. Recipe Syntax

Understanding recipe file syntax is important for writing recipes. The following list overviews the basic items that make up a BitBake recipe file. For more complete BitBake syntax descriptions, see the "Syntax and Operators" chapter of the BitBake User Manual.

Variable Assignments and Manipulations: Variable assignments allow a value to be assigned to a variable. The assignment can be static text or might include the contents of other variables. In addition to the assignment, appending and prepending operations are also supported.

The following example shows some of the ways you can use variables in recipes:
```
     S = "${WORKDIR}/postfix-${PV}"
     CFLAGS += "-DNO_ASM"
     SRC_URI_append = " file://fixup.patch"
                
```
Functions: Functions provide a series of actions to be performed. You usually use functions to override the default implementation of a task function or to complement a default function (i.e. append or prepend to an existing function). Standard functions use sh shell syntax, although access to OpenEmbedded variables and internal methods are also available.

The following is an example function from the sed recipe:
```
     do_install () {
         autotools_do_install
         install -d ${D}${base_bindir}
         mv ${D}${bindir}/sed ${D}${base_bindir}/sed
         rmdir ${D}${bindir}/
     }
                
```
It is also possible to implement new functions that are called between existing tasks as long as the new functions are not replacing or complementing the default functions. You can implement functions in Python instead of shell. Both of these options are not seen in the majority of recipes.
Keywords: BitBake recipes use only a few keywords. You use keywords to include common functions (inherit), load parts of a recipe from other files (include and require) and export variables to the environment (export).

The following example shows the use of some of these keywords:
```
     export POSTCONF = "${STAGING_BINDIR}/postconf"
     inherit autoconf
     require otherfile.inc
                
```
Comments: Any lines that begin with the hash character (#) are treated as comment lines and are ignored:
```
     # This is a comment
                
```

This next list summarizes the most important and most commonly used parts of the recipe syntax. For more information on these parts of the syntax, you can reference the Syntax and Operators chapter in the BitBake User Manual.

Line Continuation: \ - Use the backward slash (\) character to split a statement over multiple lines. Place the slash character at the end of the line that is to be continued on the next line:
```
     VAR = "A really long \
            line"
                
```
Note
You cannot have any characters including spaces or tabs after the slash character.
Using Variables: ${...} - Use the ${VARNAME} syntax to access the contents of a variable:
```
     SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
                
```
Note
It is important to understand that the value of a variable expressed in this form does not get substituted automatically. The expansion of these expressions happens on-demand later (e.g. usually when a function that makes reference to the variable executes). This behavior ensures that the values are most appropriate for the context in which they are finally used. On the rare occasion that you do need the variable expression to be expanded immediately, you can use the := operator instead of = when you make the assignment, but this is not generally needed.
Quote All Assignments: "value" - Use double quotes around the value in all variable assignments.
```
     VAR1 = "${OTHERVAR}"
     VAR2 = "The version is ${PV}"
                
```
Conditional Assignment: ?= - Conditional assignment is used to assign a value to a variable, but only when the variable is currently unset. Use the question mark followed by the equal sign (?=) to make a "soft" assignment used for conditional assignment. Typically, "soft" assignments are used in the local.conf file for variables that are allowed to come through from the external environment.

Here is an example where VAR1 is set to "New value" if it is currently empty. However, if VAR1 has already been set, it remains unchanged:
```
     VAR1 ?= "New value"
                
```
In this next example, VAR1 is left with the value "Original value":
```
     VAR1 = "Original value"
     VAR1 ?= "New value"
                
```
Appending: += - Use the plus character followed by the equals sign (+=) to append values to existing variables.

Note
This operator adds a space between the existing content of the variable and the new content.

Here is an example:
```
     SRC_URI += "file://fix-makefile.patch"
                
```
Prepending: =+ - Use the equals sign followed by the plus character (=+) to prepend values to existing variables.

Note
This operator adds a space between the new content and the existing content of the variable.

Here is an example:
```
     VAR =+ "Starts"
                
```
Appending: _append - Use the _append operator to append values to existing variables. This operator does not add any additional space. Also, the operator is applied after all the +=, and =+ operators have been applied and after all = assignments have occurred.

The following example shows the space being explicitly added to the start to ensure the appended value is not merged with the existing value:
```
     SRC_URI_append = " file://fix-makefile.patch"
                
```
You can also use the _append operator with overrides, which results in the actions only being performed for the specified target or machine:
```
     SRC_URI_append_sh4 = " file://fix-makefile.patch"
                
```
Prepending: _prepend - Use the _prepend operator to prepend values to existing variables. This operator does not add any additional space. Also, the operator is applied after all the +=, and =+ operators have been applied and after all = assignments have occurred.

The following example shows the space being explicitly added to the end to ensure the prepended value is not merged with the existing value:
```
     CFLAGS_prepend = "-I${S}/myincludes "
                
```
You can also use the _prepend operator with overrides, which results in the actions only being performed for the specified target or machine:
```
     CFLAGS_prepend_sh4 = "-I${S}/myincludes "
                
```
Overrides: - You can use overrides to set a value conditionally, typically based on how the recipe is being built. For example, to set the KBRANCH variable's value to "standard/base" for any target MACHINE, except for qemuarm where it should be set to "standard/arm-versatile-926ejs", you would do the following:
```
     KBRANCH = "standard/base"
     KBRANCH_qemuarm  = "standard/arm-versatile-926ejs"
                
```
Overrides are also used to separate alternate values of a variable in other situations. For example, when setting variables such as FILES and RDEPENDS that are specific to individual packages produced by a recipe, you should always use an override that specifies the name of the package.
Indentation: Use spaces for indentation rather than than tabs. For shell functions, both currently work. However, it is a policy decision of the Yocto Project to use tabs in shell functions. Realize that some layers have a policy to use spaces for all indentation.
Using Python for Complex Operations: ${@python_code} - For more advanced processing, it is possible to use Python code during variable assignments (e.g. search and replacement on a variable).

You indicate Python code using the ${@python_code} syntax for the variable assignment:
```
     SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
                
```
Shell Function Syntax: Write shell functions as if you were writing a shell script when you describe a list of actions to take. You should ensure that your script works with a generic sh and that it does not require any bash or other shell-specific functionality. The same considerations apply to various system utilities (e.g. sed, grep, awk, and so forth) that you might wish to use. If in doubt, you should check with multiple implementations - including those from BusyBox.

2.7. Recipe Syntax

Note

Note

Note

Note