From 6697ce28851121fa570b93949b82a36c322e4014 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Wed, 10 Aug 2011 15:07:45 +0000 Subject: bitbake/usermanual: Update to be more in sync with bitbake codebase (Bitbake rev: 6c382c2ee7740a5e78b4135648870e5c181ec23f) Signed-off-by: Richard Purdie --- bitbake/doc/manual/usermanual.xml | 136 ++++++++++++++++++++++++++++++-------- 1 file changed, 108 insertions(+), 28 deletions(-) diff --git a/bitbake/doc/manual/usermanual.xml b/bitbake/doc/manual/usermanual.xml index 7dea949f4f..4f6725fd61 100644 --- a/bitbake/doc/manual/usermanual.xml +++ b/bitbake/doc/manual/usermanual.xml @@ -12,9 +12,10 @@ BitBake Team - 2004, 2005, 2006 + 2004, 2005, 2006, 2011 Chris Larson Phil Blundell + Richard Purdie This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by/2.5/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. @@ -26,7 +27,7 @@ Overview BitBake is, at its simplest, a tool for executing tasks and managing metadata. As such, its similarities to GNU make and other -build tools are readily apparent. It was inspired by Portage, the package management system used by the Gentoo Linux distribution. BitBake is the basis of the OpenEmbedded project, which is being used to build and maintain a number of embedded Linux distributions, including OpenZaurus and Familiar. +build tools are readily apparent. It was inspired by Portage, the package management system used by the Gentoo Linux distribution. BitBake is the basis of the OpenEmbedded project, which is being used to build and maintain a number of embedded Linux distributions/projects such as Angstrom and the Yocto project.
Background and goals @@ -37,7 +38,7 @@ important functionality, and none of the ad-hoc buildroot systems, prevalent in the embedded space, were scalable or maintainable. - Some important goals for BitBake were: + Some important original goals for BitBake were: Handle crosscompilation. Handle interpackage dependencies (build time on target architecture, build time on native architecture, and runtime). @@ -53,10 +54,18 @@ between multiple projects using BitBake for their builds. Should provide an inheritance mechanism to share common metadata between many packages. - Et cetera... - BitBake satisfies all these and many more. Flexibility and power have always been the priorities. It is highly extensible, supporting embedded Python code and execution of any arbitrary tasks. + Over time it has become apparent that some further requirements were necessary: + + Handle variants of a base recipe (native, sdk, multilib). + Able to split metadata into layers and allow layers to override each other. + Allow representation of a given set of input variables to a task as a checksum. + based on that checksum, allow acceleration of builds with prebuilt components. + + + + BitBake satisfies all the original requirements and many more with extensions being made to the basic functionality to reflect the additionl requirements. Flexibility and power have always been the priorities. It is highly extensible, supporting embedded Python code and execution of any arbitrary tasks.
@@ -94,10 +103,10 @@ share common metadata between many packages. If A is set before the above is called, 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 to a single variable, the first of those will be used.
- Setting a default value (??=) - A ??= "somevalue" - A ??= "someothervalue" - If A is set before the above, it will retain that value. If A is unset prior to the above, A will be set to someothervalue. This is a lazy version of ??=, 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. + Setting a weak default value (??=) + A ??= "somevalue" +A ??= "someothervalue" + If A is set before the above, 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 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 ??=
Immediate variable expansion (:=) @@ -209,6 +218,19 @@ include directive. addtask printdate before do_build 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.
+ +
+ Task Flags + Tasks support a number of flags which control various functionality of the task. These are as follows: + 'dirs' - directories which should be created before the task runs + 'cleandirs' - directories which should created before the task runs but should be empty + '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. + 'nostamp' - don't generate a stamp file for a task. This means the task is always rexecuted. + 'fakeroot' - this task needs to be run in a fakeroot environment, obtained by adding the variables in FAKEROOTENV to the environment. + 'umask' - the umask to run the task under. + For the 'deptask', 'rdeptask', 'recdeptask' and 'recrdeptask' flags please see the dependencies section. +
+
Events NOTE: This is only supported in .bb and .bbclass files. @@ -239,6 +261,51 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat 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 BPV variable, for use in file:// search paths (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 BitBake 1.7.x onwards works with the metadata at the task level since this is optimal when dealing with multiple threads of execution. A robust method of specifing task dependencies is therefore needed. @@ -299,13 +366,35 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat File download support
Overview - BitBake provides support to download files this procedure is called fetching. The SRC_URI is normally used to tell BitBake which files to fetch. The next sections will describe the available fetchers and their options. Each fetcher honors a set of variables and per URI parameters separated by a ; consisting of a key and a value. The semantics of the variables and parameters are defined by the fetcher. BitBake tries to have consistent semantics between the different fetchers. + BitBake provides support to download files this procedure is called fetching and it handled by the fetch and fetch2 modules. At this point the original fetch code is considered to be replaced by fetch2 and this manual only related to the fetch2 codebase. + + The SRC_URI is normally used to tell BitBake which files to fetch. The next sections will describe the available fetchers and their options. Each fetcher honors a set of variables and per URI parameters separated by a ; consisting of a key and a value. The semantics of the variables and parameters are defined by the fetcher. BitBake tries to have consistent semantics between the different fetchers. + + The overall fetch process is that first, fetches are attempted from PREMIRRORS. If those don't work, the original SRC_URI is attempted and if that fails, BitBake will fall back to MIRRORS. Cross urls are supported, so its possible to mirror a git repository on an http server as a tarball for example. Some example commonly used mirror definitions are: + + PREMIRRORS ?= "\ +bzr://.*/.* http://somemirror.org/sources/ \n \ +cvs://.*/.* http://somemirror.org/sources/ \n \ +git://.*/.* http://somemirror.org/sources/ \n \ +hg://.*/.* http://somemirror.org/sources/ \n \ +osc://.*/.* http://somemirror.org/sources/ \n \ +p4://.*/.* http://somemirror.org/sources/ \n \ +svk://.*/.* http://somemirror.org/sources/ \n \ +svn://.*/.* http://somemirror.org/sources/ \n" + +MIRRORS =+ "\ +ftp://.*/.* http://somemirror.org/sources/ \n \ +http://.*/.* http://somemirror.org/sources/ \n \ +https://.*/.* http://somemirror.org/sources/ \n" + + Non-local downloaded output is placed into the directory specified by the DL_DIR. For non local downloads the code can check checksums for the download to ensure the file has been downloaded correctly. These are specified in the form SRC_URI[md5sum] for the md5 checksum and SRC_URI[sha256sum] for the sha256 checksum. If BB_STRICT_CHECKSUM is set, any download without a checksum will trigger an error message. In cases where multiple files are listed in SRC_URI, the name parameter is used assign names to the urls and these are then specified in the checksums in the form SRC_URI[name.sha256sum]. +
Local file fetcher - The URN for the local file fetcher is file. The filename can be either absolute or relative. If the filename is relative, FILESPATH and FILESDIR will be used to find the appropriate relative file, depending on the OVERRIDES. Single files and complete directories can be specified. + The URN for the local file fetcher is file. The filename can be either absolute or relative. If the filename is relative, FILESPATH and failing that FILESDIR will be used to find the appropriate relative file. The metadata usually extend these variables to include variations of the values in OVERRIDES. Single files and complete directories can be specified. SRC_URI= "file://relativefile.patch" SRC_URI= "file://relativefile.patch;this=ignored" SRC_URI= "file:///Users/ich/very_important_software" @@ -314,8 +403,8 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
- CVS file fetcher - The URN for the CVS fetcher is cvs. This fetcher honors the variables DL_DIR, SRCDATE, FETCHCOMMAND_cvs, UPDATECOMMAND_cvs. DL_DIR specifies where a temporary checkout is saved. SRCDATE specifies which date to use when doing the fetching (the special value of "now" will cause the checkout to be updated on every build). FETCHCOMMAND and UPDATECOMMAND specify which executables to use for the CVS checkout or update. + CVS fetcher + The URN for the CVS fetcher is cvs. This fetcher honors the variables CVSDIR, SRCDATE, FETCHCOMMAND_cvs, UPDATECOMMAND_cvs. DL_DIR specifies where a temporary checkout is saved. SRCDATE specifies which date to use when doing the fetching (the special value of "now" will cause the checkout to be updated on every build). FETCHCOMMAND and UPDATECOMMAND specify which executables to use for the CVS checkout or update. The supported parameters are module, tag, date, method, localdir, rsh and scmdata. The module specifies which module to check out, the tag describes which CVS TAG should be used for the checkout. By default the TAG is empty. A date can be specified to override the SRCDATE of the configuration to checkout a specific date. The special value of "now" will cause the checkout to be updated on every build.method is by default pserver. If ext is used the rsh parameter will be evaluated and CVS_RSH will be set. Finally, localdir is used to checkout into a special directory relative to CVSDIR. @@ -327,28 +416,19 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat
HTTP/FTP fetcher - The URNs for the HTTP/FTP fetcher are http, https and ftp. This fetcher honors the variables DL_DIR, FETCHCOMMAND_wget, PREMIRRORS, MIRRORS. The DL_DIR defines where to store the fetched file. FETCHCOMMAND contains the command used for fetching. ${URI} and ${FILES} will be replaced by the URI and basename of the file to be fetched. PREMIRRORS will be tried first when fetching a file. If that fails, the actual file will be tried and finally all MIRRORS will be tried. - - The only supported parameter is md5sum. After a fetch the md5sum of the file will be calculated and the two sums will be compared. + The URNs for the HTTP/FTP fetcher are http, https and ftp. This fetcher honors the variables FETCHCOMMAND_wget. FETCHCOMMAND contains the command used for fetching. ${URI} and ${FILES} will be replaced by the URI and basename of the file to be fetched. - SRC_URI = "http://oe.handhelds.org/not_there.aac;md5sum=12343" -SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac;md5sum=1234" -SRC_URI = "ftp://you@oe.handheld.sorg/home/you/secret.plan;md5sum=1234" + SRC_URI = "http://oe.handhelds.org/not_there.aac" +SRC_URI = "ftp://oe.handhelds.org/not_there_as_well.aac" +SRC_URI = "ftp://you@oe.handheld.sorg/home/you/secret.plan"
-
- SVK fetcher - - Currently NOT supported - -
-
SVN fetcher The URN for the SVN fetcher is svn. - This fetcher honors the variables FETCHCOMMAND_svn, DL_DIR, SRCDATE. FETCHCOMMAND contains the subversion command. DL_DIR is the directory where tarballs will be saved. SRCDATE specifies which date to use when doing the fetching (the special value of "now" will cause the checkout to be updated on every build). + This fetcher honors the variables FETCHCOMMAND_svn, SVNDIR, SRCREV. FETCHCOMMAND contains the subversion command. SRCREV specifies which revision to use when doing the fetching. The supported parameters are proto, rev and scmdata. proto is the Subversion protocol, rev is the Subversion revision. If scmdata is set to keep, the .svn directories will be available during compile-time. @@ -361,7 +441,7 @@ SRC_URI_append_1.0.7+ = "file://some_patch_which_the_new_versions_need.patch;pat GIT fetcher The URN for the GIT Fetcher is git. - The Variables DL_DIR, GITDIR are used. DL_DIR will be used to store the checkedout version. GITDIR will be used as the base directory where the git tree is cloned to. + The variable GITDIR will be used as the base directory where the git tree is cloned to. The parameters are tag, protocol and scmdata. tag is a Git tag, the default is master. protocol is the Git protocol to use and defaults to rsync. If scmdata is set to keep, the .git directory will be available during compile-time. -- cgit v1.2.3-54-g00ecf