diff options
Diffstat (limited to 'import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml')
| -rw-r--r-- | import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml | 1079 |
1 files changed, 857 insertions, 222 deletions
diff --git a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml index 6329cd6e4..71bb25bf7 100644 --- a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +++ b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml @@ -44,28 +44,73 @@ VARIABLE = " " </literallayout> </para> + + <para> + You can use single quotes instead of double quotes + when setting a variable's value. + Doing so allows you to use values that contain the double + quote character: + <literallayout class='monospaced'> + VARIABLE = 'I have a " in my value' + </literallayout> + <note> + Unlike in Bourne shells, single quotes work identically + to double quotes in all other ways. + They do not suppress variable expansions. + </note> + </para> </section> <section id='variable-expansion'> <title>Variable Expansion</title> <para> - BitBake supports variables referencing one another's - contents using a syntax that is similar to shell scripting. - Following is an example that results in <filename>A</filename> - containing "aval" and <filename>B</filename> evaluating to - "preavalpost" based on that current value of - <filename>A</filename>. + Variables can reference the contents of other variables + using a syntax that is similar to variable expansion in + Bourne shells. + The following assignments + result in A containing "aval" and B evaluating to "preavalpost". <literallayout class='monospaced'> A = "aval" B = "pre${A}post" </literallayout> - You should realize that whenever <filename>B</filename> is - referenced, its evaluation will depend on the state of - <filename>A</filename> at that time. - Thus, later evaluations of <filename>B</filename> in the - previous example could result in different values - depending on the value of <filename>A</filename>. + <note> + Unlike in Bourne shells, the curly braces are mandatory: + Only <filename>${FOO}</filename> and not + <filename>$FOO</filename> is recognized as an expansion of + <filename>FOO</filename>. + </note> + The "=" operator does not immediately expand variable + references in the right-hand side. + Instead, expansion is deferred until the variable assigned to + is actually used. + The result depends on the current values of the referenced + variables. + The following example should clarify this behavior: + <literallayout class='monospaced'> + A = "${B} baz" + B = "${C} bar" + C = "foo" + *At this point, ${A} equals "foo bar baz"* + C = "qux" + *At this point, ${A} equals "qux bar baz"* + B = "norf" + *At this point, ${A} equals "norf baz"* + </literallayout> + Contrast this behavior with the + <link linkend='immediate-variable-expansion'>immediate variable expansion</link> + operator (i.e. ":="). + </para> + + <para> + If the variable expansion syntax is used on a variable that + does not exist, the string is kept as is. + For example, given the following assignment, + <filename>BAR</filename> expands to the literal string + "${FOO}" as long as <filename>FOO</filename> does not exist. + <literallayout class='monospaced'> + BAR = "${FOO}" + </literallayout> </para> </section> @@ -232,6 +277,15 @@ override syntax. </note> </para> + + <para> + It is also possible to append and prepend to shell + functions and BitBake-style Python functions. + See the + "<link linkend='shell-functions'>Shell Functions</link>" and + "<link linkend='bitbake-style-python-functions'>BitBake-Style Python Functions</link> + sections for examples. + </para> </section> <section id='removing-override-style-syntax'> @@ -259,6 +313,60 @@ "789 123456" and <filename>FOO2</filename> becomes "ghi abcdef". </para> + + <para> + Like "_append" and "_prepend", "_remove" + is deferred until after parsing completes. + </para> + </section> + + <section id='override-style-operation-advantages'> + <title>Override Style Operation Advantages</title> + + <para> + An advantage of the override style operations + "_append", "_prepend", and "_remove" as compared to the + "+=" and "=+" operators is that the override style + operators provide guaranteed operations. + For example, consider a class <filename>foo.bbclass</filename> + that needs to add the value "val" to the variable + <filename>FOO</filename>, and a recipe that uses + <filename>foo.bbclass</filename> as follows: + <literallayout class='monospaced'> + inherit foo + + FOO = "initial" + </literallayout> + If <filename>foo.bbclass</filename> uses the "+=" operator, + as follows, then the final value of <filename>FOO</filename> + will be "initial", which is not what is desired: + <literallayout class='monospaced'> + FOO += "val" + </literallayout> + If, on the other hand, <filename>foo.bbclass</filename> + uses the "_append" operator, then the final value of + <filename>FOO</filename> will be "initial val", as intended: + <literallayout class='monospaced'> + FOO_append = " val" + </literallayout> + <note> + It is never necessary to use "+=" together with "_append". + The following sequence of assignments appends "barbaz" to + <filename>FOO</filename>: + <literallayout class='monospaced'> + FOO_append = "bar" + FOO_append = "baz" + </literallayout> + The only effect of changing the second assignment in the + previous example to use "+=" would be to add a space before + "baz" in the appended value (due to how the "+=" operator + works). + </note> + Another advantage of the override style operations is that + you can combine them with other overrides as described in the + "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>" + section. + </para> </section> <section id='variable-flag-syntax'> @@ -277,8 +385,7 @@ 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. <filename>_prepend</filename>, <filename>_append</filename>, - and <filename>_remove</filename>). + (i.e. "_prepend", "_append", and "_remove"). </para> <para> @@ -289,9 +396,9 @@ FOO[a] += "456" </literallayout> The variable <filename>FOO</filename> has two flags: - <filename>a</filename> and <filename>b</filename>. + <filename>[a]</filename> and <filename>[b]</filename>. The flags are immediately set to "abc" and "123", respectively. - The <filename>a</filename> flag becomes "abc 456". + The <filename>[a]</filename> flag becomes "abc 456". </para> <para> @@ -330,7 +437,43 @@ PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[0] or 'defaultpkgname'}" PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE', False),d)[1] or '1.0'}" </literallayout> + <note> + Inline Python expressions work just like variable expansions + insofar as the "=" and ":=" operators are concerned. + Given the following assignment, <filename>foo()</filename> + is called each time <filename>FOO</filename> is expanded: + <literallayout class='monospaced'> + FOO = "${@foo()}" + </literallayout> + Contrast this with the following immediate assignment, where + <filename>foo()</filename> is only called once, while the + assignment is parsed: + <literallayout class='monospaced'> + FOO := "${@foo()}" + </literallayout> + </note> + For a different way to set variables with Python code during + parsing, see the + "<link linkend='anonymous-python-functions'>Anonymous Python Functions</link>" + section. + </para> + </section> + + <section id='unsetting-variables'> + <title>Unseting variables</title> + + <para> + It is possible to completely remove a variable or a variable flag + from BitBake's internal data dictionary by using the "unset" keyword. + Here is an example: + <literallayout class='monospaced'> + unset DATE + unset do_fetch[noexec] + </literallayout> + These two statements remove the <filename>DATE</filename> and the + <filename>do_fetch[noexec]</filename> flag. </para> + </section> <section id='providing-pathnames'> @@ -357,6 +500,53 @@ </section> </section> + <section id='exporting-variables-to-the-environment'> + <title>Exporting Variables to the Environment</title> + + <para> + You can export variables to the environment of running + tasks by using the <filename>export</filename> keyword. + For example, in the following example, the + <filename>do_foo</filename> task prints "value from + the environment" when run: + <literallayout class='monospaced'> + export ENV_VARIABLE + ENV_VARIABLE = "value from the environment" + + do_foo() { + bbplain "$ENV_VARIABLE" + } + </literallayout> + <note> + BitBake does not expand <filename>$ENV_VARIABLE</filename> + in this case because it lacks the obligatory + <filename>{}</filename>. + Rather, <filename>$ENV_VARIABLE</filename> is expanded + by the shell. + </note> + It does not matter whether + <filename>export ENV_VARIABLE</filename> appears before or + after assignments to <filename>ENV_VARIABLE</filename>. + </para> + + <para> + It is also possible to combine <filename>export</filename> + with setting a value for the variable. + Here is an example: + <literallayout class='monospaced'> + export ENV_VARIABLE = "<replaceable>variable-value</replaceable>" + </literallayout> + In the output of <filename>bitbake -e</filename>, variables + that are exported to the environment are preceded by "export". + </para> + + <para> + Among the variables commonly exported to the environment + are <filename>CC</filename> and <filename>CFLAGS</filename>, + which are picked up by many build systems. + </para> + </section> + <section id='conditional-syntax-overrides'> <title>Conditional Syntax (Overrides)</title> @@ -455,6 +645,34 @@ KERNEL_FEATURES_append_qemux86-64=" cfg/sound.scc cfg/paravirt_kvm.scc" </literallayout> </para></listitem> + <listitem><para><emphasis>Setting a Variable for a Single Task:</emphasis> + BitBake supports setting a variable just for the + duration of a single task. + Here is an example: + <literallayout class='monospaced'> + FOO_task-configure = "val 1" + FOO_task-compile = "val 2" + </literallayout> + In the previous example, <filename>FOO</filename> + has the value "val 1" while the + <filename>do_configure</filename> task is executed, + and the value "val 2" while the + <filename>do_compile</filename> task is executed. + </para> + + <para>Internally, this is implemented by prepending + the task (e.g. "task-compile:") to the value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + for the local datastore of the <filename>do_compile</filename> + task.</para> + + <para>You can also use this syntax with other combinations + (e.g. "<filename>_prepend</filename>") as shown in the + following example: + <literallayout class='monospaced'> + EXTRA_OEMAKE_prepend_task-compile = "${PARALLEL_MAKE} " + </literallayout> + </para></listitem> </itemizedlist> </para> </section> @@ -545,15 +763,15 @@ OVERRIDES = "foo" A = "Y" A_foo_append = "Z" - A_foo_append += "X" + A_foo_append = "X" </literallayout> For this case, before any overrides are resolved, <filename>A</filename> is set to "Y" using an immediate assignment. After this immediate assignment, <filename>A_foo</filename> is set to "Z", and then further appended with - "X" leaving the variable set to "Z X". + "X" leaving the variable set to "ZX". Finally, applying the override for "foo" results in the conditional - variable <filename>A</filename> becoming "Z X" (i.e. + variable <filename>A</filename> becoming "ZX" (i.e. <filename>A</filename> is replaced with <filename>A_foo</filename>). </para> @@ -572,7 +790,7 @@ Initially, <filename>A</filename> is set to "1 45" because of the three statements that use immediate operators. After these assignments are made, BitBake applies the - <filename>_append</filename> operations. + "_append" operations. Those operations result in <filename>A</filename> becoming "1 4523". </para> </section> @@ -842,7 +1060,7 @@ directly as functions, tasks, or both. They can also be called by other shell functions. </para></listitem> - <listitem><para><emphasis>BitBake Style Python Functions:</emphasis> + <listitem><para><emphasis>BitBake-Style Python Functions:</emphasis> Functions written in Python and executed by BitBake or other Python functions using <filename>bb.build.exec_func()</filename>. </para></listitem> @@ -881,10 +1099,60 @@ such as <filename>dash</filename>. You should not use Bash-specific script (bashisms). </para> + + <para> + Overrides and override-style operators like + <filename>_append</filename> and + <filename>_prepend</filename> can also be applied to + shell functions. + Most commonly, this application would be used in a + <filename>.bbappend</filename> file to modify functions in + the main recipe. + It can also be used to modify functions inherited from + classes. + </para> + + <para> + As an example, consider the following: + <literallayout class='monospaced'> + do_foo() { + bbplain first + fn + } + + fn_prepend() { + bbplain second + } + + fn() { + bbplain third + } + + do_foo_append() { + bbplain fourth + } + </literallayout> + Running <filename>do_foo</filename> + prints the following: + <literallayout class='monospaced'> + recipename do_foo: first + recipename do_foo: second + recipename do_foo: third + recipename do_foo: fourth + </literallayout> + <note> + Overrides and override-style operators can + be applied to any shell function, not just + <link linkend='tasks'>tasks</link>. + </note> + You can use the <filename>bitbake -e</filename> <replaceable>recipename</replaceable> + command to view the final assembled function + after all overrides have been applied. + </para> </section> <section id='bitbake-style-python-functions'> - <title>BitBake Style Python Functions</title> + <title>BitBake-Style Python Functions</title> <para> These functions are written in Python and executed by @@ -905,19 +1173,51 @@ Also in these types of functions, the datastore ("d") is a global variable and is always automatically available. - </para> - - <note> - Variable expressions (e.g. <filename>${X}</filename>) are no - longer expanded within Python functions. - This behavior is intentional in order to allow you to freely - set variable values to expandable expressions without having - them expanded prematurely. - If you do wish to expand a variable within a Python function, - use <filename>d.getVar("X", True)</filename>. - Or, for more complicated expressions, use - <filename>d.expand()</filename>. - </note> + <note> + Variable expressions (e.g. <filename>${X}</filename>) + are no longer expanded within Python functions. + This behavior is intentional in order to allow you + to freely set variable values to expandable expressions + without having them expanded prematurely. + If you do wish to expand a variable within a Python + function, use <filename>d.getVar("X", True)</filename>. + Or, for more complicated expressions, use + <filename>d.expand()</filename>. + </note> + </para> + + <para> + Similar to shell functions, you can also apply overrides + and override-style operators to BitBake-style Python + functions. + </para> + + <para> + As an example, consider the following: + <literallayout class='monospaced'> + python do_foo_prepend() { + bb.plain("first") + } + + python do_foo() { + bb.plain("second") + } + + python do_foo_append() { + bb.plain("third") + } + </literallayout> + Running <filename>do_foo</filename> prints + the following: + <literallayout class='monospaced'> + recipename do_foo: first + recipename do_foo: second + recipename do_foo: third + </literallayout> + You can use the <filename>bitbake -e</filename> <replaceable>recipename</replaceable> + command to view the final assembled function + after all overrides have been applied. + </para> </section> <section id='python-functions'> @@ -961,36 +1261,178 @@ </para> </section> + <section id='bitbake-style-python-functions-versus-python-functions'> + <title>Bitbake-Style Python Functions Versus Python Functions</title> + + <para> + Following are some important differences between + BitBake-style Python functions and regular Python + functions defined with "def": + <itemizedlist> + <listitem><para> + Only BitBake-style Python functions can be + <link linkend='tasks'>tasks</link>. + </para></listitem> + <listitem><para> + Overrides and override-style operators can only + be applied to BitBake-style Python functions. + </para></listitem> + <listitem><para> + Only regular Python functions can take arguments + and return values. + </para></listitem> + <listitem><para> + <link linkend='variable-flags'>Variable flags</link> + such as <filename>[dirs]</filename>, + <filename>[cleandirs]</filename>, and + <filename>[lockfiles]</filename> can be used + on BitBake-style Python functions, but not on + regular Python functions. + </para></listitem> + <listitem><para> + BitBake-style Python functions generate a separate + <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/run.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable> + script that is executed to run the function, and also + generate a log file in + <filename>${T}/log.</filename><replaceable>function-name</replaceable><filename>.</filename><replaceable>pid</replaceable> + if they are executed as tasks.</para> + + <para> + Regular Python functions execute "inline" and do not + generate any files in <filename>${T}</filename>. + </para></listitem> + <listitem><para> + Regular Python functions are called with the usual + Python syntax. + BitBake-style Python functions are usually tasks and + are called directly by BitBake, but can also be called + manually from Python code by using the + <filename>bb.build.exec_func()</filename> function. + Here is an example: + <literallayout class='monospaced'> + bb.build.exec_func("my_bitbake_style_function", d) + </literallayout> + <note> + <filename>bb.build.exec_func()</filename> can also + be used to run shell functions from Python code. + If you want to run a shell function before a Python + function within the same task, then you can use a + parent helper Python function that starts by running + the shell function with + <filename>bb.build.exec_func()</filename> and then + runs the Python code. + </note></para> + + <para>To detect errors from functions executed with + <filename>bb.build.exec_func()</filename>, you + can catch the <filename>bb.build.FuncFailed</filename> + exception. + <note> + Functions in metadata (recipes and classes) should + not themselves raise + <filename>bb.build.FuncFailed</filename>. + Rather, <filename>bb.build.FuncFailed</filename> + should be viewed as a general indicator that the + called function failed by raising an exception. + For example, an exception raised by + <filename>bb.fatal()</filename> will be caught inside + <filename>bb.build.exec_func()</filename>, and a + <filename>bb.build.FuncFailed</filename> will be raised + in response. + </note> + </para></listitem> + </itemizedlist> + </para> + + <para> + Due to their simplicity, you should prefer regular Python functions + over BitBake-style Python functions unless you need a feature specific + to BitBake-style Python functions. + Regular Python functions in metadata are a more recent invention than + BitBake-style Python functions, and older code tends to use + <filename>bb.build.exec_func()</filename> more often. + </para> + </section> + <section id='anonymous-python-functions'> <title>Anonymous Python Functions</title> <para> - Sometimes it is useful to run some code during - parsing to set variables or to perform other operations - programmatically. - To do this, you can define an anonymous Python function. - Here is an example that conditionally sets a - variable based on the value of another variable: + Sometimes it is useful to set variables or perform + other operations programmatically during parsing. + To do this, you can define special Python functions, + called anonymous Python functions, that run at the + end of parsing. + For example, the following conditionally sets a variable + based on the value of another variable: <literallayout class='monospaced'> - python __anonymous () { + python () { if d.getVar('SOMEVAR', True) == 'value': d.setVar('ANOTHERVAR', 'value2') } </literallayout> - The "__anonymous" function name is optional, so the - following example is functionally equivalent to the above: + An equivalent way to mark a function as an anonymous + function is to give it the name "__anonymous", rather + than no name. + </para> + + <para> + Anonymous Python functions always run at the end + of parsing, regardless of where they are defined. + If a recipe contains many anonymous functions, they + run in the same order as they are defined within the + recipe. + As an example, consider the following snippet: <literallayout class='monospaced'> python () { - if d.getVar('SOMEVAR', True) == 'value': - d.setVar('ANOTHERVAR', 'value2') + d.setVar('FOO', 'foo 2') + } + + FOO = "foo 1" + + python () { + d.appendVar('BAR', ' bar 2') + } + + BAR = "bar 1" + </literallayout> + The previous example is conceptually equivalent to the + following snippet: + <literallayout class='monospaced'> + FOO = "foo 1" + BAR = "bar 1" + FOO = "foo 2" + BAR += "bar 2" + </literallayout> + <filename>FOO</filename> ends up with the value "foo 2", + and <filename>BAR</filename> with the value "bar 1 bar 2". + Just as in the second snippet, the values set for the + variables within the anonymous functions become available + to tasks, which always run after parsing. + </para> + + <para> + Overrides and override-style operators such as + "<filename>_append</filename>" are applied before + anonymous functions run. + In the following example, <filename>FOO</filename> ends + up with the value "foo from anonymous": + <literallayout class='monospaced'> + FOO = "foo" + FOO_append = " from outside" + + python () { + d.setVar("FOO", "foo from anonymous") } </literallayout> - Because unlike other Python functions anonymous - Python functions are executed during parsing, the - "d" variable within an anonymous Python function represents - the datastore for the entire recipe. - Consequently, you can set variable values here and - those values can be picked up by other functions. + For methods you can use with anonymous Python functions, + see the + "<link linkend='functions-you-can-call-from-within-python'>Functions You Can Call From Within Python</link>" + section. + For a different method to run Python code during parsing, + see the + "<link linkend='inline-python-variable-expansion'>Inline Python Variable Expansion</link>" + section. </para> </section> @@ -1089,37 +1531,29 @@ <title>Tasks</title> <para> - Tasks are BitBake execution units that originate as - functions and make up the steps that BitBake needs to run - for given recipe. - Tasks are only supported in recipe (<filename>.bb</filename> - or <filename>.inc</filename>) and class - (<filename>.bbclass</filename>) files. - By convention, task names begin with the string "do_". - </para> - - <para> - Here is an example of a task that prints out the date: - <literallayout class='monospaced'> - python do_printdate () { - import time - print time.strftime('%Y%m%d', time.gmtime()) - } - addtask printdate after do_fetch before do_build - </literallayout> + Tasks are BitBake execution units that make up the + steps that BitBake can run for a given recipe. + Tasks are only supported in recipes and classes + (i.e. in <filename>.bb</filename> files and files + included or inherited from <filename>.bb</filename> + files). + By convention, tasks have names that start with "do_". </para> <section id='promoting-a-function-to-a-task'> <title>Promoting a Function to a Task</title> <para> - Any function can be promoted to a task by applying the + Tasks are either + <link linkend='shell-functions'>shell functions</link> or + <link linkend='bitbake-style-python-functions'>BitBake-style Python functions</link> + that have been promoted to tasks by using the <filename>addtask</filename> command. - The <filename>addtask</filename> command also describes - inter-task dependencies. - Here is the function from the previous section but with the - <filename>addtask</filename> command promoting it to a task - and defining some dependencies: + The <filename>addtask</filename> command can also + optionally describe dependencies between the + task and other tasks. + Here is an example that shows how to define a task + and declare some dependencies: <literallayout class='monospaced'> python do_printdate () { import time @@ -1127,15 +1561,81 @@ } addtask printdate after do_fetch before do_build </literallayout> - In the example, the function is defined and then promoted - as a task. - The <filename>do_printdate</filename> task becomes a dependency of - the <filename>do_build</filename> task, which is the default - task. - And, the <filename>do_printdate</filename> task is dependent upon - the <filename>do_fetch</filename> task. - Execution of the <filename>do_build</filename> task results - in the <filename>do_printdate</filename> task running first. + The first argument to <filename>addtask</filename> + is the name of the function to promote to + a task. + If the name does not start with "do_", "do_" is + implicitly added, which enforces the convention that + all task names start with "do_". + </para> + + <para> + In the previous example, the + <filename>do_printdate</filename> task becomes a + dependency of the <filename>do_build</filename> + task, which is the default task (i.e. the task run by + the <filename>bitbake</filename> command unless + another task is specified explicitly). + Additionally, the <filename>do_printdate</filename> + task becomes dependent upon the + <filename>do_fetch</filename> task. + Running the <filename>do_build</filename> task + results in the <filename>do_printdate</filename> + task running first. + <note> + If you try out the previous example, you might see that + the <filename>do_printdate</filename> task is only run + the first time you build the recipe with + the <filename>bitbake</filename> command. + This is because BitBake considers the task "up-to-date" + after that initial run. + If you want to force the task to always be rerun for + experimentation purposes, you can make BitBake always + consider the task "out-of-date" by using the + <filename>[</filename><link linkend='variable-flags'><filename>nostamp</filename></link><filename>]</filename> + variable flag, as follows: + <literallayout class='monospaced'> + do_printdate[nostamp] = "1" + </literallayout> + You can also explicitly run the task and provide the + <filename>-f</filename> option as follows: + <literallayout class='monospaced'> + $ bitbake <replaceable>recipe</replaceable> -c printdate -f + </literallayout> + When manually selecting a task to run with the + <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c</filename> <replaceable>task</replaceable> + command, you can omit the "do_" prefix as part of the + task name. + </note> + </para> + + <para> + You might wonder about the practical effects of using + <filename>addtask</filename> without specifying any + dependencies as is done in the following example: + <literallayout class='monospaced'> + addtask printdate + </literallayout> + In this example, assuming dependencies have not been + added through some other means, the only way to run + the task is by explicitly selecting it with + <filename>bitbake</filename> <replaceable>recipe</replaceable> <filename>-c printdate</filename>. + You can use the + <filename>do_listtasks</filename> task to list all tasks + defined in a recipe as shown in the following example: + <literallayout class='monospaced'> + $ bitbake <replaceable>recipe</replaceable> -c listtasks + </literallayout> + For more information on task dependencies, see the + "<link linkend='dependencies'>Dependencies</link>" + section. + </para> + + <para> + See the + "<link linkend='variable-flags'>Variable Flags</link>" + section for information on variable flags you can use with + tasks. </para> </section> @@ -1172,7 +1672,7 @@ <para> If you want dependencies such as these to remain intact, use - the <filename>noexec</filename> varflag to disable the task + the <filename>[noexec]</filename> varflag to disable the task instead of using the <filename>deltask</filename> command to delete it: <literallayout class='monospaced'> @@ -1295,10 +1795,13 @@ Tasks support a number of these flags which control various functionality of the task: <itemizedlist> - <listitem><para><emphasis>cleandirs:</emphasis> - Empty directories that should created before the task runs. + <listitem><para><emphasis><filename>[cleandirs]</filename>:</emphasis> + Empty directories that should be created before the + task runs. + Directories that already exist are removed and recreated + to empty them. </para></listitem> - <listitem><para><emphasis>depends:</emphasis> + <listitem><para><emphasis><filename>[depends]</filename>:</emphasis> Controls inter-task dependencies. See the <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> @@ -1306,7 +1809,7 @@ "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" section for more information. </para></listitem> - <listitem><para><emphasis>deptask:</emphasis> + <listitem><para><emphasis><filename>[deptask]</filename>:</emphasis> Controls task build-time dependencies. See the <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> @@ -1314,12 +1817,13 @@ "<link linkend='build-dependencies'>Build Dependencies</link>" section for more information. </para></listitem> - <listitem><para><emphasis>dirs:</emphasis> + <listitem><para><emphasis><filename>[dirs]</filename>:</emphasis> Directories that should be created before the task runs. - The last directory listed will be used as the work directory - for the task. + Directories that already exist are left as is. + The last directory listed is used as the + current working directory for the task. </para></listitem> - <listitem><para><emphasis>lockfiles:</emphasis> + <listitem><para><emphasis><filename>[lockfiles]</filename>:</emphasis> Specifies one or more lockfiles to lock while the task executes. Only one task may hold a lockfile, and any task that @@ -1328,23 +1832,32 @@ You can use this variable flag to accomplish mutual exclusion. </para></listitem> - <listitem><para><emphasis>noexec:</emphasis> - Marks the tasks as being empty and no execution required. - The <filename>noexec</filename> flag can be used to set up + <listitem><para><emphasis><filename>[noexec]</filename>:</emphasis> + When set to "1", marks the task as being empty, with + no execution required. + You can use the <filename>[noexec]</filename> flag to set up tasks as dependency placeholders, or to disable tasks defined elsewhere that are not needed in a particular recipe. </para></listitem> - <listitem><para><emphasis>nostamp:</emphasis> - Tells BitBake to not generate a stamp file for a task, - which implies the task should always be executed. + <listitem><para><emphasis><filename>[nostamp]</filename>:</emphasis> + When set to "1", tells BitBake to not generate a stamp + file for a task, which implies the task should always + be executed. + <note><title>Caution</title> + Any task that depends (possibly indirectly) on a + <filename>[nostamp]</filename> task will always be + executed as well. + This can cause unnecessary rebuilding if you are + not careful. + </note> </para></listitem> - <listitem><para><emphasis>postfuncs:</emphasis> + <listitem><para><emphasis><filename>[postfuncs]</filename>:</emphasis> List of functions to call after the completion of the task. </para></listitem> - <listitem><para><emphasis>prefuncs:</emphasis> + <listitem><para><emphasis><filename>[prefuncs]</filename>:</emphasis> List of functions to call before the task executes. </para></listitem> - <listitem><para><emphasis>rdepends:</emphasis> + <listitem><para><emphasis><filename>[rdepends]</filename>:</emphasis> Controls inter-task runtime dependencies. See the <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> @@ -1354,7 +1867,7 @@ "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" section for more information. </para></listitem> - <listitem><para><emphasis>rdeptask:</emphasis> + <listitem><para><emphasis><filename>[rdeptask]</filename>:</emphasis> Controls task runtime dependencies. See the <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> @@ -1364,12 +1877,12 @@ "<link linkend='runtime-dependencies'>Runtime Dependencies</link>" section for more information. </para></listitem> - <listitem><para><emphasis>recideptask:</emphasis> + <listitem><para><emphasis><filename>[recideptask]</filename>:</emphasis> When set in conjunction with <filename>recrdeptask</filename>, specifies a task that should be inspected for additional dependencies. </para></listitem> - <listitem><para><emphasis>recrdeptask:</emphasis> + <listitem><para><emphasis><filename>[recrdeptask]</filename>:</emphasis> Controls task recursive runtime dependencies. See the <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> @@ -1379,12 +1892,12 @@ "<link linkend='recursive-dependencies'>Recursive Dependencies</link>" section for more information. </para></listitem> - <listitem><para><emphasis>stamp-extra-info:</emphasis> + <listitem><para><emphasis><filename>[stamp-extra-info]</filename>:</emphasis> Extra stamp information to append to the task's stamp. As an example, OpenEmbedded uses this flag to allow machine-specific tasks. </para></listitem> - <listitem><para><emphasis>umask:</emphasis> + <listitem><para><emphasis><filename>[umask]</filename>:</emphasis> The umask to run the task under. </para></listitem> </itemizedlist> @@ -1397,7 +1910,7 @@ "<link linkend='checksums'>Checksums (Signatures)</link>" section. <itemizedlist> - <listitem><para><emphasis>vardeps:</emphasis> + <listitem><para><emphasis><filename>[vardeps]</filename>:</emphasis> Specifies a space-separated list of additional variables to add to a variable's dependencies for the purposes of calculating its signature. @@ -1406,17 +1919,17 @@ does not allow BitBake to automatically determine that the variable is referred to. </para></listitem> - <listitem><para><emphasis>vardepsexclude:</emphasis> + <listitem><para><emphasis><filename>[vardepsexclude]</filename>:</emphasis> Specifies a space-separated list of variables that should be excluded from a variable's dependencies for the purposes of calculating its signature. </para></listitem> - <listitem><para><emphasis>vardepvalue:</emphasis> + <listitem><para><emphasis><filename>[vardepvalue]</filename>:</emphasis> If set, instructs BitBake to ignore the actual value of the variable and instead use the specified value when calculating the variable's signature. </para></listitem> - <listitem><para><emphasis>vardepvalueexclude:</emphasis> + <listitem><para><emphasis><filename>[vardepvalueexclude]</filename>:</emphasis> Specifies a pipe-separated list of strings to exclude from the variable's value when calculating the variable's signature. @@ -1624,15 +2137,32 @@ <title>Dependencies</title> <para> - To allow for efficient operation given multiple processes - executing in parallel, BitBake handles dependencies at - the task level. - BitBake supports a robust method to handle these dependencies. - </para> + To allow for efficient parallel processing, BitBake handles + dependencies at the task level. + Dependencies can exist both between tasks within a single recipe + and between tasks in different recipes. + Following are examples of each: + <itemizedlist> + <listitem><para>For tasks within a single recipe, a + recipe's <filename>do_configure</filename> + task might need to complete before its + <filename>do_compile</filename> task can run. + </para></listitem> + <listitem><para>For tasks in different recipes, one + recipe's <filename>do_configure</filename> + task might require another recipe's + <filename>do_populate_sysroot</filename> + task to finish first such that the libraries and headers + provided by the other recipe are available. + </para></listitem> + </itemizedlist> + </para> - <para> - This section describes several types of dependency mechanisms. - </para> + <para> + This section describes several ways to declare dependencies. + Remember, even though dependencies are declared in different ways, they + are all simply dependencies between tasks. + </para> <section id='dependencies-internal-to-the-bb-file'> <title>Dependencies Internal to the <filename>.bb</filename> File</title> @@ -1648,11 +2178,49 @@ <literallayout class='monospaced'> addtask printdate after do_fetch before do_build </literallayout> - In this example, the <filename>printdate</filename> task is - depends on the completion of the <filename>do_fetch</filename> + In this example, the <filename>do_printdate</filename> + task depends on the completion of the + <filename>do_fetch</filename> task, and the + <filename>do_build</filename> task depends on the + completion of the <filename>do_printdate</filename> task. - And, the <filename>do_build</filename> depends on the completion - of the <filename>printdate</filename> task. + <note><para> + For a task to run, it must be a direct or indirect + dependency of some other task that is scheduled to + run.</para> + + <para>For illustration, here are some examples: + <itemizedlist> + <listitem><para> + The directive + <filename>addtask mytask before do_configure</filename> + causes <filename>do_mytask</filename> to run before + <filename>do_configure</filename> runs. + Be aware that <filename>do_mytask</filename> still only + runs if its <link linkend='checksums'>input checksum</link> + has changed since the last time it was run. + Changes to the input checksum of + <filename>do_mytask</filename> also indirectly cause + <filename>do_configure</filename> to run. + </para></listitem> + <listitem><para> + The directive + <filename>addtask mytask after do_configure</filename> + by itself never causes <filename>do_mytask</filename> + to run. + <filename>do_mytask</filename> can still be run manually + as follows: + <literallayout class='monospaced'> + $ bitbake <replaceable>recipe</replaceable> -c mytask + </literallayout> + Declaring <filename>do_mytask</filename> as a dependency + of some other task that is scheduled to run also causes + it to run. + Regardless, the task runs after + <filename>do_configure</filename>. + </para></listitem> + </itemizedlist></para> + </note> </para> </section> @@ -1663,7 +2231,8 @@ BitBake uses the <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> variable to manage build time dependencies. - The "deptask" varflag for tasks signifies the task of each + The <filename>[deptask]</filename> varflag for tasks + signifies the task of each item listed in <filename>DEPENDS</filename> that must complete before that task can be executed. Here is an example: @@ -1692,7 +2261,8 @@ packages. Each of those packages can have <filename>RDEPENDS</filename> and <filename>RRECOMMENDS</filename> runtime dependencies. - The "rdeptask" flag for tasks is used to signify the task of each + The <filename>[rdeptask]</filename> flag for tasks is used to + signify the task of each item runtime dependency which must have completed before that task can be executed. <literallayout class='monospaced'> @@ -1708,7 +2278,7 @@ <title>Recursive Dependencies</title> <para> - BitBake uses the "recrdeptask" flag to manage + BitBake uses the <filename>[recrdeptask]</filename> flag to manage recursive task dependencies. BitBake looks through the build-time and runtime dependencies of the current recipe, looks through @@ -1722,6 +2292,21 @@ </para> <para> + The <filename>[recrdeptask]</filename> flag is most commonly + used in high-level + recipes that need to wait for some task to finish "globally". + For example, <filename>image.bbclass</filename> has the following: + <literallayout class='monospaced'> + do_rootfs[recrdeptask] += "do_packagedata" + </literallayout> + This statement says that the <filename>do_packagedata</filename> + task of the current recipe and all recipes reachable + (by way of dependencies) from the + image recipe must run before the <filename>do_rootfs</filename> + task can run. + </para> + + <para> You might want to not only have BitBake look for dependencies of those tasks, but also have BitBake look for build-time and runtime dependencies of the dependent @@ -1738,7 +2323,8 @@ <title>Inter-Task Dependencies</title> <para> - BitBake uses the "depends" flag in a more generic form + BitBake uses the <filename>[depends]</filename> + flag in a more generic form to manage inter-task dependencies. This more generic form allows for inter-dependency checks for specific tasks rather than checks for @@ -1754,109 +2340,158 @@ </para> <para> - The "rdepends" flag works in a similar way but takes targets + The <filename>[rdepends]</filename> flag works in a similar + way but takes targets in the runtime namespace instead of the build-time dependency namespace. </para> </section> </section> - <section id='accessing-datastore-variables-using-python'> - <title>Accessing Datastore Variables Using Python</title> + <section id='functions-you-can-call-from-within-python'> + <title>Functions You Can Call From Within Python</title> <para> - It is often necessary to access variables in the - BitBake datastore using Python functions. - The Bitbake datastore has an API that allows you this - access. - Here is a list of available operations: + BitBake provides many functions you can call from + within Python functions. + This section lists the most commonly used functions, + and mentions where to find others. </para> - <para> - <informaltable frame='none'> - <tgroup cols='2' align='left' colsep='1' rowsep='1'> - <colspec colname='c1' colwidth='1*'/> - <colspec colname='c2' colwidth='1*'/> - <thead> - <row> - <entry align="left"><emphasis>Operation</emphasis></entry> - <entry align="left"><emphasis>Description</emphasis></entry> - </row> - </thead> - <tbody> - <row> - <entry align="left"><filename>d.getVar("X", expand=False)</filename></entry> - <entry align="left">Returns the value of variable "X". - Using "expand=True" expands the value.</entry> - </row> - <row> - <entry align="left"><filename>d.setVar("X", "value")</filename></entry> - <entry align="left">Sets the variable "X" to "value".</entry> - </row> - <row> - <entry align="left"><filename>d.appendVar("X", "value")</filename></entry> - <entry align="left">Adds "value" to the end of the variable "X".</entry> - </row> - <row> - <entry align="left"><filename>d.prependVar("X", "value")</filename></entry> - <entry align="left">Adds "value" to the start of the variable "X".</entry> - </row> - <row> - <entry align="left"><filename>d.delVar("X")</filename></entry> - <entry align="left">Deletes the variable "X" from the datastore.</entry> - </row> - <row> - <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry> - <entry align="left">Renames the variable "X" to "Y".</entry> - </row> - <row> - <entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry> - <entry align="left">Gets then named flag from the variable "X". - Using "expand=True" expands the named flag.</entry> - </row> - <row> - <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry> - <entry align="left">Sets the named flag for variable "X" to "value".</entry> - </row> - <row> - <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry> - <entry align="left">Appends "value" to the named flag on the - variable "X".</entry> - </row> - <row> - <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry> - <entry align="left">Prepends "value" to the named flag on - the variable "X".</entry> - </row> - <row> - <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry> - <entry align="left">Deletes the named flag on the variable - "X" from the datastore.</entry> - </row> - <row> - <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry> - <entry align="left">Sets the flags specified in - the <filename>flagsdict()</filename> parameter. - <filename>setVarFlags</filename> does not clear previous flags. - Think of this operation as <filename>addVarFlags</filename>.</entry> - </row> - <row> - <entry align="left"><filename>d.getVarFlags("X")</filename></entry> - <entry align="left">Returns a <filename>flagsdict</filename> of the flags for - the variable "X".</entry> - </row> - <row> - <entry align="left"><filename>d.delVarFlags("X")</filename></entry> - <entry align="left">Deletes all the flags for the variable "X".</entry> - </row> - <row> - <entry align="left"><filename>d.expand(expression)</filename></entry> - <entry align="left">Expands variable references in the specified string expression.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> + <section id='functions-for-accessing-datastore-variables'> + <title>Functions for Accessing Datastore Variables</title> + + <para> + It is often necessary to access variables in the + BitBake datastore using Python functions. + The Bitbake datastore has an API that allows you this + access. + Here is a list of available operations: + </para> + + <para> + <informaltable frame='none'> + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth='1*'/> + <colspec colname='c2' colwidth='1*'/> + <thead> + <row> + <entry align="left"><emphasis>Operation</emphasis></entry> + <entry align="left"><emphasis>Description</emphasis></entry> + </row> + </thead> + <tbody> + <row> + <entry align="left"><filename>d.getVar("X", expand)</filename></entry> + <entry align="left">Returns the value of variable "X". + Using "expand=True" expands the value. + Returns "None" if the variable "X" does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.setVar("X", "value")</filename></entry> + <entry align="left">Sets the variable "X" to "value".</entry> + </row> + <row> + <entry align="left"><filename>d.appendVar("X", "value")</filename></entry> + <entry align="left">Adds "value" to the end of the variable "X". + Acts like <filename>d.setVar("X", "value")</filename> + if the variable "X" does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.prependVar("X", "value")</filename></entry> + <entry align="left">Adds "value" to the start of the variable "X". + Acts like <filename>d.setVar("X", "value")</filename> + if the variable "X" does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.delVar("X")</filename></entry> + <entry align="left">Deletes the variable "X" from the datastore. + Does nothing if the variable "X" does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.renameVar("X", "Y")</filename></entry> + <entry align="left">Renames the variable "X" to "Y". + Does nothing if the variable "X" does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.getVarFlag("X", flag, expand)</filename></entry> + <entry align="left">Returns the value of variable "X". + Using "expand=True" expands the value. + Returns "None" if either the variable "X" or the named flag + does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.setVarFlag("X", flag, "value")</filename></entry> + <entry align="left">Sets the named flag for variable "X" to "value".</entry> + </row> + <row> + <entry align="left"><filename>d.appendVarFlag("X", flag, "value")</filename></entry> + <entry align="left">Appends "value" to the named flag on the + variable "X". + Acts like <filename>d.setVarFlag("X", flag, "value")</filename> + if the named flag does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.prependVarFlag("X", flag, "value")</filename></entry> + <entry align="left">Prepends "value" to the named flag on + the variable "X". + Acts like <filename>d.setVarFlag("X", flag, "value")</filename> + if the named flag does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry> + <entry align="left">Deletes the named flag on the variable + "X" from the datastore.</entry> + </row> + <row> + <entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry> + <entry align="left">Sets the flags specified in + the <filename>flagsdict()</filename> parameter. + <filename>setVarFlags</filename> does not clear previous flags. + Think of this operation as <filename>addVarFlags</filename>.</entry> + </row> + <row> + <entry align="left"><filename>d.getVarFlags("X")</filename></entry> + <entry align="left">Returns a <filename>flagsdict</filename> + of the flags for the variable "X". + Returns "None" if the variable "X" does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.delVarFlags("X")</filename></entry> + <entry align="left">Deletes all the flags for the variable "X". + Does nothing if the variable "X" does not exist.</entry> + </row> + <row> + <entry align="left"><filename>d.expand(expression)</filename></entry> + <entry align="left">Expands variable references in the specified + string expression. + References to variables that do not exist are left as is. + For example, <filename>d.expand("foo ${X}")</filename> + expands to the literal string "foo ${X}" if the + variable "X" does not exist.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </section> + + <section id='other-functions'> + <title>Other Functions</title> + + <para> + You can find many other functions that can be called + from Python by looking at the source code of the + <filename>bb</filename> module, which is in + <filename>bitbake/lib/bb</filename>. + For example, + <filename>bitbake/lib/bb/utils.py</filename> includes + the commonly used functions + <filename>bb.utils.contains()</filename> and + <filename>bb.utils.mkdirhier()</filename>, which come + with docstrings. + </para> + </section> </section> <section id='task-checksums-and-setscene'> @@ -1897,7 +2532,7 @@ the "setscene" part of the task's execution in order to validate the list of task hashes. </para></listitem> - <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION</filename> + <listitem><para><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> Specifies a function to call that verifies the list of planned task execution before the main task execution happens. |
