mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-03-19 13:49:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

bitbake: user-manual: Review edits applied from Paul Eggleton.

Browse Source 
Review of the entire manual by Paul.  I have implemented his
suggestions throughout.

(Bitbake rev: 5cd310d1df194cd171691a4bcfb98024e2bc66b8)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2014-03-06 09:48:37 -06:00
committed by Richard Purdie
parent 96294ee407
commit 40ab940360
4 changed files with 115 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
bitbake/doc/user-manual/user-manual-execution.xml
View File

@@ -87,21 +87,6 @@
just constructed.
The <filename>bitbake.conf</filename> file usually indicates
all the other key include files to parse.
The usual convention is to have machine, distro, site, and local
configurations.
This means a user provides their own customizations
through a <filename>local.conf</filename> file.
</para>
<para>
As mentioned in the previous paragraph, two of the other notable
configuration files are the distro and machine configuration
files.
These configuration files are normally identified by
variables unique to the build systems using BitBake.
For example, the Yocto Project uses the
<filename>DISTRO</filename> and <filename>MACHINE</filename>
variables, respectively.
</para>
<para>
@@ -122,7 +107,7 @@
<para>
The base configuration metadata is global
and therefore affects all packages and tasks that are executed.
and therefore affects all recipes and tasks that are executed.
</para>
<para>
@@ -161,10 +146,11 @@
These variables might have been set from the environment
depending on the environment variables previously
mentioned or set in the configuration files.
See the
The
"<link linkend='ref-variables-glos'>Variables Glossary</link>"
for a full list of variables.
The following list shows common variables set:
chapter presents a full list of variables.
<!--
Here are some common ones used:
<itemizedlist>
<listitem><para>
<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
@@ -215,6 +201,7 @@
<link linkend='var-BBINCLUDED'><filename>BBINCLUDED</filename></link>
</para></listitem>
</itemizedlist>
-->
</para>
<para>
@@ -305,7 +292,7 @@
</para>
<para>
BitBake does not need all this information.
BitBake does not need all of this information.
It only needs a small subset of the information to make
decisions about the recipe.
Consequently, BitBake caches the values in which it is
@@ -375,7 +362,7 @@
<literallayout class='monospaced'>
PROVIDES += "virtual/package"
</literallayout>
The recipe now provides both "package1" and "virtual/package.
The recipe now provides both "package1" and "virtual/package".
The "virtual/" namespace is often used to denote cases where
multiple providers are expected with the user choosing between
them.
@@ -395,20 +382,8 @@
The default
<link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
is the provider with the same name as the target.
</para>
<para>
Bitbake iterates through each target it needs to build and resolve
them using this process.
As an example, suppose the target is
<filename>core-image-sato</filename>.
In this case, it would lead to
<filename>packagegroup-core-x11-sato</filename>,
which in turn leads to recipes like
<filename>matchbox-terminal</filename>, <filename>pcmanfm</filename>
and <filename>gthumb</filename>.
These recipes in turn depend on <filename>eglibc</filename>
and the toolchain.
Bitbake iterates through each target it needs to build and
resolves them and their dependencies using this process.
</para>
<para>
@@ -418,21 +393,21 @@
Version comparisons are made using the same method as Debian.
You can use the
<link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
variable to specify a particular version (usually in the distro configuration).
variable to specify a particular version.
You can influence the order by using the
<link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
variable.
By default, files have a preference of "0".
Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
package unlikely to be used unless it is explicitly referenced.
Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
recipe unlikely to be used unless it is explicitly referenced.
Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the recipe is used.
<filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
<filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
<filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental recipe
versions until they have undergone sufficient testing to be considered stable.
</para>
<para>
When there are multiple “versions” of a given package,
When there are multiple “versions” of a given recipe,
BitBake defaults to selecting the most recent
version, unless otherwise specified.
If the recipe in question has a
@@ -573,12 +548,12 @@
<para>
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>
<filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}/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>.
<filename>${T}/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>
@@ -831,9 +806,6 @@
a setscene task named <filename>xxx_setscene</filename>.
The setscene version of the task executes and provides the necessary
artifacts returning either success or failure.
<note>
Artifacts might need to be fetched from the network.
</note>
</para>
<para>

11
bitbake/doc/user-manual/user-manual-fetching.xml
View File

