diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/poky-ref-manual/ref-bitbake.xml | 269 |
1 files changed, 135 insertions, 134 deletions
diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml index cf019aabcd..1a98b048be 100644 --- a/documentation/poky-ref-manual/ref-bitbake.xml +++ b/documentation/poky-ref-manual/ref-bitbake.xml @@ -28,15 +28,15 @@ <title>Parsing</title> <para> - The first thing BitBake does is work out its configuration by - looking for a file called <filename>bitbake.conf</filename>. - BitBake examines the <varname>BBPATH</varname> environment - variable looking for a <filename class="directory">conf/</filename> - directory that contains a <filename>bitbake.conf</filename> file. - BitBake adds the first <filename>bitbake.conf</filename> file found in - <varname>BBPATH</varname> (similar to the PATH environment variable). - For Poky, <filename>bitbake.conf</filename> is found in <filename - class="directory">meta/conf/</filename>. + BitBake parses configuration files, classes, and <filename>.bb</filename> files. + </para> + + <para> + The first thing BitBake does is look for the <filename>bitbake.conf</filename> file. + Poky keeps this file in <filename class="directory">meta/conf/</filename>. + BitBake finds it by examining the <varname>BBPATH</varname> environment + variable and looking for the <filename class="directory">meta/conf/</filename> + directory. </para> <para> @@ -75,12 +75,12 @@ </para> <para> - After the parsing of the configuration files is complete, the + After classes are included, the variable <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> is set, usually in <filename>local.conf</filename>, and defines the list of places to search for <filename class="extension">.bb</filename> files. - By default this specifies the <filename class="directory">meta/packages/ + By default, the BBFILES variable specifies the <filename class="directory">meta/packages/ </filename> directory within Poky, but other directories such as <filename class="directory">meta-extras/</filename> can be included too. @@ -92,19 +92,19 @@ BitBake parses each <filename class="extension">.bb</filename> file in BBFILES and stores the values of various variables. In summary, for each <filename class="extension">.bb</filename> - file the configuration + base class of variables are set, followed + file the configuration plus the base class of variables are set, followed by the data in the <filename class="extension">.bb</filename> file itself, followed by any inherit commands that <filename class="extension">.bb</filename> file might contain. </para> <para> - Parsing <filename class="extension">.bb</filename> files is a time - consuming process, so a cache is kept to speed up subsequent parsing. + Because parsing <filename class="extension">.bb</filename> files is a time + consuming process, a cache is kept to speed up subsequent parsing. This cache is invalid if the timestamp of the <filename class="extension">.bb</filename> - file itself has changed, or if the timestamps of any of the include, + file itself changes, or if the timestamps of any of the include, configuration or class files the <filename class="extension">.bb</filename> - file depends on have changed. + file depends on changes. </para> </section> @@ -113,58 +113,53 @@ <para> Once all the <filename class="extension">.bb</filename> files have been - parsed, BitBake will proceed to build "poky-image-sato" (or whatever was - specified on the commandline) and looks for providers of that target. + parsed, BitBake starts to build the target (poky-image-sato in the previous section's + example) and looks for providers of that target. Once a provider is selected, BitBake resolves all the dependencies for - the target. In the case of "poky-image-sato", it would lead to - <filename>task-base.bb</filename> - which in turn would lead to packages like <application>Contacts</application>, - <application>Dates</application>, <application>BusyBox</application> - and these in turn depend on glibc and the toolchain. + the target. + In the case of "poky-image-sato", it would lead to <filename>task-base.bb</filename>, + which in turn leads to packages like <application>Contacts</application>, + <application>Dates</application> and <application>BusyBox</application>. + These packages in turn depend on glibc and the toolchain. </para> <para> - Sometimes a target might have multiple providers and a common example - is "virtual/kernel" that is provided by each kernel package. Each machine - will often elect the best provider of its kernel with a line like the + Sometimes a target might have multiple providers. + An common example is "virtual/kernel", which is provided by each kernel package. + Each machine often elects the best kernel provider by using a line similar to the following in the machine configuration file: </para> - <programlisting><glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel = "linux-rp"</programlisting> + + <programlisting> +PREFERRED_PROVIDER_virtual/kernel = "linux-rp" + </programlisting> + <para> - The default <glossterm><link linkend='var-PREFERRED_PROVIDER'> - PREFERRED_PROVIDER</link></glossterm> is the provider with the same name as - the target. + The default <glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm> + is the provider with the same name as the target. </para> <para> - Understanding how providers are chosen is complicated by the fact - multiple versions might be present. BitBake defaults to the highest - version of a provider by default. Version comparisons are made using - the same method as Debian. The <glossterm><link - linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> - variable can be used to specify a particular version - (usually in the distro configuration) but the order can - also be influenced by the <glossterm><link - linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> - variable. By default files - have a preference of "0". Setting the - <glossterm><link - linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> to "-1" will - make a package unlikely to be used unless it was explicitly referenced and - "1" makes it likely the package will be used. - <glossterm><link - linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides - any <glossterm><link - linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>. <glossterm><link - linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> - is often used to mark more - experimental new versions of packages until they've undergone sufficient - testing to be considered stable. + Understanding how providers are chosen is made complicated by the fact + that multiple versions might exist. + BitBake defaults to the highest version of a provider. + Version comparisons are made using the same method as Debian. + You can use the <glossterm><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> + variable to specify a particular version (usually in the distro configuration). + You can influence the order by using the + <glossterm><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> + variable. + By default, files have a preference of "0". + Setting the DEFAULT_PREFERENCE to "-1" makes the package unlikely to be used unless it is + explicitly referenced. + Setting the DEFAULT_PREFERENCE to "1" makes it likely the package is used. + PREFERRED_VERSION overrides any DEFAULT_PREFERENCE setting. + DEFAULT_PREFERENCE is often used to mark newer and more experimental package + versions until they have undergone sufficient testing to be considered stable. </para> <para> - The end result is that internally, BitBake has now built a list of - providers for each target it needs in order of priority. + In summary, BitBake has created a list of providers, which is prioritized, for each target. </para> </section> @@ -172,18 +167,20 @@ <title>Dependencies</title> <para> - Each target BitBake builds consists of multiple tasks (e.g. fetch, - unpack, patch, configure, compile etc.). For best performance on - multi-core systems, BitBake considers each task as an independent - entity with a set of dependencies. There are many variables that - are used to signify these dependencies and more information can be found - about these in the <ulink url='http://bitbake.berlios.de/manual/'> - BitBake manual</ulink>. At a basic level it is sufficient to know - that BitBake uses the <glossterm><link - linkend='var-DEPENDS'>DEPENDS</link></glossterm> and - <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when - calculating dependencies and descriptions of these variables are - available through the links. + Each target BitBake builds consists of multiple tasks such as fetch, unpack, patch, configure, + and compile. + For best performance on multi-core systems, BitBake considers each task as an independent + entity with its own set of dependencies. + </para> + + <para> + Dependencies are defined through several variables. + You can find information about variables BitBake uses in the + <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>. + At a basic level it is sufficient to know that BitBake uses the + <glossterm><link linkend='var-DEPENDS'>DEPENDS</link></glossterm> and + <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when + calculating dependencies. </para> </section> @@ -193,69 +190,75 @@ <para> Based on the generated list of providers and the dependency information, - BitBake can now calculate exactly which tasks it needs to run and in what - order. The build now starts with BitBake forking off threads up to - the limit set in the <glossterm><link - linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable - as long as there are tasks ready to run, i.e. tasks with all their - dependencies met. + BitBake can now calculate exactly what tasks it needs to run and in what + order it needs to run them. + The build now starts with BitBake forking off threads up to the limit set in the + <glossterm><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable. + BitBake continues to fork threads as long as there are tasks ready to run, + those taksks have all their dependencies met, and the thread threshold has not been + exceeded. </para> <para> - As each task completes, a timestamp is written to the directory - specified by the <glossterm><link - linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually - <filename class="directory">build/tmp/stamps/*/</filename>). On - subsequent runs, BitBake looks at the <glossterm><link - linkend='var-STAMPS'>STAMPS</link></glossterm> - directory and will not rerun - tasks its already completed unless a timestamp is found to be invalid. - Currently, invalid timestamps are only considered on a per <filename - class="extension">.bb</filename> file basis so if for example the configure stamp has a timestamp greater than the - compile timestamp for a given target the compile task would rerun but this - has no effect on other providers depending on that target. This could - change or become configurable in future versions of BitBake. Some tasks - are marked as "nostamp" tasks which means no timestamp file will be written - and the task will always rerun. + As each task completes, a timestamp is written to the directory specified by the + <glossterm><link linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually + <filename class="directory">build/tmp/stamps/*/</filename>). + On subsequent runs, BitBake looks at the STAMPS directory and does not rerun + tasks that are already completed unless a timestamp is found to be invalid. + Currently, invalid timestamps are only considered on a per + <filename class="extension">.bb</filename> file basis. + So, for example, if the configure stamp has a timestamp greater than the + compile timestamp for a given target then the compile task would rerun. + Running the compile task again, however, has no effect on other providers + that depend on that target. + This behavior could change or become configurable in future versions of BitBake. </para> - - <para>Once all the tasks have been completed BitBake exits.</para> - + + <note><para> + Some tasks are marked as "nostamp" tasks. + No timestamp file is created when these tasks are run. + Consequently, "nostamp" tasks are always rerun. + </para></note> </section> <section id='ref-bitbake-runtask'> <title>Running a Task</title> <para> - It's worth noting what BitBake does to run a task. A task can either - be a shell task or a python task. For shell tasks, BitBake writes a - shell script to <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> - and then executes the script. The generated - shell script contains all the exported variables, and the shell functions - with all variables expanded. Output from the shell script is - sent to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. - Looking at the - expanded shell functions in the run file and the output in the log files + Tasks can either be a shell task or a python task. + For shell tasks, BitBake writes a shell script to + <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script. + The generated shell script contains all the exported variables, and the shell functions + with all variables expanded. + Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. + Looking at the expanded shell functions in the run file and the output in the log files is a useful debugging technique. </para> <para> - Python functions are executed internally to BitBake itself and - logging goes to the controlling terminal. Future versions of BitBake will - write the functions to files in a similar way to shell functions and - logging will also go to the log files in a similar way. + For Python tasks, BitBake executes the task internally and logs information to the + controlling terminal. + Future versions of BitBake will write the functions to files similar to the way + shell tasks are handled. + Logging will be handled in way similar to shell tasks as well. </para> + + <para> + Once all the tasks have been completed BitBake exits. + </para> </section> <section id='ref-bitbake-commandline'> - <title>Commandline</title> + <title>BitBake Command Line</title> <para> - To quote from "bitbake --help": + Following is the bitbake manpage: </para> - <screen>Usage: bitbake [options] [package ...] + <screen> +$ bitbake --help +Usage: bitbake [options] [package ...] Executes the specified task (default is 'build') for a given set of BitBake files. It expects that BBFILES is defined, which is a space separated list of files to @@ -275,6 +278,8 @@ Options: -a, --tryaltconfigs continue with builds by trying to use alternative providers where possible. -f, --force force run of specified cmd, regardless of stamp status + -i, --interactive drop into the interactive mode also called the BitBake + shell. -c CMD, --cmd=CMD Specify task to execute. Note that this only executes the specified task for the providee and the packages it depends on, i.e. 'compile' does not implicitly call @@ -287,9 +292,6 @@ Options: -D, --debug Increase the debug level. You can specify this more than once. -n, --dry-run don't execute, just go through the motions - -S, --dump-signatures - don't execute, just dump out the signature - construction information -p, --parse-only quit after parsing the BB files (developers only) -d, --disable-psyco disable using the psyco just-in-time compiler (not recommended) @@ -298,46 +300,45 @@ Options: what used to be bbread) -g, --graphviz emit the dependency trees of the specified packages in the dot syntax - -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED - Assume these dependencies don't exist and are already - provided (equivalent to ASSUME_PROVIDED). Useful to - make dependency graphs more appealing + -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS + Stop processing at the given list of dependencies when + generating dependency graphs. This can help to make + the graph more appealing -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS Show debug logging for the specified logging domains -P, --profile profile the command and print a report - -u UI, --ui=UI userinterface to use - --revisions-changed Set the exit code depending on whether upstream - floating revisions have changed or not</screen> - + </screen> </section> <section id='ref-bitbake-fetchers'> <title>Fetchers</title> <para> - As well as the containing the parsing and task/dependency handling - code, BitBake also contains a set of "fetcher" modules which allow - fetching of source code from various types of sources. Example - sources might be from disk with the metadata, from websites, from - remote shell accounts or from SCM systems like cvs/subversion/git. + BitBake also contains a set of "fetcher" modules that allow + retrieval of source code from various types of sources. + For example, BitBake can get source code from a disk with the metadata, from websites, + from remote shell accounts or from Source Code Management (SCM) systems + like <filename>cvs/subversion/git</filename>. </para> <para> - The fetchers are usually triggered by entries in - <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. Information about the - options and formats of entries for specific fetchers can be found in the - <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>. + Fetchers are usually triggered by entries in + <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. + You can find information about the options and formats of entries for specific + fetchers in the <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>. </para> <para> One useful feature for certain SCM fetchers is the ability to - "auto-update" when the upstream SCM changes version. Since this - requires certain functionality from the SCM only certain systems - support it, currently Subversion, Bazaar and to a limited extent, Git. It - works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link> - </glossterm> variable. See the <link linkend='platdev-appdev-srcrev'> - developing with an external SCM based project</link> section for more - information. + "auto-update" when the upstream SCM changes version. + Since this ability requires certain functionality from the SCM, not all + systems support it. + Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". + This feature works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link></glossterm> + variable. + See the + <link linkend='platdev-appdev-srcrev'>Developing within Poky with an External SCM-based Package</link> + section for more information. </para> </section> |