diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml index 5e4551bb6b..c6b9005cd7 100644 --- a/bitbake/doc/user-manual/user-manual-metadata.xml +++ b/bitbake/doc/user-manual/user-manual-metadata.xml @@ -5,21 +5,27 @@ Metadata
- Description - - BitBake metadata can be classified into 3 major areas: - - Configuration Files - - - .bb Files - - - Classes - - + Overview + - What follows are a large number of examples of BitBake metadata. Any syntax which isn't supported + The BitBake task executor together with various types of configuration files form the OpenEmbedded + Core. + This section provides an overview of the BitBake task executor and the configuration files by + describing what they are used for and how they interact. + + + + BitBake handles the parsing and execution of the data files. The data itself is of various types: + + Recipes: + Provides details about particular pieces of software. + Class Data: + An abstraction of common build information (e.g. how to build a Linux kernel). + Configuration Data: + Defines machine-specific settings, policy decisions, etc. Configuration data acts + as the glue to bind everything together. + + 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.
@@ -28,7 +34,7 @@ Basic Syntax
- Basic variable setting + Basic Variable Setting @@ -39,7 +45,7 @@
- Variable expansion + Variable Expansion BitBake supports variables referencing one another's @@ -69,8 +75,10 @@ it will retain its previous value. If A is unset prior to the above call, A will be set to aval. - Note that this assignment is immediate, so if there are multiple ?= assignments + + This assignment is immediate, so if there are multiple "?=" assignments to a single variable, the first of those will be used. +
@@ -86,11 +94,11 @@ it will retain that value. If A is unset prior to the above, A will be set to someothervalue. - This is a lazy/weak assignment in that the assignment does not occur until the end + This is a lazy or 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 ??= + "??=" assignment to a given variable will be used. + Any other setting of A using "=" or "?=" + will, however, override the value set with "??=". @@ -98,8 +106,9 @@ Immediate variable expansion (:=) - := results in a variable's contents being expanded immediately, rather than when the variable is actually used. - + The ":=" operator results in a variable's contents being expanded immediately, + rather than when the variable is actually used: + T = "123" A := "${B} ${A} test ${T}" T = "456" @@ -107,7 +116,7 @@ C = "cval" C := "${C}append" - In that example, A would contain + In this example, A would contain test 123, B would contain 456 bval, and C would be cvalappend. @@ -131,7 +140,7 @@
- Appending (.=) and prepending (=.) without spaces + Appending (.=) and Prepending (=.) Without Spaces @@ -149,7 +158,7 @@
- Appending and Prepending (override style syntax) + Appending and Prepending (Override Style Syntax) @@ -159,18 +168,20 @@ C_prepend = "additional data " This example results in B - becoming bval additional data - and C becoming + becoming bval additional data and + C becoming additional data cval. - Note the spaces in the _append. - Unlike the += operator, additional space is not automatically added. - You must take steps to add space -yourself. + + The spaces in _append. + Unlike the "+=" operator, additional space is not automatically added. + You must take steps to add space yourself. +
- Removing (override style syntax) + Removing (Override Style Syntax) + FOO = "123 456 789 123456 123 456 123 456" @@ -182,7 +193,7 @@ yourself.
- Variable flags + Variable Flags Variables can have associated flags which provide a way of tagging extra information onto a variable. @@ -192,12 +203,12 @@ yourself. VARIABLE[SOMEFLAG] = "value" In this example, VARIABLE has a flag, - SOMEFLAG which is set to value. + SOMEFLAG that is set to value.
- Python variable expansion + Inline Python Variable Expansion @@ -207,18 +218,22 @@ yourself. variable containing today's date.
+
- Conditional metadata set + Conditional Syntax (Overrides) + +
+ Conditional Metadata - OVERRIDES is a : separated variable containing - each item you want to satisfy conditions. - So, if you have a variable which is conditional on arm, and arm - is in OVERRIDES, then the arm specific + OVERRIDES is a “:” separated variable containing + each item for which you want to satisfy conditions. + So, if you have a variable that is conditional on “arm”, and “arm” + is in OVERRIDES, then the “arm” specific version of the variable is used rather than the non-conditional version. - Example: + Here is an example: OVERRIDES = "architecture:os:machine" TEST = "defaultvalue" @@ -227,16 +242,17 @@ yourself. In this example, TEST would be osspecificvalue, due to the condition - os being in OVERRIDES. + “os” being in OVERRIDES.
- Conditional appending + Conditional Appending BitBake also supports appending and prepending to variables based - on whether something is in OVERRIDES. Example: + on whether something is in OVERRIDES. + Here is an example: DEPENDS = "glibc ncurses" OVERRIDES = "machine:local" @@ -248,22 +264,22 @@ yourself.
- Variable interaction: Worked Examples + 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. + + + + Following are some common scenarios where variables interact + that can confuse users. There is often confusion about which order overrides and the - various append operators take effect. - - - + various "append" operators take effect: OVERRIDES = "foo" A_foo_append = "X" @@ -297,7 +313,7 @@ yourself. A .= "5" Would ultimately result in A taking the value - "1 4523" since the _append operator executes at the + "1 4523" since the "_append" operator executes at the same time as the expansion of other overrides.
@@ -306,7 +322,7 @@ yourself. Key Expansion - Key expansion happens at the data store finalisation + Key expansion happens at the data store finalization time just before overrides are expanded. A${B} = "X" @@ -322,10 +338,13 @@ yourself. Inheritance
- Inheritance - NOTE: - This is only supported in .bb and .bbclass files. - + Inheritance Directive + + + This is only supported in .bb and + .bbclass files. + + The inherit directive is a means of specifying what classes of functionality your .bb requires. @@ -339,34 +358,42 @@ yourself.
- Inclusion + Inclusion Directive - Next, there is the include directive, which causes BitBake to parse whatever file you specify, - and insert it at that location, which is not unlike make. - However, if the path specified on the include line is a + This directive causes BitBake to parse whatever file you specify, + and insert it at that location, which is not unlike Make. + However, if the path specified on the include line is a relative path, BitBake will locate the first one it can find within BBPATH.
- Requiring inclusion + Requiring Inclusion + - In contrast to the include directive, require will -raise an + In contrast to the include directive, require will raise a ParseError if the file to be included cannot be found. - Otherwise it will behave just like the include directive. + Otherwise it will behave just like the include directive.
- Defining Python functions into the global Python namespace + Defining Python Functions into the Global Python Namespace - NOTE: This is only supported in .bb and .bbclass files + + + This is only supported in .bb + and .bbclass files. + + + + Python functions are in the global namespace so should use + unique names. def get_depends(d): if d.getVar('SOMECONDITION', True): @@ -376,8 +403,10 @@ raise an SOMECONDITION = "1" DEPENDS = "${@get_depends(d)}" - This would result in DEPENDS containing dependencywithcond. + This would result in DEPENDS + containing dependencywithcond. +
@@ -436,15 +465,15 @@ python do_printdate () { Configuration files The first kind of metadata in BitBake is configuration metadata. - This metadata is global, and therefore affects all packages and - tasks which are executed. + 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 which is a space delimited list of 'layer' directories. + 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 @@ -456,10 +485,10 @@ python do_printdate () { BitBake will then expect to find conf/bitbake.conf - somewhere in the user specified BBPATH. + file 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, local and so on). + machine, local and so on). @@ -467,8 +496,10 @@ python do_printdate () { in .conf files.
+
Classes + BitBake classes are our rudimentary inheritance mechanism. As briefly mentioned in the metadata introduction, they're @@ -479,15 +510,15 @@ python do_printdate () {
- .<filename>.bb</filename> files + <filename>.bb</filename> Files - BitBake (.bb) file is a logical unit + 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 + The files themselves are located via the + BBFILES variable, which is set to a space separated list of .bb files, and does handle wildcards. @@ -497,17 +528,17 @@ python do_printdate () {
Events - - NOTE: - This is only supported in .bb + + This is only supported in .bb and .bbclass files. - + + 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. + task failure, task success, and so forth. The intent is to make it easy to do things like email notification on build failure. @@ -521,9 +552,9 @@ python do_printdate () { This event handler gets called every time an event is triggered. - A global variable e is defined. - e.data contains an instance of - bb.data. + A global variable "e" is defined. + "e.data" contains an instance of + "bb.data". With the getName(e) method one can get the name of the triggered event. @@ -535,7 +566,7 @@ python do_printdate () {
- Variants + Variants - Class Extension Mechanism Two BitBake features exist to facilitate the creation of @@ -546,15 +577,12 @@ python do_printdate () { The first is BBCLASSEXTEND. This variable is a space separated list of classes used to "extend" the recipe for each variant. - As an example, setting + Here is an example that results in a second incarnation of the current + recipe being available. + This second incarnation will have the "native" class inherited. BBCLASSEXTEND = "native" - results in a second incarnation of the current - recipe being available. - This second incarnation will have the "native" class inherited. - - The second feature is BBVERSIONS. This variable allows a single recipe to build multiple versions of a project from a single recipe file, and allows you to specify @@ -568,7 +596,7 @@ python do_printdate () { 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" - Note that the name of the range will default to the original version of the + 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; @@ -579,17 +607,21 @@ python do_printdate () {
- Dependency handling + Dependencies + +
+ Overview 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. + processes executing in parallel, a robust method of + specifying task dependencies is needed. +
- Dependencies internal to the <filename>.bb</filename> file + Dependencies Internal to the <filename>.bb</filename> File Where the dependencies are internal to a given @@ -609,7 +641,7 @@ python do_printdate () { do_configure[deptask] = "do_populate_staging" - means the do_populate_staging + In the previous example, the do_populate_staging task of each item in DEPENDS must have completed before do_configure can execute. @@ -628,7 +660,7 @@ python do_printdate () { do_package_write[rdeptask] = "do_package" - means the do_package + In the previous example, the do_package task of each item in RDEPENDS must have completed before do_package_write can execute. @@ -639,7 +671,7 @@ python do_printdate () { These are specified with the 'recrdeptask' flag - which is used signify the task(s) of dependencies + 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 @@ -655,29 +687,29 @@ python do_printdate () { 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". + be referenced in the task list (e.g. + do_a[recrdeptask] = "do_a do_b").
- Inter task + Inter-Task Dependencies - The 'depends' flag for tasks is a more generic form of which - allows an interdependency on specific tasks rather than specifying + The 'depends' flag for tasks is a more generic form which + allows an inter-dependency on specific tasks rather than specifying the data in DEPENDS. do_patch[depends] = "quilt-native:do_populate_staging" - means the do_populate_staging + In the previous example, the do_populate_staging task of the target quilt-native must have completed before the do_patch task can execute. The 'rdepends' flag works in a similar way but takes targets - in the runtime namespace instead of the build time dependency + in the runtime namespace instead of the build-time dependency namespace.