@@ -42,7 +42,7 @@
fetcher = bb.fetch2.Fetch(src_uri, d)
fetcher.download()
</literallayout>
This code sets up an instance of the fetch module.
This code sets up an instance of the fetch class.
The instance uses a space-separated list of URLs from the
<link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
variable and then calls the <filename>download</filename>
@@ -155,14 +155,13 @@
<filename>SRC_URI</filename> variable with the appropriate
varflags as follows:
<literallayout class='monospaced'>
SRC_URI[md5sum]
SRC_URI[sha256sum]
SRC_URI[md5sum] = "value"
SRC_URI[sha256sum] = "value"
</literallayout>
You can also specify the checksums as parameters on the
<filename>SRC_URI</filename> as shown below:
<literallayout class='monospaced'>
SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07f
db994d"
SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d"
</literallayout>
If multiple URIs exist, you can specify the checksums either
directly as in the previous example, or you can name the URLs.
@@ -578,7 +577,7 @@ db994d"
Fetch submodules also exist for the following:
<itemizedlist>
<listitem><para>
Bazzar (<filename>bzr://</filename>)
Bazaar (<filename>bzr://</filename>)
</para></listitem>
<listitem><para>
Perforce (<filename>p4://</filename>)

81
bitbake/doc/user-manual/user-manual-intro.xml
View File

@@ -6,10 +6,10 @@
<para>
Welcome to the BitBake User Manual.
This manual provides information on BitBake.
This manual provides information on the BitBake tool.
The information attempts to be as independent as possible regarding
systems that use BitBake, such as the Yocto Project and
OpenEmbeddeded.
OpenEmbedded.
In some cases, scenarios or examples that within the context of
a build system are used in the manual to help with understanding.
For these cases, the manual clearly states the context.
@@ -88,7 +88,7 @@
an aspiring embedded Linux distribution.
All of the build systems used by traditional desktop Linux
distributions lacked important functionality, and none of the
ad-hoc buildroot systems, prevalent in the
ad-hoc Buildroot-based systems, prevalent in the
embedded space, were scalable or maintainable.
</para>
@@ -216,7 +216,7 @@
<para>
Within the context of BitBake, or any project utilizing BitBake
as it's build system, files with the <filename>.bb</filename>
as its build system, files with the <filename>.bb</filename>
extension are referred to as recipes.
<note>
The term "package" is also commonly used to describe recipes.
@@ -282,7 +282,7 @@
<para>
To illustrate how you can use layers to keep things modular,
consider machine customizations.
consider customizations you might make to support a specific target machine.
These types of customizations typically reside in a special layer,
rather than a general layer, called a Board Specific Package (BSP) Layer.
Furthermore, the machine customizations should be isolated from
@@ -343,7 +343,7 @@
<filename>busybox_1.3.0.bb</filename>, the append name would not
match.
However, if you named the append file
<filename>busybox_1.%.bb</filename>, then you would have a match.
<filename>busybox_1.%.bbappend</filename>, then you would have a match.
</para>
</section>
</section>
@@ -421,20 +421,10 @@
<title>The BitBake Command</title>
<para>
BitBake is the underlying piece of the build system.
Two excellent examples are the Yocto Project and the OpenEmbedded
build systems.
Each provide an environment in which to develop embedded Linux
images, and each use BitBake as their underlying build engine.
</para>
<para>
BitBake facilitates executing tasks in a single <filename>.bb</filename>
file, or executing a given task on a set of multiple
<filename>.bb</filename> files, accounting for interdependencies
amongst them.
This section presents the BitBake syntax and provides some execution
examples.
The BitBake command is the primary interface to the BitBake
tool.
This section presents the BitBake command syntax and provides
several execution examples.
</para>
<section id='usage-and-syntax'>
@@ -539,17 +529,21 @@ Options:
</para>
<para>
The following command runs the clean task on the
<filename>foo_1.0.bb</filename> recipe file:
<literallayout class='monospaced'>
$ bitbake -b foo.bb -c clean
</literallayout>
The following command runs the build task, which is
the default task, on the <filename>foo_1.0.bb</filename>
recipe file:
<literallayout class='monospaced'>
$ bitbake -b foo_1.0.bb
</literallayout>
The following command runs the clean task on the
<filename>foo_1.0.bb</filename> recipe file:
<literallayout class='monospaced'>
$ bitbake -b foo.bb -c clean
</literallayout>
<note>
The "-b" option explicitly does not handle recipe
dependencies.
</note>
</para>
</section>
@@ -573,7 +567,7 @@ Options:
<para>
The <filename>bitbake</filename> command, when not using
"--buildfile" or "-b" only accepts a "PROVIDER".
"--buildfile" or "-b" only accepts a "PROVIDES".
You cannot provide anything else.
By default, a recipe file generally "PROVIDES" its
"packagename", "packagename-version", and
@@ -581,10 +575,6 @@ Options:
example:
<literallayout class='monospaced'>
$ bitbake foo
$ bitbake foo-1.0
$ bitbake foo-1.0-r0
</literallayout>
This next example "PROVIDES" the package name and also uses
the "-c" option to tell BitBake to just execute the
@@ -600,22 +590,35 @@ Options:
<para>
BitBake is able to generate dependency graphs using
the dot syntax.
You can convert these graphs into images using the dot
application from
the <filename>dot</filename> syntax.
You can convert these graphs into images using the
<filename>dot</filename> tool from
<ulink url='http://www.graphviz.org'>Graphviz</ulink>.
</para>
<para>
When you generate a dependency graph, BitBake writes two files
When you generate a dependency graph, BitBake writes four files
to the current working directory:
<filename>depends.dot</filename>, which contains dependency information
at the package level, and <filename>task-depends.dot</filename>,
which contains a breakdown of the dependencies at the task level.
<itemizedlist>
<listitem><para><emphasis><filename>package-depends.dot</filename>:</emphasis>
Shows BitBake's knowledge of dependencies between
runtime targets.
</para></listitem>
<listitem><para><emphasis><filename>pn-depends.dot</filename>:</emphasis>
Shows dependencies between build-time targets
(i.e. recipes).
</para></listitem>
<listitem><para><emphasis><filename>task-depends.dot</filename>:</emphasis>
Shows dependencies between tasks.
</para></listitem>
<listitem><para><emphasis><filename>pn-buildlist</filename>:</emphasis>
Shows a simple list of targets that are to be built.
</para></listitem>
</itemizedlist>
</para>
<para>
To stop depending on common depends, use use the "-I" depend
To stop depending on common depends, use the "-I" depend
option and BitBake omits them from the graph.
Leaving this information out can produce more readable graphs.
This way, you can remove from the graph
@@ -629,7 +632,7 @@ Options:
<literallayout class='monospaced'>
$ bitbake -g foo
$ bitbake -g -I virtual/whatever -I bloom foo
$ bitbake -g -I virtual/kernel -I eglibc foo
</literallayout>
</para>
</section>

87
bitbake/doc/user-manual/user-manual-metadata.xml
View File

@@ -40,12 +40,15 @@
BitBake supports variables referencing one another's
contents using a syntax that is similar to shell scripting.
Following is an example that results in <filename>A</filename>
containing "aval" and <filename>B</filename> containing
containing "aval" and <filename>B</filename> evaluating to
"preavalpost".
<literallayout class='monospaced'>
A = "aval"
B = "pre${A}post"
</literallayout>
Because the expansion happens later, the value of
<filename>B</filename> expands differently if the value
of <filename>A</filename> changes.
</para>
</section>
@@ -79,7 +82,7 @@
<title>Setting a weak default value (??=)</title>
<para>
It is possible to use a "weaker" assignment that in the
It is possible to use a "weaker" assignment than in the
previous section by using the "??=" operator.
This assignment behaves identical to "?=" except that the
assignment is made at the end of the parsing process rather
@@ -197,6 +200,13 @@
override syntax.
</note>
</para>
<para>
The operators "_append" and "_prepend" differ from
the operators ".=" and "=." in that they are deferred
until after parsing completes rather than being immediately
applied.
</para>
</section>
<section id='removing-override-style-syntax'>
@@ -519,7 +529,7 @@
recipes require.
For example, you can easily abstract out the tasks involved in
building a package that uses Autoconf and Automake and put
those tasks into a class file that can be used by your package.
those tasks into a class file that can be used by your recipe.
</para>
<para>
@@ -549,9 +559,10 @@
directive.
This directive causes BitBake to parse whatever file you specify,
and to insert that file at that location.
The directive is much like Make except that if the path specified
on the include line is a relative path, BitBake locates
the first file it can find within <filename>BBPATH</filename>.
The directive is much like its equivalent in Make except
that if the path specified on the include line is a relative
path, BitBake locates the first file it can find
within <filename>BBPATH</filename>.
</para>
<para>
@@ -588,7 +599,7 @@
</para>
<para>
Similar to how BitBake uses
Similar to how BitBake handles
<link linkend='include-directive'><filename>include</filename></link>,
if the path specified
on the require line is a relative path, BitBake locates
@@ -776,16 +787,17 @@
Tasks are only supported in recipe (<filename>.bb</filename>
or <filename>.inc</filename>) and class
(<filename>.bbclass</filename>) files.
By convention, tasks begin with the string "do_".
By convention, task names begin with the string "do_".
</para>
<para>
Here is an example of a task that prints out the date:
<literallayout class='monospaced'>
python do_printdate () {
import time print
time.strftime('%Y%m%d', time.gmtime())
import time
print time.strftime('%Y%m%d', time.gmtime())
}
addtask printdate after do_fetch before do_build
</literallayout>
</para>
@@ -802,8 +814,8 @@
and defining some dependencies:
<literallayout class='monospaced'>
python do_printdate () {
import time print
time.strftime('%Y%m%d', time.gmtime())
import time
print time.strftime('%Y%m%d', time.gmtime())
}
addtask printdate after do_fetch before do_build
</literallayout>
@@ -942,11 +954,6 @@
<para>
BitBake has a defined set of varflags available for recipes and
classes.
You can discover the complete set by using <filename>grep</filename>
within a shell and search on the string "VarFlags".
</para>
<para>
Tasks support a number of these flags which control various
functionality of the task:
<itemizedlist>
@@ -958,12 +965,13 @@
</para></listitem>
<listitem><para><emphasis>noexec:</emphasis>
Marks the tasks as being empty and no execution required.
These flags are used as dependency placeholders or used when
added tasks need to be subsequently disabled.
The <filename>noexec</filename> flag can be used to set up
tasks as dependency placeholders, or to disable tasks defined
elsewhere that are not needed in a particular recipe.
</para></listitem>
<listitem><para><emphasis>nostamp:</emphasis>
Tells BitBake to not generate a stamp file for a task,
which implies the task is always executed.
which implies the task should always be executed.
</para></listitem>
<listitem><para><emphasis>fakeroot:</emphasis>
Causes a task to be run in a fakeroot environment,
@@ -1027,7 +1035,7 @@
List of functions to call before the task executes.
</para></listitem>
<listitem><para><emphasis>stamp-extra-info:</emphasis>
Extra stamp information to append to the task's stamp
Extra stamp information to append to the task's stamp.
As an example, OpenEmbedded uses this flag to allow
machine-specific tasks.
</para></listitem>
@@ -1380,15 +1388,18 @@
</row>
<row>
<entry align="left"><filename>d.setVar("X", value)</filename></entry>
<entry align="left">Sets the variable "X" to "value".</entry>
<entry align="left">Sets the variable "X" to the value of the Python
variable called "value".</entry>
</row>
<row>
<entry align="left"><filename>d.appendVar("X", value)</filename></entry>
<entry align="left">Adds "value" to the end of the variable "X".</entry>
<entry align="left">Adds the value of the Python variable called
"value" to the end of the variable "X".</entry>
</row>
<row>
<entry align="left"><filename>d.prependVar("X", value)</filename></entry>
<entry align="left">Adds "value" to the start of the variable "X".</entry>
<entry align="left">Adds the value of the Python variable called
"value" to the start of the variable "X".</entry>
</row>
<row>
<entry align="left"><filename>d.delVar("X")</filename></entry>
@@ -1400,40 +1411,44 @@
</row>
<row>
<entry align="left"><filename>d.getVarFlag("X", flag, expand=False)</filename></entry>
<entry align="left">Gets "flag" from the variable "X".
Using "expand=True" expands the flag.</entry>
<entry align="left">Gets then named flag from the variable "X".
Using "expand=True" expands the named flag.</entry>
</row>
<row>
<entry align="left"><filename>d.setVarFlag("X", flag, value)</filename></entry>
<entry align="left">Sets "flag" for variable "X" to "value".
<filename>setVarFlags</filename> does not clear previous flags.
Think of this operation as <filename>addVarFlags</filename>.</entry>
<entry align="left">Sets the named flag for variable "X" to the value
of the Python variable called "value".</entry>
</row>
<row>
<entry align="left"><filename>d.appendVarFlag("X", flag, value)</filename></entry>
<entry align="left">Need description.</entry>
<entry align="left">Appends a value to the named flag on the
variable "X".</entry>
</row>
<row>
<entry align="left"><filename>d.prependVarFlag("X", flag, value)</filename></entry>
<entry align="left">Need description.</entry>
<entry align="left">Prepends a value to the named flag on
the variable "X".</entry>
</row>
<row>
<entry align="left"><filename>d.delVarFlag("X", flag)</filename></entry>
<entry align="left">Need description.</entry>
<entry align="left">Deletes the named flag on the variable
"X" from the datastore.</entry>
</row>
<row>
<entry align="left"><filename>d.setVarFlags("X", flagsdict)</filename></entry>
<entry align="left">Sets the flags specified in
the <filename>dict()</filename> parameter.</entry>
the <filename>flagsdict()</filename> parameter.
<filename>setVarFlags</filename> does not clear previous flags.
Think of this operation as <filename>addVarFlags</filename>.</entry>
</row>
<row>
<entry align="left"><filename>d.getVarFlags("X")</filename></entry>
<entry align="left">Returns a <filename>dict</filename> of the flags for
<entry align="left">Returns a <filename>flagsdict</filename> of the flags for
the variable "X".</entry>
</row>
<row>
<entry align="left"><filename>d.delVarFlags</filename></entry>
<entry align="left">Deletes all the flags for a variable.</entry>
<entry align="left"><filename>d.delVarFlags("X")</filename></entry>
<entry align="left">Deletes all the flags for the variable "X".</entry>
</row>
</tbody>
</tgroup>