diff options
Diffstat (limited to 'external/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml')
| -rw-r--r-- | external/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml | 219 |
1 files changed, 150 insertions, 69 deletions
diff --git a/external/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/external/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml index d91f437d..0ca53216 100644 --- a/external/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml +++ b/external/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml @@ -5,7 +5,7 @@ <title>Syntax and Operators</title> <para> - Bitbake files have their own syntax. + BitBake files have their own syntax. The syntax has similarities to several other languages but also has some unique features. This section describes the available syntax and operators @@ -61,6 +61,78 @@ </para> </section> + <section id='modifying-existing-variables'> + <title>Modifying Existing Variables</title> + + <para> + Sometimes you need to modify existing variables. + Following are some cases where you might find you want to + modify an existing variable: + <itemizedlist> + <listitem><para> + Customize a recipe that uses the variable. + </para></listitem> + <listitem><para> + Change a variable's default value used in a + <filename>*.bbclass</filename> file. + </para></listitem> + <listitem><para> + Change the variable in a <filename>*.bbappend</filename> + file to override the variable in the original recipe. + </para></listitem> + <listitem><para> + Change the variable in a configuration file so that the + value overrides an existing configuration. + </para></listitem> + </itemizedlist> + </para> + + <para> + Changing a variable value can sometimes depend on how the + value was originally assigned and also on the desired + intent of the change. + In particular, when you append a value to a variable that + has a default value, the resulting value might not be what + you expect. + In this case, the value you provide might replace the value + rather than append to the default value. + </para> + + <para> + If after you have changed a variable's value and something + unexplained occurs, you can use BitBake to check the actual + value of the suspect variable. + You can make these checks for both configuration and recipe + level changes: + <itemizedlist> + <listitem><para> + For configuration changes, use the following: + <literallayout class='monospaced'> + $ bitbake -e + </literallayout> + This command displays variable values after the + configuration files (i.e. <filename>local.conf</filename>, + <filename>bblayers.conf</filename>, + <filename>bitbake.conf</filename> and so forth) have + been parsed. + <note> + Variables that are exported to the environment are + preceded by the string "export" in the command's + output. + </note> + </para></listitem> + <listitem><para> + For recipe changes, use the following: + <literallayout class='monospaced'> + $ bitbake <replaceable>recipe</replaceable> -e | grep VARIABLE=" + </literallayout> + This command checks to see if the variable actually + makes it into a specific recipe. + </para></listitem> + </itemizedlist> + </para> + </section> + <section id='line-joining'> <title>Line Joining</title> @@ -222,17 +294,20 @@ rather than when the variable is actually used: <literallayout class='monospaced'> T = "123" - A := "${B} ${A} test ${T}" + A := "test ${T}" T = "456" - B = "${T} bval" + B := "${T} ${C}" C = "cval" C := "${C}append" </literallayout> In this example, <filename>A</filename> contains - "test 123" because <filename>${B}</filename> and - <filename>${A}</filename> at the time of parsing are undefined, - which leaves "test 123". - And, the variable <filename>C</filename> + "test 123", even though the final value of <filename>T</filename> + is "456". + The variable <filename>B</filename> will end up containing "456 cvalappend". + This is because references to undefined variables are preserved as is + during (immediate)expansion. This is in contrast to GNU Make, where undefined + variables expand to nothing. + The variable <filename>C</filename> contains "cvalappend" since <filename>${C}</filename> immediately expands to "cval". </para> @@ -297,9 +372,8 @@ <para> These operators differ from the ":=", ".=", "=.", "+=", and "=+" - operators in that their effects are deferred - until after parsing completes rather than being immediately - applied. + operators in that their effects are applied at variable + expansion time rather than being immediately applied. Here are some examples: <literallayout class='monospaced'> B = "bval" @@ -348,18 +422,22 @@ FOO = "123 456 789 123456 123 456 123 456" FOO_remove = "123" FOO_remove = "456" - FOO2 = "abc def ghi abcdef abc def abc def" - FOO2_remove = "abc def" + FOO2 = " abc def ghi abcdef abc def abc def def" + FOO2_remove = " \ + def \ + abc \ + ghi \ + " </literallayout> The variable <filename>FOO</filename> becomes - " 789 123456 " + " 789 123456 " and <filename>FOO2</filename> becomes - " ghi abcdef ". + " abcdef ". </para> <para> Like "_append" and "_prepend", "_remove" - is deferred until after parsing completes. + is applied at variable expansion time. </para> </section> @@ -595,7 +673,7 @@ <para> BitBake uses - <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> to control what variables are overridden after BitBake parses recipes and configuration files. This section describes how you can use @@ -705,7 +783,7 @@ <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> + <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> for the local datastore of the <filename>do_compile</filename> task.</para> @@ -724,17 +802,15 @@ <title>Key Expansion</title> <para> - Key expansion happens when the BitBake datastore is finalized - just before BitBake expands overrides. + Key expansion happens when the BitBake datastore is finalized. To better understand this, consider the following example: <literallayout class='monospaced'> A${B} = "X" B = "2" A2 = "Y" </literallayout> - In this case, after all the parsing is complete, and - before any overrides are handled, BitBake expands - <filename>${B}</filename> into "2". + In this case, after all the parsing is complete, + BitBake expands <filename>${B}</filename> into "2". This expansion causes <filename>A2</filename>, which was set to "Y" before the expansion, to become "X". </para> @@ -868,7 +944,7 @@ <para> BitBake uses the - <link linkend='var-BBPATH'><filename>BBPATH</filename></link> + <link linkend='var-bb-BBPATH'><filename>BBPATH</filename></link> variable to locate needed include and class files. Additionally, BitBake searches the current directory for <filename>include</filename> and <filename>require</filename> @@ -1086,7 +1162,7 @@ <para> When creating a configuration file (<filename>.conf</filename>), you can use the - <link linkend='var-INHERIT'><filename>INHERIT</filename></link> + <link linkend='var-bb-INHERIT'><filename>INHERIT</filename></link> configuration directive to inherit a class. BitBake only supports this directive when used within a configuration file. @@ -1341,7 +1417,7 @@ </section> <section id='bitbake-style-python-functions-versus-python-functions'> - <title>Bitbake-Style Python Functions Versus Python Functions</title> + <title>BitBake-Style Python Functions Versus Python Functions</title> <para> Following are some important differences between @@ -1370,7 +1446,7 @@ </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> + <filename>${</filename><link linkend='var-bb-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> @@ -1773,7 +1849,7 @@ things exported or listed in its whitelist to ensure that the build environment is reproducible and consistent. You can prevent this "cleaning" by setting the - <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link> + <link linkend='var-bb-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link> variable. </note> Consequently, if you do want something to get passed into the @@ -1783,15 +1859,15 @@ Tell BitBake to load what you want from the environment into the datastore. You can do so through the - <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link> + <link linkend='var-bb-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link> and - <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link> + <link linkend='var-bb-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link> variables. For example, assume you want to prevent the build system from accessing your <filename>$HOME/.ccache</filename> directory. The following command "whitelists" the environment variable - <filename>CCACHE_DIR</filename> causing BitBack to allow that + <filename>CCACHE_DIR</filename> causing BitBake to allow that variable into the datastore: <literallayout class='monospaced'> export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR" @@ -1822,9 +1898,9 @@ <para> Sometimes, it is useful to be able to obtain information from the original execution environment. - Bitbake saves a copy of the original environment into + BitBake saves a copy of the original environment into a special variable named - <link linkend='var-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>. + <link linkend='var-bb-BB_ORIGENV'><filename>BB_ORIGENV</filename></link>. </para> <para> @@ -1883,7 +1959,7 @@ <listitem><para><emphasis><filename>[depends]</filename>:</emphasis> Controls inter-task dependencies. See the - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> variable and the "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" section for more information. @@ -1891,7 +1967,7 @@ <listitem><para><emphasis><filename>[deptask]</filename>:</emphasis> Controls task build-time dependencies. See the - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> variable and the "<link linkend='build-dependencies'>Build Dependencies</link>" section for more information. @@ -1937,7 +2013,7 @@ of cores but certain tasks need to be rate-limited due to various kinds of resource constraints (e.g. to avoid network throttling). <filename>number_threads</filename> works similarly to the - <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> + <link linkend='var-bb-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> variable but is task-specific.</para> <para>Set the value globally. @@ -1971,9 +2047,9 @@ <listitem><para><emphasis><filename>[rdepends]</filename>:</emphasis> Controls inter-task runtime dependencies. See the - <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> variable, the - <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> + <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> variable, and the "<link linkend='inter-task-dependencies'>Inter-Task Dependencies</link>" section for more information. @@ -1981,9 +2057,9 @@ <listitem><para><emphasis><filename>[rdeptask]</filename>:</emphasis> Controls task runtime dependencies. See the - <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> variable, the - <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> + <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> variable, and the "<link linkend='runtime-dependencies'>Runtime Dependencies</link>" section for more information. @@ -1996,9 +2072,9 @@ <listitem><para><emphasis><filename>[recrdeptask]</filename>:</emphasis> Controls task recursive runtime dependencies. See the - <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link> variable, the - <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> + <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> variable, and the "<link linkend='recursive-dependencies'>Recursive Dependencies</link>" section for more information. @@ -2127,7 +2203,7 @@ Any given datastore only has one such event executed against it, however. If - <link linkende='var-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link> + <link linkende='var-bb-BB_INVALIDCONF'><filename>BB_INVALIDCONF</filename></link> is set in the datastore by the event handler, the configuration is reparsed and a new event triggered, allowing the metadata to update configuration. @@ -2256,17 +2332,17 @@ from a single recipe file multiple incarnations of that recipe file where all incarnations are buildable. These features are enabled through the - <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> + <link linkend='var-bb-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> and - <link linkend='var-BBVERSIONS'><filename>BBVERSIONS</filename></link> + <link linkend='var-bb-BBVERSIONS'><filename>BBVERSIONS</filename></link> variables. <note> The mechanism for this class extension is extremely specific to the implementation. Usually, the recipe's - <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>, - <link linkend='var-PN'><filename>PN</filename></link>, and - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + <link linkend='var-bb-PROVIDES'><filename>PROVIDES</filename></link>, + <link linkend='var-bb-PN'><filename>PN</filename></link>, and + <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> variables would need to be modified by the extension class. For specific examples, see the OE-Core <filename>native</filename>, <filename>nativesdk</filename>, @@ -2287,7 +2363,7 @@ project from a single recipe file. You can also specify conditional metadata (using the - <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + <link linkend='var-bb-OVERRIDES'><filename>OVERRIDES</filename></link> mechanism) for a single version, or an optionally named range of versions. Here is an example: <literallayout class='monospaced'> @@ -2306,7 +2382,7 @@ into overrides, but it is also made available for the metadata to use in the variable that defines the base recipe versions for use in <filename>file://</filename> search paths - (<link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>). + (<link linkend='var-bb-FILESPATH'><filename>FILESPATH</filename></link>). </para></listitem> </itemizedlist> </para> @@ -2408,7 +2484,7 @@ <para> BitBake uses the - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + <link linkend='var-bb-DEPENDS'><filename>DEPENDS</filename></link> variable to manage build time dependencies. The <filename>[deptask]</filename> varflag for tasks signifies the task of each @@ -2429,9 +2505,9 @@ <para> BitBake uses the - <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>, - <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, and - <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> + <link linkend='var-bb-PACKAGES'><filename>PACKAGES</filename></link>, + <link linkend='var-bb-RDEPENDS'><filename>RDEPENDS</filename></link>, and + <link linkend='var-bb-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> variables to manage runtime dependencies. </para> @@ -2450,6 +2526,9 @@ In the previous example, the <filename>do_packagedata</filename> task of each item in <filename>RDEPENDS</filename> must have completed before <filename>do_package_qa</filename> can execute. + Although <filename>RDEPENDS</filename> contains entries from the + runtime dependency namespace, BitBake knows how to map them back + to the build-time dependency namespace, in which the tasks are defined. </para> </section> @@ -2486,15 +2565,17 @@ </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 - tasks as well. - If that is the case, you need to reference the task name - itself in the task list: + BitBake allows a task to recursively depend on itself by + referencing itself in the task list: <literallayout class='monospaced'> do_a[recrdeptask] = "do_a do_b" </literallayout> + In the same way as before, this means that the <filename>do_a</filename> + and <filename>do_b</filename> tasks of the current recipe and all + recipes reachable (by way of dependencies) from the recipe + must run before the <filename>do_a</filename> task can run. In this + case BitBake will ignore the current recipe's <filename>do_a</filename> + task circular dependency on itself. </para> </section> @@ -2543,7 +2624,7 @@ <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 + The BitBake datastore has an API that allows you this access. Here is a list of available operations: </para> @@ -2686,7 +2767,7 @@ <para> These checksums are stored in - <link linkend='var-STAMP'><filename>STAMP</filename></link>. + <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>. You can examine the checksums using the following BitBake command: <literallayout class='monospaced'> $ bitbake-dumpsigs @@ -2708,44 +2789,44 @@ The following list describes related variables: <itemizedlist> <listitem><para> - <link linkend='var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>: + <link linkend='var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></link>: Specifies the name of the function to call during the "setscene" part of the task's execution in order to validate the list of task hashes. </para></listitem> <listitem><para> - <link linkend='var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>: + <link linkend='var-bb-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></link>: Specifies a function BitBake calls that determines whether BitBake requires a setscene dependency to be met. </para></listitem> <listitem><para> - <link linkend='var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link>: + <link linkend='var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></link>: Specifies a function to call that verifies the list of planned task execution before the main task execution happens. </para></listitem> <listitem><para> - <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>: + <link linkend='var-bb-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>: Defines the mode for comparing timestamps of stamp files. </para></listitem> <listitem><para> - <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>: + <link linkend='var-bb-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>: Lists stamp files that are looked at when the stamp policy is "whitelist". </para></listitem> <listitem><para> - <link linkend='var-BB_TASKHASH'><filename>BB_TASKHASH</filename></link>: + <link linkend='var-bb-BB_TASKHASH'><filename>BB_TASKHASH</filename></link>: Within an executing task, this variable holds the hash of the task as returned by the currently enabled signature generator. </para></listitem> <listitem><para> - <link linkend='var-STAMP'><filename>STAMP</filename></link>: + <link linkend='var-bb-STAMP'><filename>STAMP</filename></link>: The base path to create stamp files. </para></listitem> <listitem><para> - <link linkend='var-STAMPCLEAN'><filename>STAMPCLEAN</filename></link>: + <link linkend='var-bb-STAMPCLEAN'><filename>STAMPCLEAN</filename></link>: Again, the base path to create stamp files but can use wildcards for matching a range of files for clean operations. </para></listitem> |