diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index bead56c978..9c316909e8 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1283,6 +1283,280 @@
+
+ Understanding Recipe Syntax
+
+
+ The basic items that make up a BitBake recipe file are
+ as follows:
+
+ Functions:
+ Functions provide a series of actions to be performed.
+ Functions are usually used to override the default
+ implementation of a task function, or to compliment
+ (append or prepend to an existing function) a default
+ 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.${PN}
+ }
+
+ It is also possible to implement new functions, that
+ are not replacing or complimenting the default
+ functions, which are called between existing tasks.
+ It is also possible to implement functions in Python
+ instead of sh.
+ Both of these options are not seen in the majority of
+ recipes.
+ 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 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}"
+ PR = "r4"
+ CFLAGS += "-DNO_ASM"
+ SRC_URI_append = "file://fixup.patch"
+
+
+ Keywords:
+ Only a few keywords are used in BitBake recipes.
+ Keywords are used for things such as including common
+ functions (inherit), loading parts
+ of a recipe from other files
+ (include and
+ require) and exporting 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"
+
+
+ Quote All Assignments: "<value>" -
+ Use double quotes to make 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, you use conditional assignment to
+ provide
+ a default value for use when no specific definition is
+ provided by the machine or distro configuration in
+ your local.conf configuration.
+
+ Here is an example:
+
+ VAR1 ?= "New value"
+
+ In the previous example, VAR1 is
+ set to "New value" if it is currently empty.
+ However, if VAR1 has already been
+ set, it remains unchanged.
+ 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.
+
+ 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"
+
+
+ The appended information is a variable itself.
+ Therefore, it is possible to use the
+ += or
+ =+ operators to assign
+ variables to the _append
+ information:
+
+ SRC_URI_append = " file://fix-makefile.patch"
+ SRC_URI_append += "file://fix-install.patch"
+
+
+
+ Prepending: _prepend -
+ Use the _prepend operator to
+ prepend values to existing variables.
+ This operator does not add any additional space.
+ Also, it is applied after all the
+ += and
+ =+ operators have been applied.
+
+ 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 = " file://fix-makefile.patch"
+
+
+ The appended information is a variable itself.
+ Therefore, it is possible to use the
+ += or
+ =+ operators to assign
+ variables to the _prepend
+ information:
+
+ CFLAGS_prepend = "-I${S}/myincludes "
+ CFLAGS_prepend += "-I${S}/myincludes2 "
+
+ Notice in this example no spacing is used at the
+ front of the value string.
+ Recall that the += operator
+ adds space itself.
+
+
+ Spaces as Compared to Tabs:
+ Use spaces for indentation rather than than tabs.
+ Both currently work, however it is a policy decision
+ of the Yocto Project to use tabs in shell functions
+ and spaces in Python.
+ However, realize that some layers use a policy of all
+ spaces.
+
+ 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 a preceding
+ @ character in the variable
+ assignment:
+
+ CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"
+
+
+ Shell Syntax:
+ Use shell syntax 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.
+
+
+
+
+
Running a Build on the Recipe