mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-06-02 01:19:52 +00:00
Code Issues Projects Releases Wiki Activity

documentation/poky-ref-manual/ref-bitbake.xml: Completed general edits.

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