diff options
author | Bill Traynor <wmat@alphatroop.com> | 2013-02-26 15:34:19 -0500 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-13 22:00:26 +0000 |
commit | a86f5837fe6d9537ba61c02d6252fb21e99b0864 (patch) | |
tree | e8327818c9fc346fda77978cff4f6522efbde1d4 | |
parent | 5786230823d8ad85a9c626c8ce6cbeec91cf6060 (diff) | |
download | bitbake-a86f5837fe6d9537ba61c02d6252fb21e99b0864.tar.gz |
user-manual-metadata.xml: Integration of feedback on first draft.
Began integration of feedback as well as reformatting.
Signed-off-by: Bill Traynor <wmat@alphatroop.com>
-rw-r--r-- | doc/user-manual/user-manual-metadata.xml | 1147 |
1 files changed, 648 insertions, 499 deletions
diff --git a/doc/user-manual/user-manual-metadata.xml b/doc/user-manual/user-manual-metadata.xml index d339b9e07..a7b23c06c 100644 --- a/doc/user-manual/user-manual-metadata.xml +++ b/doc/user-manual/user-manual-metadata.xml @@ -30,39 +30,41 @@ </listitem> <listitem> <para> - <emphasis>Configuration Data:</emphasis>Defines - machine-specific settings, policy decisions, etc. - Configuration data acts as the glue to bind everything - together.</para> + <emphasis>Configuration Data:</emphasis>Defines + machine-specific settings, policy decisions, etc. + Configuration data acts as the glue to bind everything + together. + </para> </listitem> </itemizedlist> - <para>What follows are a large number of examples of BitBake - metadata. Any syntax which isn't supported in any of the - aforementioned areas will be documented as such.</para> + <para>What follows are a large number of examples of BitBake metadata. + Any syntax which isn't supported in any of the aforementioned areas + will be documented as such. + </para> <section> <title>Basic variable setting</title> <para> <screen> - <varname>VARIABLE</varname>= "value"</screen> + <varname>VARIABLE</varname> = "value"</screen> </para> <para>In this example, - <varname>VARIABLE</varname>is + <varname>VARIABLE</varname> is <literal>value</literal>.</para> </section> <section> <title>Variable expansion</title> - <para>BitBake supports variables referencing one another's - contents using a syntax which is similar to shell - scripting</para> + <para>BitBake supports variables referencing one another's contents using + a syntax which is similar to shell scripting: + </para> <para> <screen> - <varname>A</varname>= "aval" - <varname>B</varname>= "pre${A}post"</screen> + <varname>A</varname> = "aval" + <varname>B</varname> = "pre${A}post"</screen> </para> <para>This results in - <varname>A</varname>containing - <literal>aval</literal>and - <varname>B</varname>containing + <varname>A</varname> containing + <literal>aval</literal> and + <varname>B</varname> containing <literal>preavalpost</literal>.</para> </section> <section> @@ -72,10 +74,10 @@ <varname>A</varname>?= "aval"</screen> </para> <para>If - <varname>A</varname>is set before the above is called, it + <varname>A</varname> is set before the above is called, it will retain its previous value. If - <varname>A</varname>is unset prior to the above call, - <varname>A</varname>will be set to + <varname>A</varname> is unset prior to the above call, + <varname>A</varname> will be set to <literal>aval</literal>. Note that this assignment is immediate, so if there are multiple ?= assignments to a single variable, the first of those will be used.</para> @@ -88,72 +90,90 @@ <varname>A</varname>??= "someothervalue"</screen> </para> <para>If - <varname>A</varname>is set before the above, it will retain - that value. If - <varname>A</varname>is unset prior to the above, - <varname>A</varname>will be set to - <literal>someothervalue</literal>. This is a lazy/weak - assignment in that the assignment does not occur until the - end of the parsing process, so that the last, rather than the - first, ??= assignment to a given variable will be used. Any - other setting of A using = or ?= will however override the - value set with ??=</para> + <varname>A</varname> + is set before the above, it will retain that value. + If + <varname>A</varname> + is unset prior to the above, + <varname>A</varname> + will be set to <literal>someothervalue</literal>. + This is a lazy/weak assignment in that the assignment does not + occur until the end of the parsing process, so that the last, + rather than the first, ??= assignment to a given variable will + be used. + Any other setting of A using = or ?= will however override the + value set with ??=. + </para> </section> <section> <title>Immediate variable expansion (:=)</title> - <para>:= results in a variable's contents being expanded - immediately, rather than when the variable is actually - used.</para> + <para>:= results in a variable's contents being expanded immediately, + rather than when the variable is actually used. + </para> + <para> <screen> - <varname>T</varname>= "123" + <varname>T</varname> = "123" <varname>A</varname>:= "${B} ${A} test ${T}" - <varname>T</varname>= "456" - <varname>B</varname>= "${T} bval" - <varname>C</varname>= "cval" + <varname>T</varname> = "456" + <varname>B</varname> = "${T} bval" + <varname>C</varname> = "cval" <varname>C</varname>:= "${C}append"</screen> </para> - <para>In that example, - <varname>A</varname>would contain - <literal>test 123</literal>, - <varname>B</varname>would contain - <literal>456 bval</literal>, and - <varname>C</varname>would be - <literal>cvalappend</literal>.</para> + <para>In this example, + <varname>A</varname> + would contain + <literal>test 123</literal>, + <varname>B</varname> + would contain + <literal>456 bval</literal>, and + <varname>C</varname> + would be + <literal>cvalappend</literal>. + </para> </section> <section> <title>Appending (+=) and prepending (=+)</title> <para> <screen> - <varname>B</varname>= "bval" + <varname>B</varname> = "bval" <varname>B</varname>+= "additionaldata" - <varname>C</varname>= "cval" + <varname>C</varname> = "cval" <varname>C</varname>=+ "test"</screen> </para> <para>In this example, - <varname>B</varname>is now - <literal>bval additionaldata</literal>and - <varname>C</varname>is - <literal>test cval</literal>.</para> + <varname>B</varname> + is now + <literal>bval additionaldata</literal> + and + <varname>C</varname> + is + <literal>test cval</literal>. + </para> </section> <section> - <title>Appending (.=) and prepending (=.) without - spaces</title> - <para> - <screen> - <varname>B</varname>= "bval" - <varname>B</varname>.= "additionaldata" - <varname>C</varname>= "cval" - <varname>C</varname>=. "test"</screen> - </para> - <para>In this example, - <varname>B</varname>is now - <literal>bvaladditionaldata</literal>and - <varname>C</varname>is - <literal>testcval</literal>. In contrast to the above - appending and prepending operators, no additional space will - be introduced.</para> + <title>Appending (.=) and prepending (=.) without spaces</title> + <para> + <screen> + <varname>B</varname> = "bval" + <varname>B</varname>.= "additionaldata" + <varname>C</varname> = "cval" + <varname>C</varname>=. "test" + </screen> + </para> + <para>In this example, + <varname>B</varname> + is now + <literal>bvaladditionaldata</literal> + and + <varname>C</varname> + is + <literal>testcval</literal>. + In contrast to the above appending and prepending operators, + no additional space will be introduced. + </para> </section> + <section> <title>Appending and Prepending (override style syntax)</title> <para><screen><varname>B</varname> = "bval" @@ -172,449 +192,578 @@ yourself.</para> <varname>FOO_remove</varname> = "456"</screen></para> <para>In this example, <varname>FOO</varname> is now <literal>789 123456</literal>.</para> </section> + <section> - <title>Conditional metadata set</title> - <para>OVERRIDES is a - <quote>:</quote>separated variable containing each item you - want to satisfy conditions. So, if you have a variable which - is conditional on - <quote>arm</quote>, and - <quote>arm</quote>is in OVERRIDES, then the - <quote>arm</quote>specific version of the variable is used - rather than the non-conditional version. Example:</para> - <para> - <screen> - <varname>OVERRIDES</varname>= "architecture:os:machine" - <varname>TEST</varname>= "defaultvalue" - <varname>TEST_os</varname>= "osspecificvalue" - <varname>TEST_condnotinoverrides</varname>= - "othercondvalue"</screen> + <title>Conditional metadata set</title> + <para>OVERRIDES is a + <quote>:</quote> + separated variable containing each item you want to satisfy + conditions. + So, if you have a variable that is conditional on + <quote>arm</quote>, and + <quote>arm</quote> + is in OVERRIDES, then the + <quote>arm</quote> + specific version of the variable is used rather than the + non-conditional version. + Example: + </para> + <para> + <screen> + <varname>OVERRIDES</varname> + = "architecture:os:machine" + <varname>TEST</varname> + = "defaultvalue" + <varname>TEST_os</varname> + = "osspecificvalue" + <varname>TEST_condnotinoverrides</varname> + = "othercondvalue" + </screen> </para> <para>In this example, - <varname>TEST</varname>would be - <literal>osspecificvalue</literal>, due to the condition - <quote>os</quote>being in - <varname>OVERRIDES</varname>.</para> - </section> - <section> - <title>Conditional appending</title> - <para>BitBake also supports appending and prepending to - variables based on whether something is in OVERRIDES. - Example:</para> - <para> - <screen> - <varname>DEPENDS</varname>= "glibc ncurses" - <varname>OVERRIDES</varname>= "machine:local" - <varname>DEPENDS_append_machine</varname>= " - libmad"</screen> - </para> - <para>In this example, - <varname>DEPENDS</varname>is set to - <literal>glibc ncurses libmad</literal>.</para> - </section> - <section> - <title>Inclusion</title> - <para>Next, there is the - <literal>include</literal>directive, which causes BitBake to - parse whatever file you specify, and insert it at that - location, which is not unlike - <command>make</command>. However, if the path specified on - the - <literal>include</literal>line is a relative path, BitBake - will locate the first one it can find within - <envar>BBPATH</envar>.</para> - </section> - <section> - <title>Requiring inclusion</title> - <para>In contrast to the - <literal>include</literal>directive, - <literal>require</literal>will raise an ParseError if the - file to be included cannot be found. Otherwise it will behave - just like the - <literal>include</literal>directive.</para> - </section> - <section> - <title>Python variable expansion</title> - <para> - <screen> - <varname>DATE</varname>= - "${@time.strftime('%Y%m%d',time.gmtime())}"</screen> + <varname>TEST</varname> + would be <literal>osspecificvalue</literal>, + due to the condition + <quote>os</quote> being in + <varname>OVERRIDES</varname>. </para> - <para>This would result in the - <varname>DATE</varname>variable containing today's - date.</para> </section> + <section> - <title>Defining executable metadata</title> - <para> - <emphasis>NOTE:</emphasis>This is only supported in .bb and - .bbclass files.</para> - <para> - <screen>do_mytask () { echo "Hello, world!" }</screen> - </para> - <para>This is essentially identical to setting a variable, - except that this variable happens to be executable shell - code.</para> - <para> - <screen>python do_printdate () { import time print - time.strftime('%Y%m%d', time.gmtime()) }</screen> - </para> - <para>This is the similar to the previous, but flags it as - Python so that BitBake knows it is Python code.</para> - </section> - <section> - <title>Defining Python functions into the global Python - namespace</title> - <para> - <emphasis>NOTE:</emphasis>This is only supported in .bb and - .bbclass files.</para> - <para> - <screen>def get_depends(bb, d): if - d.getVar('SOMECONDITION', True): return - "dependencywithcond" else: return "dependency" - <varname>SOMECONDITION</varname>= "1" - <varname>DEPENDS</varname>= "${@get_depends(bb, - d)}"</screen> - </para> - <para>This would result in - <varname>DEPENDS</varname>containing - <literal>dependencywithcond</literal>.</para> - </section> - <section> - <title>Variable flags</title> - <para>Variables can have associated flags which provide a way - of tagging extra information onto a variable. Several flags - are used internally by BitBake but they can be used - externally too if needed. The standard operations mentioned - above also work on flags.</para> - <para> - <screen> - <varname>VARIABLE</varname>[ - <varname>SOMEFLAG</varname>] = "value"</screen> - </para> - <para>In this example, - <varname>VARIABLE</varname>has a flag, - <varname>SOMEFLAG</varname>which is set to - <literal>value</literal>.</para> - </section> - <section> - <title>Inheritance</title> - <para> - <emphasis>NOTE:</emphasis>This is only supported in .bb and - .bbclass files.</para> - <para>The - <literal>inherit</literal>directive is a means of specifying - what classes of functionality your .bb requires. It is a - rudimentary form of inheritance. For example, you can easily - abstract out the tasks involved in building a package that - uses autoconf and automake, and put that into a bbclass for - your packages to make use of. A given bbclass is located by - searching for classes/filename.bbclass in - <envar>BBPATH</envar>, where filename is what you - inherited.</para> - </section> - <section> - <title>Tasks</title> - <para> - <emphasis>NOTE:</emphasis>This is only supported in .bb and - .bbclass files.</para> - <para>In BitBake, each step that needs to be run for a given - .bb is known as a task. There is a command - <literal>addtask</literal>to add new tasks (must be a defined - Python executable metadata and must start with - <quote>do_</quote>) and describe intertask - dependencies.</para> - <para> - <screen>python do_printdate () { import time print - time.strftime('%Y%m%d', time.gmtime()) } addtask printdate - before do_build</screen> - </para> - <para>This defines the necessary Python function and adds it - as a task which is now a dependency of do_build, the default - task. If anyone executes the do_build task, that will result - in do_printdate being run first.</para> - </section> - <section> - <title>Task Flags</title> - <para>Tasks support a number of flags which control various - functionality of the task. These are as follows:</para> - <para>'dirs' - directories which should be created before the - task runs</para> - <para>'cleandirs' - directories which should created before - the task runs but should be empty</para> - <para>'noexec' - marks the tasks as being empty and no - execution required. These are used as dependency placeholders - or used when added tasks need to be subsequently - disabled.</para> - <para>'nostamp' - don't generate a stamp file for a task. - This means the task is always rexecuted.</para> - <para>'fakeroot' - this task needs to be run in a fakeroot - environment, obtained by adding the variables in FAKEROOTENV - to the environment.</para> - <para>'umask' - the umask to run the task under.</para> - <para>For the 'deptask', 'rdeptask', 'depends', 'rdepends' - and 'recrdeptask' flags please see the dependencies - section.</para> - </section> - <section> - <title>Events</title> - <para> - <emphasis>NOTE:</emphasis>This is only supported in .bb and - .bbclass files.</para> - <para>BitBake allows installation of event handlers. Events - are triggered at certain points during operation, such as the - beginning of operation against a given .bb, the start of a - given task, task failure, task success, et cetera. The intent - is to make it easy to do things like email notification on - build failure.</para> - <para> - <screen>addhandler myclass_eventhandler python - myclass_eventhandler() { from bb.event import getName from - bb import data print("The name of the Event is %s" % - getName(e)) print("The file we run for is %s" % - data.getVar('FILE', e.data, True)) }</screen> - </para> - <para>This event handler gets called every time an event is - triggered. A global variable - <varname>e</varname>is defined. - <varname>e</varname>.data contains an instance of bb.data. - With the getName( - <varname>e</varname>) method one can get the name of the - triggered event.</para> - <para>The above event handler prints the name of the event - and the content of the - <varname>FILE</varname>variable.</para> - </section> - <section> - <title>Variants</title> - <para>Two BitBake features exist to facilitate the creation - of multiple buildable incarnations from a single recipe - file.</para> - <para>The first is - <varname>BBCLASSEXTEND</varname>. This variable is a space - separated list of classes used to "extend" the recipe for - each variant. As an example, setting - <screen>BBCLASSEXTEND = "native"</screen>results in a second - incarnation of the current recipe being available. This - second incarnation will have the "native" class - inherited.</para> - <para>The second feature is - <varname>BBVERSIONS</varname>. This variable allows a single - recipe to build multiple versions of a project from a single - recipe file, and allows you to specify conditional metadata - (using the - <varname>OVERRIDES</varname>mechanism) for a single version, - or an optionally named range of versions:</para> - <para> - <screen>BBVERSIONS = "1.0 2.0 git" SRC_URI_git = - "git://someurl/somepath.git"</screen> - </para> - <para> - <screen>BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+" - SRC_URI_append_1.0.7+ = - "file://some_patch_which_the_new_versions_need.patch;patch=1"</screen> - </para> - <para>Note that the name of the range will default to the - original version of the recipe, so given OE, a recipe file of - foo_1.0.0+.bb will default the name of its versions to - 1.0.0+. This is useful, as the range name is not only placed - into overrides; it's also made available for the metadata to - use in the form of the - <varname>BPV</varname>variable, for use in file:// search - paths ( - <varname>FILESPATH</varname>).</para> - </section> - <section> - <title>Variable interaction: Worked Examples</title> - <para>Despite the documentation of the different forms of - variable definition above, it can be hard to work out what - happens when variable operators are combined. This section - documents some common questions people have regarding the way - variables interact.</para> - <section> - <title>Override and append ordering</title> - <para>There is often confusion about which order overrides - and the various append operators take effect.</para> - <para> - <screen> - <varname>OVERRIDES</varname>= "foo" - <varname>A_foo_append</varname>= "X"</screen> - </para> - <para>In this case, X is unconditionally appended to the - variable - <varname>A_foo</varname>. Since foo is an override, A_foo - would then replace - <varname>A</varname>.</para> - <para> - <screen> - <varname>OVERRIDES</varname>= "foo" - <varname>A</varname>= "X" - <varname>A_append_foo</varname>= "Y"</screen> - </para> - <para>In this case, only when foo is in OVERRIDES, Y is - appended to the variable - <varname>A</varname>so the value of - <varname>A</varname>would become XY (NB: no spaces are - appended).</para> - <para> - <screen> - <varname>OVERRIDES</varname>= "foo" - <varname>A_foo_append</varname>= "X" - <varname>A_foo_append</varname>+= "Y"</screen> + <title>Conditional appending</title> + <para>BitBake also supports appending and prepending to variables + based on whether something is in OVERRIDES. + Example: + </para> + <para> + <screen> + <varname>DEPENDS</varname> + = "glibc ncurses" + <varname>OVERRIDES</varname> + = "machine:local" + <varname>DEPENDS_append_machine</varname> + = "libmad" + </screen> + </para> + <para>In this example, + <varname>DEPENDS</varname> ' + is set to + <literal>glibc ncurses libmad</literal>. + </para> +</section> +<section> + <title>Inclusion</title> + <para>Next, there is the + <literal>include</literal> directive, that causes BitBake to + parse whatever file you specify, and insert it at that + location, which is not unlike + <command>Make</command>. However, if the path specified on the + <literal>include</literal> + line is a relative path, BitBake will locate the first one it + can find within + <envar>BBPATH</envar>. + </para> +</section> +<section> + <title>Requiring inclusion</title> + <para>In contrast to the + <literal>include</literal> + directive, + <literal>require</literal> + will raise a ParseError if the file to be included cannot be + found. + Otherwise it will behave just like the + <literal>include</literal> + directive. + </para> +</section> +<section> + <title>Python variable expansion</title> + <para> + <screen> + <varname>DATE</varname> = + "${@time.strftime('%Y%m%d',time.gmtime())}" + </screen> + </para> + <para>This would result in the + <varname>DATE</varname> + variable containing today's date. + </para> +</section> +<section> + <title>Defining executable metadata</title> + <para> + <emphasis>NOTE:</emphasis> + This is only supported in .bb and .bbclass files. + </para> + <para> + <screen>do_mytask () { echo "Hello, world!" } + </screen> + </para> + <para>This is essentially identical to setting a variable, except that + this variable happens to be executable shell code. + </para> + <para> + <screen>python do_printdate () { import time print + time.strftime('%Y%m%d', time.gmtime()) } + </screen> + </para> + <para>This is the similar to the previous, but flags it as Python so + that BitBake knows it is Python code. + </para> +</section> +<section> + <title>Defining Python functions into the global Python namespace + </title> + <para> + <emphasis>NOTE:</emphasis> + This is only supported in .bb and .bbclass files. + </para> + <para> + <screen>def get_depends(bb, d): if + d.getVar('SOMECONDITION', True): return + "dependencywithcond" else: return "dependency" + <varname>SOMECONDITION</varname> = "1" + <varname>DEPENDS</varname> = "${@get_depends(bb, + d)}" + </screen> + </para> + <para>This would result in + <varname>DEPENDS</varname> + containing + <literal>dependencywithcond</literal>. + </para> +</section> +<section> + <title>Variable flags</title> + <para>Variables can have associated flags which provide a way of + tagging extra information onto a variable. + Several flags are used internally by BitBake but they can be + used externally too if needed. + The standard operations mentioned above also work on flags. + </para> + <para> + <screen> + <varname>VARIABLE</varname> + [ + <varname>SOMEFLAG</varname> + ] = "value" + </screen> + </para> + <para>In this example, + <varname>VARIABLE</varname> + has a flag, + <varname>SOMEFLAG</varname> + that is set to + <literal>value</literal>. + </para> +</section> +<section> + <title>Inheritance</title> + <para> + <emphasis>NOTE:</emphasis> This is only supported in .bb + and .bbclass files. + </para> + <para>The <literal>inherit</literal> directive is a means of specifying + what classes of functionality your .bb requires. + It is a rudimentary form of inheritance. + For example, you can easily abstract out the tasks involved in + building a package that uses autoconf and automake, and put + that into a bbclass for your packages to make use of. + A given bbclass is located by searching for + classes/filename.bbclass in + <envar>BBPATH</envar>, + where filename is what you inherited. + </para> +</section> +<section> + <title>Tasks</title> + <para> + <emphasis>NOTE:</emphasis> + This is only supported in .bb and .bbclass files. + </para> + <para>In BitBake, each step that needs to be run for a given .bb is + known as a task. + There is a command <literal>addtask</literal> to add new + tasks (must be a defined Python executable metadata and must + start with <quote>do_</quote>) and describe intertask + dependencies. + </para> + <para> + <screen>python do_printdate () { import time print + time.strftime('%Y%m%d', time.gmtime()) } addtask printdate + before do_build + </screen> + </para> + <para>This defines the necessary Python function and adds it as a task + which is now a dependency of do_build, the default task. + If anyone executes the do_build task, that will result in + do_printdate being run first. + </para> +</section> +<section> + <title>Task Flags</title> + <para>Tasks support a number of flags which control various + functionality of the task. + These are as follows: + </para> + <para>'dirs' - directories which should be created before the task + runs + </para> + <para>'cleandirs' - directories which should created before the task + runs but should be empty + </para> + <para>'noexec' - marks the tasks as being empty and no execution + required. + These are used as dependency placeholders or used when added + tasks need to be subsequently disabled. + </para> + <para>'nostamp' - don't generate a stamp file for a task. + This means the task is always executed. + </para> + <para>'fakeroot' - this task needs to be run in a fakeroot + environment, obtained by adding the variables in FAKEROOTENV + to the environment. + </para> + <para>'umask' - the umask to run the task under. + </para> + <para>For the 'deptask', 'rdeptask', 'depends', 'rdepends'and + 'recrdeptask' flags please see the dependencies section. + </para> +</section> +<section> + <title>Events</title> + <para> + <emphasis>NOTE:</emphasis> + This is only supported in .bb and .bbclass files. + </para> + <para>BitBake allows installation of event handlers. + Events are triggered at certain points during operation, such + as the beginning of operation against a given .bb, the start of + a given task, task failure, task success, et cetera. + The intent is to make it easy to do things like email + notification on build failure. + </para> + <para> + <screen>addhandler myclass_eventhandler python + myclass_eventhandler() { from bb.event import getName from + bb import data print("The name of the Event is %s" % + getName(e)) print("The file we run for is %s" % + data.getVar('FILE', e.data, True)) } + </screen> + </para> + <para>This event handler gets called every time an event is triggered. + A global variable + <varname>e</varname> + is defined. + <varname>e</varname>.data + contains an instance of bb.data. + With the getName(<varname>e</varname>) method one can get the + name of the triggered event. + </para> + <para>The above event handler prints the name of the event and the + content of the + <varname>FILE</varname> + variable. + </para> +</section> + +<section> + <title>Variants</title> + <para>Two BitBake features exist to facilitate the creation of multiple + buildable incarnations from a single recipe file. + </para> + <para>The first is + <varname>BBCLASSEXTEND</varname>. + This variable is a space separated list of classes used to + "extend" the recipe for each variant. + As an example, setting + <screen>BBCLASSEXTEND = "native"</screen> + results in a second incarnation of the current recipe being + available. + This second incarnation will have the "native" class + inherited. + </para> + <para>The second feature is + <varname>BBVERSIONS</varname>. + This variable allows a single recipe to build multiple versions + of a project from a single recipe file, and allows you to + specify conditional metadata (using the + <varname>OVERRIDES</varname> mechanism) for a single version, + or an optionally named range of versions: + </para> + <para> + <screen>BBVERSIONS = "1.0 2.0 git" SRC_URI_git = + "git://someurl/somepath.git" + </screen> + </para> + <para> + <screen>BBVERSIONS = "1.0.[0-6]:1.0.0+ \ 1.0.[7-9]:1.0.7+" + SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;patch=1" + </screen> + </para> + <para>Note that the name of the range will default to the original + version of the recipe, so given OE, a recipe file of + foo_1.0.0+.bb will default the name of its versions to + 1.0.0+. + This is useful, as the range name is not only placed into + overrides; it's also made available for the metadata to use in + the form of the + <varname>BPV</varname> + variable, for use in file:// search paths + (<varname>FILESPATH</varname>). + </para> +</section> +<section> + <title>Variable interaction: Worked Examples</title> + <para>Despite the documentation of the different forms of variable + definition above, it can be hard to work out what happens when + variable operators are combined. + This section documents some common questions people have + regarding the way variables interact. + </para> +<section> + <title>Override and append ordering</title> + <para>There is often confusion about which order overrides and the + various append operators take effect. + </para> + <para> + <screen> + <varname>OVERRIDES</varname> + = "foo" + <varname>A_foo_append</varname> + = "X"</screen> + </para> + <para>In this case, X is unconditionally appended to the variable + <varname>A_foo</varname>. + Since foo is an override, A_foo would then replace + <varname>A</varname>.</para> + <para> + <screen> + <varname>OVERRIDES</varname> + = "foo" + <varname>A</varname> + = "X" + <varname>A_append_foo</varname> + = "Y" + </screen> + </para> + <para>In this case, only when foo is in OVERRIDES, Y is appended to the + variable + <varname>A</varname> + so the value of + <varname>A</varname> + would become XY (NB: no spaces are appended). + </para> + <para> + <screen> + <varname>OVERRIDES</varname> + = "foo" + <varname>A_foo_append</varname> + = "X" + <varname>A_foo_append</varname> + += "Y" + </screen> </para> - <para>This behaves as per the first case above, but the - value of - <varname>A</varname>would be "X Y" instead of just - "X".</para> - <para> - <screen> - <varname>A</varname>= "1" - <varname>A_append</varname>= "2" - <varname>A_append</varname>= "3" - <varname>A</varname>+= "4" - <varname>A</varname>.= "5"</screen> + <para>This behaves as per the first case above, but the value of + <varname>A</varname> + would be "X Y" instead of just "X". + </para> + <para> + <screen> + <varname>A</varname> + = "1" + <varname>A_append</varname> + = "2" + <varname>A_append</varname> + = "3" + <varname>A</varname> + += "4" + <varname>A</varname> + .= "5" + </screen> </para> - <para>Would ultimately result in - <varname>A</varname>taking the value "1 4523" since the - _append operator executes at the same time as the expansion - of other overrides.</para> - </section> - <section> - <title>Key Expansion</title> - <para>Key expansion happens at the data store finalisation - time just before overrides are expanded.</para> - <para> - <screen> - <varname>A${B}</varname>= "X" - <varname>B</varname>= "2" - <varname>A2</varname>= "Y"</screen> + <para>Would ultimately result in + <varname>A</varname> + taking the value "1 4523" since the _append operator executes + at the same time as the expansion of other overrides. + </para> +</section> +<section> + <title>Key Expansion</title> + <para>Key expansion happens at the data store finalisation time just + before overrides are expanded. + </para> + <para> + <screen> + <varname>A${B}</varname> + = "X" + <varname>B</varname> + = "2" + <varname>A2</varname> + = "Y" + </screen> + </para> + <para>So in this case + <varname>A2</varname> + would take the value of "X". + </para> +</section> +<section> + <title>Dependency handling</title> + <para>BitBake handles dependencies at the task level since to allow for + efficient operation with multiple processes executing in + parallel, a robust method of specifying task dependencies is + needed. + </para> +</section> + +<section> + <title>Dependencies internal to the .bb file</title> + <para>Where the dependencies are internal to a given .bb file, the + dependencies are handled by the previously detailed addtask + directive. + </para> +</section> + +<section> + <title>Build Dependencies</title> + <para>DEPENDS lists build time dependencies. + The 'deptask' flag for tasks is used to signify the task of + each item listed in DEPENDS which must have completed before + that task can be executed. + </para> + <para> + <screen>do_configure[deptask] = + "do_populate_staging" + </screen> + </para> + + <para>means the do_populate_staging task of each item in DEPENDS must + have completed before do_configure can execute. + </para> +</section> + +<section> + <title>Runtime Dependencies</title> + <para>The PACKAGES variable lists runtime packages and each of these + can have RDEPENDS and RRECOMMENDS runtime dependencies. + The 'rdeptask' flag for tasks is used to signify the task of + each item runtime dependency which must have completed before + that task can be executed. + </para> + <para> + <screen>do_package_write[rdeptask] = + "do_package" + </screen> + </para> + <para>means the do_package task of each item in RDEPENDS must have + completed before do_package_write can execute. + </para> +</section> + +<section> + <title>Recursive Dependencies</title> + <para>These are specified with the 'recrdeptask' flag which is used + to signify the task(s) of dependencies which must have + completed before that task can be executed. + It works by looking though the build and runtime dependencies + of the current recipe as well as any inter-task dependencies + the task has, then adding a dependency on the listed task. + It will then recurse through the dependencies of those tasks + and so on. + </para> + <para>It may be desireable to recurse not just through the dependencies + of those tasks but through the build and runtime dependencies + of dependent tasks too. + If that is the case, the taskname itself should be referenced + in the task list, e.g. do_a[recrdeptask] = "do_a do_b". + </para> +</section> + +<section> + <title>Inter task</title> + <para>The 'depends' flag for tasks is a more generic form which allows + an interdependency on specific tasks rather than specifying + the data in DEPENDS. + </para> + <para> + <screen>do_patch[depends] = + "quilt-native:do_populate_staging" + </screen> </para> - <para>So in this case - <varname>A2</varname>would take the value of "X".</para> - </section> - </section> - <section> - <title>Dependency handling</title> - <para>BitBake handles dependencies at the task level since to - allow for efficient operation with multiple processed - executing in parallel. A robust method of specifying task - dependencies is therefore needed.</para> - <section> - <title>Dependencies internal to the .bb file</title> - <para>Where the dependencies are internal to a given .bb - file, the dependencies are handled by the previously - detailed addtask directive.</para> - </section> - <section> - <title>Build Dependencies</title> - <para>DEPENDS lists build time dependencies. The 'deptask' - flag for tasks is used to signify the task of each item - listed in DEPENDS which must have completed before that - task can be executed.</para> - <para> - <screen>do_configure[deptask] = - "do_populate_staging"</screen> - </para> - <para>means the do_populate_staging task of each item in - DEPENDS must have completed before do_configure can - execute.</para> - </section> - <section> - <title>Runtime Dependencies</title> - <para>The PACKAGES variable lists runtime packages and each - of these can have RDEPENDS and RRECOMMENDS runtime - dependencies. The 'rdeptask' flag for tasks is used to - signify the task of each item runtime dependency which must - have completed before that task can be executed.</para> - <para> - <screen>do_package_write[rdeptask] = - "do_package"</screen> - </para> - <para>means the do_package task of each item in RDEPENDS - must have completed before do_package_write can - execute.</para> - </section> - <section> - <title>Recursive Dependencies</title> - <para>These are specified with the 'recrdeptask' flag which - is used signify the task(s) of dependencies which must have - completed before that task can be executed. It works by - looking though the build and runtime dependencies of the - current recipe as well as any inter-task dependencies the - task has, then adding a dependency on the listed task. It - will then recurse through the dependencies of those tasks - and so on.</para> - <para>It may be desireable to recurse not just through the - dependencies of those tasks but through the build and - runtime dependencies of dependent tasks too. If that is the - case, the taskname itself should be referenced in the task - list, e.g. do_a[recrdeptask] = "do_a do_b".</para> - </section> - <section> - <title>Inter task</title> - <para>The 'depends' flag for tasks is a more generic form - of which allows an interdependency on specific tasks rather - than specifying the data in DEPENDS.</para> - <para> - <screen>do_patch[depends] = - "quilt-native:do_populate_staging"</screen> - </para> - <para>means the do_populate_staging task of the target - quilt-native must have completed before the do_patch can - execute.</para> - <para>The 'rdepends' flag works in a similar way but takes - targets in the runtime namespace instead of the build time - dependency namespace.</para> - </section> - </section> - <section> - <title>Parsing</title> - <section> - <title>Configuration files</title> - <para>The first kind of metadata in BitBake is - configuration metadata. This metadata is global, and - therefore affects - <emphasis>all</emphasis>packages and tasks which are - executed.</para> - <para>BitBake will first search the current working - directory for an optional "conf/bblayers.conf" - configuration file. This file is expected to contain a - BBLAYERS variable which is a space delimited list of - 'layer' directories. For each directory in this list, a - "conf/layer.conf" file will be searched for and parsed with - the LAYERDIR variable being set to the directory where the - layer was found. The idea is these files will setup BBPATH - and other variables correctly for a given build directory - automatically for the user.</para> - <para>BitBake will then expect to find 'conf/bitbake.conf' - somewhere in the user specified - <envar>BBPATH</envar>. That configuration file generally - has include directives to pull in any other metadata - (generally files specific to architecture, machine, - <emphasis>local</emphasis>and so on).</para> - <para>Only variable definitions and include directives are - allowed in .conf files.</para> - </section> - <section> - <title>Classes</title> - <para>BitBake classes are our rudimentary inheritance - mechanism. As briefly mentioned in the metadata - introduction, they're parsed when an - <literal>inherit</literal>directive is encountered, and - they are located in classes/ relative to the directories in - - <envar>BBPATH</envar>.</para> - </section> - <section> + <para>means the do_populate_staging task of the target + quilt-native must have completed before the do_patch can + execute. + </para> + <para>The 'rdepends' flag works in a similar way but takes targets in + the runtime namespace instead of the build time dependency + namespace. + </para> +</section> + +</section> + +<section> + <title>Parsing</title> + <section> + <title>Configuration files</title> + <para>The first kind of metadata in BitBake is configuration + metadata. + This metadata is global, and therefore affects + <emphasis>all</emphasis> + packages and tasks that are executed. + </para> + <para>BitBake will first search the current working directory + for an optional "conf/bblayers.conf" configuration + file. + This file is expected to contain a BBLAYERS variable + that is a space delimited list of 'layer' directories. + For each directory in this list, a "conf/layer.conf" + file will be searched for and parsed with the LAYERDIR + variable being set to the directory where the layer was + found. + The idea is these files will setup BBPATH and other + variables correctly for a given build directory + automatically for the user. + </para> + <para>BitBake will then expect to find 'conf/bitbake.conf' + somewhere in the user specified + <envar>BBPATH</envar>. + That configuration file generally has include + directives to pull in any other metadata (generally + files specific to architecture, machine, + <emphasis>local</emphasis>and so on). + </para> + <para>Only variable definitions and include directives are + allowed in .conf files. + </para> +</section> + +<section> + <title>Classes</title> + <para>BitBake classes are our rudimentary inheritance mechanism. + As briefly mentioned in the metadata introduction, they're + parsed when an + <literal>inherit</literal> + directive is encountered, and they are located in classes/ + relative to the directories in + <envar>BBPATH</envar>. + </para> +</section> + +<section> <title>.bb files</title> - <para>A BitBake (.bb) file is a logical unit of tasks to be - executed. Normally this is a package to be built. Inter-.bb - dependencies are obeyed. The files themselves are located - via the - <varname>BBFILES</varname>variable, which is set to a space - separated list of .bb files, and does handle - wildcards.</para> + <para>A BitBake (.bb) file is a logical unit of tasks to be executed. + Normally this is a package to be built. + Inter-.bb dependencies are obeyed. + The files themselves are located via the + <varname>BBFILES</varname> + variable, which is set to a space separated list of .bb files, + and does handle wildcards. + </para> </section> - </section></para> + </section> + </para> </section> </chapter> |