diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 167d107155..dbbe67657d 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1507,8 +1507,8 @@
For information on recipe syntax, see the
- "Recipe Syntax"
- section in the Getting Started With Yocto Project Manual.
+ "Recipe Syntax"
+ section.
@@ -3505,6 +3505,330 @@
style.
+
+
+ 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"
+
+
+ You cannot have any characters including spaces
+ or tabs after the slash character.
+
+
+
+ Using Variables (${VARNAME}):
+ Use the ${VARNAME}
+ syntax to access the contents of a variable:
+
+ SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
+
+
+ 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 values in all variable
+ assignments (e.g.
+ "value").
+ Following is an example:
+
+ 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.
+
+ 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.
+
+ 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:
+ 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.
+
+
+
+
diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml
index 03a807e4a5..096517b729 100644
--- a/documentation/getting-started/getting-started-development-environment.xml
+++ b/documentation/getting-started/getting-started-development-environment.xml
@@ -17,7 +17,7 @@
Specifically, this chapter addresses open source philosophy, workflows,
- Git, source repositories, licensing, recipe syntax, and development
+ Git, source repositories, licensing, and development
syntax.
@@ -938,303 +938,6 @@
-
- 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"
-
-
- 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"
-
-
- 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.
-
- 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.
-
- 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.
-
-
-
-
-
Development Concepts