From 2fc9281c49a562083d3736b2f8b159f0e76e3c0b Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 3 Feb 2014 11:51:04 -0600 Subject: bitbake: user-manual-metadata.xml: Edits through syntax section I made some general improvements in the "Overview" and "Basic Syntax" sections. Additionally, I added a blank section for "Variable Flags" that will eventually hold general information on this concept. Finally, come review edits to the "Defining Pure Python Functions" section per Paul Eggleton. (Bitbake rev: 665d655f436f1a353f5fe467c5d97588f7b121c5) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- bitbake/doc/user-manual/user-manual-metadata.xml | 280 +++++++++++++++-------- 1 file changed, 183 insertions(+), 97 deletions(-) (limited to 'bitbake') diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml index abfc89d75c..fb4bf4044c 100644 --- a/bitbake/doc/user-manual/user-manual-metadata.xml +++ b/bitbake/doc/user-manual/user-manual-metadata.xml @@ -8,39 +8,53 @@ Overview - The BitBake task executor together with various types of configuration files form the OpenEmbedded - Core. - This section provides an overview of the BitBake task executor and the configuration files by - describing what they are used for and how they interact. + The BitBake task executor together with various types of configuration + files form the OpenEmbedded Core. + This section provides an overview of the task executor and the + configuration files by describing their use and interaction. - BitBake handles the parsing and execution of the data files. The data itself is of various types: + BitBake handles the parsing and execution of the data files. + The data itself is of various types: Recipes: - Provides details about particular pieces of software. + Details about particular pieces of software. + Class Data: - An abstraction of common build information (e.g. how to build a Linux kernel). + An abstraction of common build information + (e.g. how to build a Linux kernel). + Configuration Data: - Defines machine-specific settings, policy decisions, etc. Configuration data acts - as the glue to bind everything together. + Machine-specific settings, policy decisions, + and so forth. + Configuration data acts as the glue to bind everything + together. - What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported - in any of the aforementioned areas will be documented as such. + The remainder of this chapter provides examples of BitBake metadata. + Any syntax not supported in any of the previously listed areas + is documented as such.
Basic Syntax + + This section provides some basic syntax examples. + +
Basic Variable Setting + The following example sets VARIABLE to + "value". + This assignment occurs immediately as the statement is parsed. + It is a "hard" assignment. VARIABLE = "value" - In this example, VARIABLE is value.
@@ -49,18 +63,14 @@ BitBake supports variables referencing one another's - contents using a syntax which is similar to shell - scripting - - - + contents using a syntax that is similar to shell scripting. + Following is an example that results in A + containing "aval" and B containing + "preavalpost". A = "aval" B = "pre${A}post" - This results in A containing - aval and B containing - preavalpost.
@@ -68,16 +78,24 @@ Setting a default value (?=) + You can use the "?=" operator to achieve a "softer" assignment + for a variable. + This type of assignment allows you to define a variable if it + is undefined when the statement is parsed, but to leave the + value alone if the variable has a value. + Here is an example: A ?= "aval" - If A is set before the above is called, - it will retain its previous value. - If A is unset prior to the above call, - A will be set to aval. + If A is set at the time this statement is parsed, + the variable retains its value. + However, if A is not set, + the variable is set to "aval". - This assignment is immediate, so if there are multiple "?=" assignments - to a single variable, the first of those will be used. + This assignment is immediate. + Consequently, if multiple "?=" assignments + to a single variable exist, the first of those ends up getting + used. @@ -86,19 +104,30 @@ Setting a weak default value (??=) + It is possible to use a "weaker" assignment that in the + previous section by using the "??=" operator. + This assignment behaves identical to "?=" except that the + assignment is made at the end of the parsing process rather + than immediately. + Consequently, when multiple "??=" assignments exist, the last + one is used. + Also, any "=" or "?=" assignment will override the value set with + "??=". + Here is an example: A ??= "somevalue" A ??= "someothervalue" - If A is set before the above, - it will retain that value. - If A is unset prior to the above, - A will be set to someothervalue. - This is a lazy or weak assignment in that the assignment does not occur until the end - of the parsing process, so that the last, rather than the first, - "??=" assignment to a given variable will be used. - Any other setting of A using "=" or "?=" - will, however, override the value set with "??=". + If A is set before the above statements are parsed, + the variable retains its value. + If A is not set, + the variable is set to "someothervalue". + + + + Again, this assignment is a "lazy" or "weak" assignment + because it does not occur until the end + of the parsing process. @@ -106,7 +135,8 @@ Immediate variable expansion (:=) - The ":=" operator results in a variable's contents being expanded immediately, + The ":=" operator results in a variable's + contents being expanded immediately, rather than when the variable is actually used: T = "123" @@ -116,26 +146,34 @@ C = "cval" C := "${C}append" - In this example, A would contain - test 123, B would contain - 456 bval, and C - would be cvalappend. + In this example, A contains + "test 123" because ${B} and + ${A} at the time of parsing are undefined, + which leaves "test 123". + And, the variable C + contains "cvalappend" since ${C} immediately + expands to "cval".
- Appending (+=) and prepending (=+) + Appending (+=) and prepending (=+) With Spaces + Appending and prepending values is common and can be accomplished + using the "+=" and "=+" operators. + These operators insert a space between the current + value and prepended or appended value. + Here are some examples: B = "bval" B += "additionaldata" C = "cval" C =+ "test" - In this example, B is now - bval additionaldata and C - is test cval. + The variable B contains + "bval additionaldata" and C + contains "test cval".
@@ -143,17 +181,18 @@ Appending (.=) and Prepending (=.) Without Spaces + If you want to append or prepend values without an + inserted space, use the ".=" and "=." operators. + Here are some examples: B = "bval" B .= "additionaldata" C = "cval" C =. "test" - In this example, B is now - bvaladditionaldata and - C is testcval. - In contrast to the above appending and prepending operators, - no additional space will be introduced. + The variable B contains + "bvaladditionaldata" and + C contains "testcval". @@ -161,49 +200,88 @@ Appending and Prepending (Override Style Syntax) + You can also append and prepend a variable's value + using an override style syntax. + When you use this syntax, no spaces are inserted. + Here are some examples: B = "bval" B_append = " additional data" C = "cval" C_prepend = "additional data " + D = "dval" + D_append = "additional data" - This example results in B - becoming bval additional data and - C becoming - additional data cval. + The variable B becomes + "bval additional data" and C becomes + "additional data cval". + The variable D becomes + "dvaladditional data". - The spaces in _append. - Unlike the "+=" operator, additional space is not automatically added. - You must take steps to add space yourself. + You must control all spacing when you use the + override syntax.
- Removing (Override Style Syntax) + Removal (Override Style Syntax) + You can remove values from lists using the removal + override style syntax. + Specifying a value for removal causes all occurrences of that + value to be removed from the variable. + + + + When you use this syntax, BitBake expects one or more strings. + Surrounding spaces are removed as well. + Here is an example: FOO = "123 456 789 123456 123 456 123 456" FOO_remove = "123" FOO_remove = "456" + FOO2 = "abc def ghi abcdef abc def abc def" + FOO2_remove = "abc def" - In this example, FOO is now 789 123456. + The variable FOO becomes + "789 123456" and FOO2 becomes + "ghi abcdef".
-
- Variable Flags +
+ Variable Flag Syntax - Variables can have associated flags which provide a way of tagging extra information onto a variable. - Several flags are used internally by BitBake but they can be used externally too if needed. - The standard operations mentioned above also work on flags. + Variable flags are BitBake's implementation of variable properties + or attributes. + It is a way of tagging extra information onto a variable. + You can find more out about variable flags in general in the + "Variable Flags" + section. + + + + You can define, append, and prepend values to variable flags. + All the standard syntax operations previously mentioned work + for variable flags except for override style syntax + (i.e. _prepend, _append, + and _remove). + + + + Here are some examples showing how to set variable flags: - VARIABLE[SOMEFLAG] = "value" + FOO[a] = "abc" + FOO[b] = "123" + FOO[a] += "456" - In this example, VARIABLE has a flag, - SOMEFLAG that is set to value. + The variable FOO has two flags: + a and b. + The flags are immediately set to "abc" and "123", respectively. + The a flag becomes "abc456".
@@ -211,11 +289,14 @@ Inline Python Variable Expansion + You can use inline Python variable expansion to + set variables. + Here is an example: DATE = "${@time.strftime('%Y%m%d',time.gmtime())}" - This would result in the DATE - variable containing today's date. + This example results in the DATE + variable becoming the current date.
@@ -391,33 +472,6 @@ -
- Defining Python Functions into the Global Python Namespace - - - - This is only supported in .bb - and .bbclass files. - - - - Python functions are in the global namespace so should use - unique names. - - def get_depends(d): - if d.getVar('SOMECONDITION', True): - return "dependencywithcond" - else: - return "dependency" - SOMECONDITION = "1" - DEPENDS = "${@get_depends(d)}" - - This would result in DEPENDS - containing dependencywithcond. - - -
-
Functions @@ -474,6 +528,30 @@
+
+ Defining Pure Python functions + + + This is only supported in .bb + and .bbclass files. + + + + Python functions should use unique names. + + def get_depends(d): + if d.getVar('SOMECONDITION', True): + return "dependencywithcond" + else: + return "dependency" + SOMECONDITION = "1" + DEPENDS = "${@get_depends(d)}" + + This would result in DEPENDS + containing dependencywithcond. + +
+
Tasks @@ -583,6 +661,14 @@
+
+ Variable Flags + + + This section describes variable flags. + +
+
Task Flags @@ -702,7 +788,7 @@
-
+
Configuration files @@ -992,7 +1078,7 @@ - It may be desireable to recurse not just through the + It may be desirable to recurse not just through the dependencies of those tasks but through the build and runtime dependencies of dependent tasks too. If that is the case, the taskname itself should -- cgit v1.2.3-54-g00ecf