From d369f333836b70e4109113f41bad4fddf49e3aaa Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 9 Aug 2017 17:15:15 -0700 Subject: dev-manual, ref-manual: Moved recipe syntax section to ref-manual The section on recipe syntax that was buried in the creating a new recipe section was really a reference on syntax. I have moved it to the ref-manual. (From yocto-docs rev: cb55d1b5832cca6faa6e2a5b26f3add3032cade2) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 302 +------------------- .../ref-manual/ref-development-environment.xml | 307 ++++++++++++++++++++- 2 files changed, 308 insertions(+), 301 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index e4cfdcdef2..cc69d641c5 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1482,6 +1482,11 @@ similar in function to the recipe you need. + + For information on recipe syntax, see the + "Recipe Syntax" + section in the Yocto Project Reference Manual. +
@@ -1702,303 +1707,6 @@
-
- Understanding 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. - - - -
-
Running a Build on the Recipe diff --git a/documentation/ref-manual/ref-development-environment.xml b/documentation/ref-manual/ref-development-environment.xml index d0b1f0f1d3..36de2d0a72 100644 --- a/documentation/ref-manual/ref-development-environment.xml +++ b/documentation/ref-manual/ref-development-environment.xml @@ -13,10 +13,12 @@ help you understand how work is accomplished in an open source environment, which is very different as compared to work accomplished in a closed, proprietary environment. - This chapter specifically addresses open source philosophy, using the - Yocto Project in a team environment, source repositories, Yocto Project - terms, licensing, the open source distributed version control system Git, - workflows, bug tracking, and how to submit changes. + + + + Specifically, this chapter addresses open source philosophy, workflows, + Git, source repositories, licensing, recipe syntax, and development + syntax.
@@ -819,6 +821,303 @@
+
+ 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 -- cgit v1.2.3-54-g00ecf