diff options
Diffstat (limited to 'import-layers/yocto-poky/bitbake/doc')
6 files changed, 1013 insertions, 235 deletions
diff --git a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml index b1b72e0aa..e4cc422ea 100644 --- a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml +++ b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.xml @@ -596,7 +596,7 @@ "<link linkend='checksums'>Checksums (Signatures)</link>" section for information). It is also possible to append extra metadata to the stamp using - the "stamp-extra-info" task flag. + the <filename>[stamp-extra-info]</filename> task flag. For example, OpenEmbedded uses this flag to make some tasks machine-specific. </para> @@ -653,7 +653,8 @@ </itemizedlist> It is possible to have functions run before and after a task's main function. - This is done using the "prefuncs" and "postfuncs" flags of the task + This is done using the <filename>[prefuncs]</filename> + and <filename>[postfuncs]</filename> flags of the task that lists the functions to run. </para> </section> @@ -827,7 +828,7 @@ itself. The simplest parameter to pass is "none", which causes a set of signature information to be written out into - <filename>STAMP_DIR</filename> + <filename>STAMPS_DIR</filename> corresponding to the targets specified. The other currently available parameter is "printdiff", which causes BitBake to try to establish the closest @@ -915,7 +916,7 @@ <para> Finally, after all the setscene tasks have executed, BitBake calls the function listed in - <link linkend='var-BB_SETSCENE_VERIFY_FUNCTION'><filename>BB_SETSCENE_VERIFY_FUNCTION</filename></link> + <link linkend='var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link> with the list of tasks BitBake thinks has been "covered". The metadata can then ensure that this list is correct and can inform BitBake that it wants specific tasks to be run regardless diff --git a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml index f168cfa68..2a3340b39 100644 --- a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml +++ b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml @@ -670,8 +670,8 @@ The <filename>module</filename> and <filename>vob</filename> options are combined to create the <filename>load</filename> rule in the view config spec. - As an example, consider the <filename>vob</filename> and - <filename>module</filename> values from the + As an example, consider the <filename>vob</filename> and + <filename>module</filename> values from the <filename>SRC_URI</filename> statement at the start of this section. Combining those values results in the following: <literallayout class='monospaced'> @@ -716,6 +716,68 @@ </para> </section> + <section id='perforce-fetcher'> + <title>Perforce Fetcher (<filename>p4://</filename>)</title> + + <para> + This fetcher submodule fetches code from the + <ulink url='https://www.perforce.com/'>Perforce</ulink> + source control system. + The executable used is specified by + <filename>FETCHCMD_p4</filename>, which defaults + to "p4". + The fetcher's temporary working directory is set by + <link linkend='var-P4DIR'><filename>P4DIR</filename></link>, + which defaults to "DL_DIR/p4". + </para> + + <para> + To use this fetcher, make sure your recipe has proper + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>, + <link linkend='var-SRCREV'><filename>SRCREV</filename></link>, and + <link linkend='var-PV'><filename>PV</filename></link> values. + The p4 executable is able to use the config file defined by your + system's <filename>P4CONFIG</filename> environment variable in + order to define the Perforce server URL and port, username, and + password if you do not wish to keep those values in a recipe + itself. + If you choose not to use <filename>P4CONFIG</filename>, + or to explicitly set variables that <filename>P4CONFIG</filename> + can contain, you can specify the <filename>P4PORT</filename> value, + which is the server's URL and port number, and you can + specify a username and password directly in your recipe within + <filename>SRC_URI</filename>. + </para> + + <para> + Here is an example that relies on <filename>P4CONFIG</filename> + to specify the server URL and port, username, and password, and + fetches the Head Revision: + <literallayout class='monospaced'> + SRC_URI = "p4://example-depot/main/source/..." + SRCREV = "${AUTOREV}" + PV = "p4-${SRCPV}" + S = "${WORKDIR}/p4" + </literallayout> + </para> + + <para> + Here is an example that specifies the server URL and port, + username, and password, and fetches a Revision based on a Label: + <literallayout class='monospaced'> + P4PORT = "tcp:p4server.example.net:1666" + SRC_URI = "p4://user:passwd@example-depot/main/source/..." + SRCREV = "release-1.0" + PV = "p4-${SRCPV}" + S = "${WORKDIR}/p4" + </literallayout> + <note> + You should always set <filename>S</filename> + to <filename>"${WORKDIR}/p4"</filename> in your recipe. + </note> + </para> + </section> + <section id='other-fetchers'> <title>Other Fetchers</title> @@ -726,9 +788,6 @@ Bazaar (<filename>bzr://</filename>) </para></listitem> <listitem><para> - Perforce (<filename>p4://</filename>) - </para></listitem> - <listitem><para> Trees using Git Annex (<filename>gitannex://</filename>) </para></listitem> <listitem><para> diff --git a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml index f6d82b4f3..8b7edbff5 100644 --- a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml +++ b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-hello.xml @@ -399,7 +399,7 @@ ERROR: Unable to parse base: ParseError in configuration INHERITs: Could not inh <link linkend='var-BBFILES'>BBFILES</link> += "${LAYERDIR}/*.bb" <link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link> += "mylayer" - <link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR}/" + <link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN_mylayer</link> := "^${LAYERDIR_RE}/" </literallayout> For information on these variables, click the links to go to the definitions in the glossary.</para> diff --git a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml index 7a37edd50..4d58dc456 100644 --- a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml +++ b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.xml @@ -634,6 +634,25 @@ </para> </section> + <section id='executing-a-list-of-task-and-recipe-combinations'> + <title>Executing a List of Task and Recipe Combinations</title> + + <para> + The BitBake command line supports specifying different + tasks for individual targets when you specify multiple + targets. + For example, suppose you had two targets (or recipes) + <filename>myfirstrecipe</filename> and + <filename>mysecondrecipe</filename> and you needed + BitBake to run <filename>taskA</filename> for the first + recipe and <filename>taskB</filename> for the second + recipe: + <literallayout class='monospaced'> + $ bitbake myfirstrecipe:do_taskA mysecondrecipe:do_taskB + </literallayout> + </para> + </section> + <section id='generating-dependency-graphs'> <title>Generating Dependency Graphs</title> 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. diff --git a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml index ae7e4cee8..66d8f844e 100644 --- a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml +++ b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml @@ -52,7 +52,7 @@ <link linkend='var-MIRRORS'>M</link> <!-- <link linkend='var-glossary-n'>N</link> --> <link linkend='var-OVERRIDES'>O</link> - <link linkend='var-PACKAGES'>P</link> + <link linkend='var-P4DIR'>P</link> <!-- <link linkend='var-QMAKE_PROFILES'>Q</link> --> <link linkend='var-RDEPENDS'>R</link> <link linkend='var-SECTION'>S</link> @@ -716,7 +716,7 @@ </glossdef> </glossentry> - <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION'><glossterm>BB_SETSCENE_VERIFY_FUNCTION</glossterm> + <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION2'><glossterm>BB_SETSCENE_VERIFY_FUNCTION2</glossterm> <glossdef> <para> Specifies a function to call that verifies the list of @@ -986,6 +986,29 @@ BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>" </literallayout> + <note> + <para> + Internally, the <filename>BBCLASSEXTEND</filename> + mechanism generates recipe variants by rewriting + variable values and applying overrides such as + <filename>_class-native</filename>. + For example, to generate a native version of a recipe, + a + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + on "foo" is rewritten to a <filename>DEPENDS</filename> + on "foo-native". + </para> + + <para> + Even when using <filename>BBCLASSEXTEND</filename>, the + recipe is only parsed once. + Parsing once adds some limitations. + For example, it is not possible to + include a different file depending on the variant, + since <filename>include</filename> statements are + processed when the recipe is parsed. + </para> + </note> </para> </glossdef> </glossentry> @@ -994,7 +1017,7 @@ <glossdef> <para> Sets the BitBake debug output level to a specific value - as incremented by the <filename>-d</filename> command line + as incremented by the <filename>-D</filename> command line option. <note> You must set this variable in the external environment @@ -1636,6 +1659,17 @@ </glossdef> </glossentry> + <glossentry id='var-LAYERDIR_RE'><glossterm>LAYERDIR_RE</glossterm> + <glossdef> + <para>When used inside the <filename>layer.conf</filename> configuration + file, this variable provides the path of the current layer, + escaped for use in a regular expression + (<link linkend='var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></link>). + This variable is not available outside of <filename>layer.conf</filename> + and references are expanded immediately when parsing of the file completes.</para> + </glossdef> + </glossentry> + <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> <glossdef> <para>Optionally specifies the version of a layer as a single number. @@ -1737,6 +1771,15 @@ <glossdiv id='var-glossary-p'><title>P</title> + <glossentry id='var-P4DIR'><glossterm>P4DIR</glossterm> + <glossdef> + <para> + The directory in which a local copy of a Perforce depot + is stored when it is fetched. + </para> + </glossdef> + </glossentry> + <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm> <glossdef> <para>The list of packages the recipe creates. @@ -1933,6 +1976,27 @@ The <filename>PROVIDES</filename> statement results in the "libav" recipe also being known as "libpostproc". </para> + + <para> + In addition to providing recipes under alternate names, + the <filename>PROVIDES</filename> mechanism is also used + to implement virtual targets. + A virtual target is a name that corresponds to some + particular functionality (e.g. a Linux kernel). + Recipes that provide the functionality in question list the + virtual target in <filename>PROVIDES</filename>. + Recipes that depend on the functionality in question can + include the virtual target in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + to leave the choice of provider open. + </para> + + <para> + Conventionally, virtual targets have names on the form + "virtual/function" (e.g. "virtual/kernel"). + The slash is simply part of the name and has no + syntactical significance. + </para> </glossdef> </glossentry> |
