From 8d320536dcda978a43693e1874c32d9d95e42b5e Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 1 Feb 2018 10:30:31 -0800 Subject: dev-manual, getting-started: Moved the BB syntax section This section on BitBake syntax appeared in the Getting Started manual. I decided that it should live with the section on writing a new recipe. (From yocto-docs rev: 8d83ce3e11405b2f12f27cdd117a19c4af52146a) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 328 ++++++++++++++++++++- .../getting-started-development-environment.xml | 299 +------------------ 2 files changed, 327 insertions(+), 300 deletions(-) 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 -- cgit v1.2.3-54-g00ecf