diff options
author | Bill Traynor <wmat@alphatroop.com> | 2013-04-15 19:02:40 -0400 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-01-13 22:00:27 +0000 |
commit | 09dc2b6d859a55bfe5b60173b68e3499bc0ec70d (patch) | |
tree | a6f6ed88a04707ec038d3a2213a8b55ddd178c24 /doc/user-manual/user-manual-metadata.xml | |
parent | 280df4c4e1535be0c1bdfdc4697e1669f7d24d62 (diff) | |
download | bitbake-09dc2b6d859a55bfe5b60173b68e3499bc0ec70d.tar.gz |
user-manual-metadata: Reorganization of chapter.
Reorganization of the whole chapter into a more reasonable
layout. Addition of various sections to make organization
happen.
Signed-off-by: Bill Traynor <wmat@alphatroop.com>
Diffstat (limited to 'doc/user-manual/user-manual-metadata.xml')
-rw-r--r-- | doc/user-manual/user-manual-metadata.xml | 484 |
1 files changed, 265 insertions, 219 deletions
diff --git a/doc/user-manual/user-manual-metadata.xml b/doc/user-manual/user-manual-metadata.xml index 6f7090852..1ea380354 100644 --- a/doc/user-manual/user-manual-metadata.xml +++ b/doc/user-manual/user-manual-metadata.xml @@ -44,8 +44,9 @@ </para> </section> +<section> <section> - <title>Basic variable setting</title> + <title>Basic Variable Setting</title> <para> <screen> <varname>VARIABLE</varname> = "value"</screen> @@ -56,7 +57,7 @@ </section> <section> - <title>Variable expansion</title> + <title>Variable Expansion</title> <para>BitBake supports variables referencing one another's contents using a syntax which is similar to shell scripting: </para> @@ -73,7 +74,7 @@ </section> <section> - <title>Setting a default value (?=)</title> + <title>Setting a Default Value (?=)</title> <para> <screen> <varname>A</varname>?= "aval"</screen> @@ -89,7 +90,7 @@ </section> <section> - <title>Setting a weak default value (??=)</title> + <title>Setting a Weak Default Value (??=)</title> <para> <screen> <varname>A</varname>??= "somevalue" @@ -113,7 +114,7 @@ </section> <section> - <title>Immediate variable expansion (:=)</title> + <title>Immediate Variable Expansion (:=)</title> <para>:= results in a variable's contents being expanded immediately, rather than when the variable is actually used. </para> @@ -139,9 +140,11 @@ <literal>cvalappend</literal>. </para> </section> - +</section> + + <section> - <title>Appending (+=) and prepending (=+)</title> + <title>Appending (+=) and Prepending (=+)</title> <para> <screen> <varname>B</varname> = "bval" @@ -160,7 +163,7 @@ </para> </section> <section> - <title>Appending (.=) and prepending (=.) without spaces</title> + <title>Appending (.=) and Prepending (=.) without spaces</title> <para> <screen> <varname>B</varname> = "bval" @@ -168,11 +171,10 @@ <varname>C</varname> = "cval" <varname>C</varname>=. "test" </screen> - </para> - <para>In this example, - <varname>B</varname> - is now - <literal>bvaladditionaldata</literal> + </para> + <para>In this example, + <varname>B</varname> is now + <literal>bvaladditionaldata</literal> and <varname>C</varname> is @@ -201,8 +203,50 @@ yourself.</para> <para>In this example, <varname>FOO</varname> is now <literal>789 123456</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>Inline 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>Conditional Syntax (Overrides)</title> + <section> - <title>Conditional metadata set</title> + <title>Conditional Metadata</title> <para>OVERRIDES is a <quote>:</quote> separated variable containing each item you want to satisfy @@ -238,7 +282,7 @@ yourself.</para> </section> <section> - <title>Conditional appending</title> + <title>Conditional Appending</title> <para>BitBake also supports appending and prepending to variables based on whether something is in OVERRIDES. Example: @@ -252,15 +296,135 @@ yourself.</para> <varname>DEPENDS_append_machine</varname> = "libmad" </screen> - </para> - <para>In this example, - <varname>DEPENDS</varname> ' - is set to + </para> + <para>In this example, + <varname>DEPENDS</varname> is set to <literal>glibc ncurses libmad</literal>. </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> + + <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> + <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> + +<section> +<title>Inheritance</title> +<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>Inclusion</title> <para>Next, there is the <literal>include</literal> directive, that causes BitBake to @@ -271,11 +435,12 @@ yourself.</para> line is a relative path, BitBake will locate the first one it can find within <envar>BBPATH</envar>. + FIX ME: This section requires improvement. </para> </section> <section> - <title>Requiring inclusion</title> + <title>Requiring Inclusion</title> <para>In contrast to the <literal>include</literal> directive, @@ -285,25 +450,27 @@ yourself.</para> Otherwise it will behave just like the <literal>include</literal> directive. + FIX ME: This section requires improvement. + </para> </section> <section> - <title>Inline Python variable expansion</title> + <title>INHERIT Configuration Directive</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> - + This configuration directive causes the named class to be inherited at this point during parsing. + This variable is only valid in configuration files. + </para> + + <para>ADD MORE HERE</para> + +</section> +</section> + +<section> + <title>Functions and Tasks</title> <section> - <title>Defining executable metadata</title> + <title>Defining Executable Metadata</title> <para> <emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files. @@ -326,7 +493,7 @@ yourself.</para> </section> <section> - <title>Defining Python functions into the global Python namespace + <title>Defining Python Functions into the Global Python Namespace </title> <para> <emphasis>NOTE:</emphasis> @@ -353,51 +520,7 @@ yourself.</para> </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> + <section> <title>Tasks</title> <para> <emphasis>NOTE:</emphasis> @@ -454,6 +577,65 @@ yourself.</para> </para> </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> + </section> + </section> + <section> <title>Events</title> <para> @@ -537,108 +719,9 @@ yourself.</para> (<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> - - <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> - <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> + <title>Dependencies</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 @@ -731,42 +814,6 @@ yourself.</para> </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 @@ -777,8 +824,7 @@ yourself.</para> <envar>BBPATH</envar>. </para> </section> - - <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. @@ -789,5 +835,5 @@ yourself.</para> and does handle wildcards. </para> </section> - </section> + </chapter> |