2.7. Recipe Syntax

+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