From 09dc2b6d859a55bfe5b60173b68e3499bc0ec70d Mon Sep 17 00:00:00 2001 From: Bill Traynor Date: Mon, 15 Apr 2013 19:02:40 -0400 Subject: 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 --- doc/user-manual/user-manual-metadata.xml | 484 +++++++++++++++++-------------- 1 file changed, 265 insertions(+), 219 deletions(-) (limited to 'doc/user-manual/user-manual-metadata.xml') 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 @@ +
- Basic variable setting + Basic Variable Setting VARIABLE = "value" @@ -56,7 +57,7 @@
- Variable expansion + Variable Expansion BitBake supports variables referencing one another's contents using a syntax which is similar to shell scripting: @@ -73,7 +74,7 @@
- Setting a default value (?=) + Setting a Default Value (?=) A?= "aval" @@ -89,7 +90,7 @@
- Setting a weak default value (??=) + Setting a Weak Default Value (??=) A??= "somevalue" @@ -113,7 +114,7 @@
- Immediate variable expansion (:=) + Immediate Variable Expansion (:=) := results in a variable's contents being expanded immediately, rather than when the variable is actually used. @@ -139,9 +140,11 @@ cvalappend.
- +
+ +
- Appending (+=) and prepending (=+) + Appending (+=) and Prepending (=+) B = "bval" @@ -160,7 +163,7 @@
- Appending (.=) and prepending (=.) without spaces + Appending (.=) and Prepending (=.) without spaces B = "bval" @@ -168,11 +171,10 @@ C = "cval" C=. "test" - - In this example, - B - is now - bvaladditionaldata + + In this example, + B is now + bvaladditionaldata and C is @@ -201,8 +203,50 @@ yourself. In this example, FOO is now 789 123456.
+
+ Variable Flags + 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. + + + + VARIABLE + [ + SOMEFLAG + ] = "value" + + + In this example, + VARIABLE + has a flag, + SOMEFLAG + that is set to + value. + +
+ +
+ Inline Python variable expansion + + + DATE = + "${@time.strftime('%Y%m%d',time.gmtime())}" + + + This would result in the + DATE + variable containing today's date. + +
+ +
+ Conditional Syntax (Overrides) +
- Conditional metadata set + Conditional Metadata OVERRIDES is a : separated variable containing each item you want to satisfy @@ -238,7 +282,7 @@ yourself.
- Conditional appending + Conditional Appending BitBake also supports appending and prepending to variables based on whether something is in OVERRIDES. Example: @@ -252,15 +296,135 @@ yourself. DEPENDS_append_machine = "libmad" - - In this example, - DEPENDS ' - is set to + + In this example, + DEPENDS is set to glibc ncurses libmad.
+ +
+ Variable Interaction: Worked Examples + 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. + +
+ +
+ Override and Append Ordering + There is often confusion about which order overrides and the + various append operators take effect. + + + + OVERRIDES + = "foo" + A_foo_append + = "X" + + In this case, X is unconditionally appended to the variable + A_foo. + Since foo is an override, A_foo would then replace + A. + + + OVERRIDES + = "foo" + A + = "X" + A_append_foo + = "Y" + + + In this case, only when foo is in OVERRIDES, Y is appended to the + variable + A + so the value of + A + would become XY (NB: no spaces are appended). + + + + OVERRIDES + = "foo" + A_foo_append + = "X" + A_foo_append + += "Y" + + + This behaves as per the first case above, but the value of + A + would be "X Y" instead of just "X". + + + + A + = "1" + A_append + = "2" + A_append + = "3" + A + += "4" + A + .= "5" + + + Would ultimately result in + A + taking the value "1 4523" since the _append operator executes + at the same time as the expansion of other overrides. + +
+ Key Expansion + Key expansion happens at the data store finalisation time just + before overrides are expanded. + + + + A${B} + = "X" + B + = "2" + A2 + = "Y" + + + So in this case + A2 + would take the value of "X". + +
+
+ +
+Inheritance +
+ Inheritance + + NOTE: This is only supported in .bb + and .bbclass files. + + The inherit 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 + BBPATH, + where filename is what you inherited. + +
+ +
Inclusion Next, there is the include directive, that causes BitBake to @@ -271,11 +435,12 @@ yourself. line is a relative path, BitBake will locate the first one it can find within BBPATH. + FIX ME: This section requires improvement.
- Requiring inclusion + Requiring Inclusion In contrast to the include directive, @@ -285,25 +450,27 @@ yourself. Otherwise it will behave just like the include directive. + FIX ME: This section requires improvement. +
- Inline Python variable expansion + INHERIT Configuration Directive - - DATE = - "${@time.strftime('%Y%m%d',time.gmtime())}" - - - This would result in the - DATE - variable containing today's date. - -
- + This configuration directive causes the named class to be inherited at this point during parsing. + This variable is only valid in configuration files. + + + ADD MORE HERE + +
+ + +
+ Functions and Tasks
- Defining executable metadata + Defining Executable Metadata NOTE: This is only supported in .bb and .bbclass files. @@ -326,7 +493,7 @@ yourself.
- Defining Python functions into the global Python namespace + <title>Defining Python Functions into the Global Python Namespace NOTE: @@ -353,51 +520,7 @@ yourself.
-
- Variable flags - 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. - - - - VARIABLE - [ - SOMEFLAG - ] = "value" - - - In this example, - VARIABLE - has a flag, - SOMEFLAG - that is set to - value. - -
- -
- Inheritance - - NOTE: This is only supported in .bb - and .bbclass files. - - The inherit 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 - BBPATH, - where filename is what you inherited. - -
- -
+
Tasks NOTE: @@ -454,6 +577,65 @@ yourself.
+
+ Parsing +
+ Configuration files + The first kind of metadata in BitBake is configuration + metadata. + This metadata is global, and therefore affects + all + packages and tasks that are executed. + + 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. + + BitBake will then expect to find 'conf/bitbake.conf' + somewhere in the user specified + BBPATH. + That configuration file generally has include + directives to pull in any other metadata (generally + files specific to architecture, machine, + localand so on). + + Only variable definitions and include directives are + allowed in .conf files. + +
+
+ Classes + BitBake classes are our rudimentary inheritance mechanism. + As briefly mentioned in the metadata introduction, they're + parsed when an + inherit + directive is encountered, and they are located in classes/ + relative to the directories in + BBPATH. + +
+
+ .bb files + 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 + BBFILES + variable, which is set to a space separated list of .bb files, + and does handle wildcards. + +
+
+
Events @@ -537,108 +719,9 @@ yourself. (FILESPATH).
- -
- Variable interaction: Worked Examples - 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. - -
- -
- Override and append ordering - There is often confusion about which order overrides and the - various append operators take effect. - - - - OVERRIDES - = "foo" - A_foo_append - = "X" - - In this case, X is unconditionally appended to the variable - A_foo. - Since foo is an override, A_foo would then replace - A. - - - OVERRIDES - = "foo" - A - = "X" - A_append_foo - = "Y" - - - In this case, only when foo is in OVERRIDES, Y is appended to the - variable - A - so the value of - A - would become XY (NB: no spaces are appended). - - - - OVERRIDES - = "foo" - A_foo_append - = "X" - A_foo_append - += "Y" - - - This behaves as per the first case above, but the value of - A - would be "X Y" instead of just "X". - - - - A - = "1" - A_append - = "2" - A_append - = "3" - A - += "4" - A - .= "5" - - - Would ultimately result in - A - taking the value "1 4523" since the _append operator executes - at the same time as the expansion of other overrides. - -
- -
- Key Expansion - Key expansion happens at the data store finalisation time just - before overrides are expanded. - - - - A${B} - = "X" - B - = "2" - A2 - = "Y" - - - So in this case - A2 - would take the value of "X". - -
- +
- Dependency handling + Dependencies 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 @@ -730,42 +813,6 @@ yourself.
-
- Parsing -
- Configuration files - The first kind of metadata in BitBake is configuration - metadata. - This metadata is global, and therefore affects - all - packages and tasks that are executed. - - 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. - - BitBake will then expect to find 'conf/bitbake.conf' - somewhere in the user specified - BBPATH. - That configuration file generally has include - directives to pull in any other metadata (generally - files specific to architecture, machine, - localand so on). - - Only variable definitions and include directives are - allowed in .conf files. - -
-
Classes BitBake classes are our rudimentary inheritance mechanism. @@ -777,8 +824,7 @@ yourself. BBPATH.
- -
+
.bb files 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. and does handle wildcards.
-
+ -- cgit 1.2.3-korg