sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

ref-manual: Various tweaks/fixes for ch4. ref manual 

(From yocto-docs rev: dc14dbc39d9cb70420d2773eef56a42ac0b2fc24)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Robert P. J. Day 2013-11-06 10:45:40 -08:00 committed by Richard Purdie
parent cebf4814bd
commit c354dc6e4f
1 changed files with 44 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
documentation/ref-manual/technical-details.xml
View File

@ -60,9 +60,9 @@
and is responsible for parsing the and is responsible for parsing the
<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>, <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
generating a list of tasks from it, and then executing those tasks. generating a list of tasks from it, and then executing those tasks.
To see a list of the options BitBake supports, use the following To see a list of the options BitBake supports, use either of:
help command:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake -h
$ bitbake --help $ bitbake --help
</literallayout> </literallayout>
</para> </para>
@ -72,7 +72,7 @@
<filename>packagename</filename> is the name of the package you want to build <filename>packagename</filename> is the name of the package you want to build
(referred to as the "target" in this manual). (referred to as the "target" in this manual).
The target often equates to the first part of a <filename>.bb</filename> filename. The target often equates to the first part of a <filename>.bb</filename> filename.
So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you So, to process the <filename>matchbox-desktop_1.2.3.bb</filename> recipe file, you
might type the following: might type the following:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake matchbox-desktop $ bitbake matchbox-desktop
@ -111,14 +111,15 @@
<para> <para>
The <filename>.bb</filename> files are usually referred to as "recipes." The <filename>.bb</filename> files are usually referred to as "recipes."
In general, a recipe contains information about a single piece of software. In general, a recipe contains information about a single piece of software.
The information includes the location from which to download the source patches This information includes the location from which to download the
pristine source, any source patches to be applied to that source
(if any are needed), which special configuration options to apply, (if any are needed), which special configuration options to apply,
how to compile the source files, and how to package the compiled output. how to compile the source files, and how to package the compiled output.
</para> </para>
<para> <para>
The term "package" can also be used to describe recipes. The term "package" is sometimes (confusingly) used to refer to recipes. However,
However, since the same word is used for the packaged output from the OpenEmbedded since the word "package" is used for the packaged output from the OpenEmbedded
build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files), build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
this document avoids using the term "package" when referring to recipes. this document avoids using the term "package" when referring to recipes.
</para> </para>
@ -162,7 +163,7 @@
<ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>. <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
This section provides some technical background information on how This section provides some technical background information on how
cross-development toolchains are created and used. cross-development toolchains are created and used.
For more information on these toolchain, you can also see the For more information on toolchains, you can also see the
<ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>. <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>.
</para> </para>
@ -347,7 +348,7 @@
As mentioned in the previous paragraph, building from scratch ensures that As mentioned in the previous paragraph, building from scratch ensures that
everything is current and starts from a known state. everything is current and starts from a known state.
However, building from scratch also takes much longer as it generally means However, building from scratch also takes much longer as it generally means
rebuilding things that do not necessarily need rebuilt. rebuilding things that do not necessarily need to be rebuilt.
</para> </para>
<para> <para>
@ -355,10 +356,11 @@
The implementation of the shared state code answers the following questions that The implementation of the shared state code answers the following questions that
were fundamental roadblocks within the OpenEmbedded incremental build support system: were fundamental roadblocks within the OpenEmbedded incremental build support system:
<itemizedlist> <itemizedlist>
<listitem>What pieces of the system have changed and what pieces have not changed?</listitem> <listitem><para>What pieces of the system have changed and what pieces have
<listitem>How are changed pieces of software removed and replaced?</listitem> not changed?</para></listitem>
<listitem>How are pre-built components that do not need to be rebuilt from scratch <listitem><para>How are changed pieces of software removed and replaced?</para></listitem>
used when they are available?</listitem> <listitem><para>How are pre-built components that do not need to be rebuilt from scratch
used when they are available?</para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -397,16 +399,16 @@
<para> <para>
When determining what parts of the system need to be built, BitBake When determining what parts of the system need to be built, BitBake
uses a per-task basis and does not use a per-recipe basis. works on a per-task basis rather than a per-recipe basis.
You might wonder why using a per-task basis is preferred over a per-recipe basis. You might wonder why using a per-task basis is preferred over a per-recipe basis.
To help explain, consider having the IPK packaging backend enabled and then switching to DEB. To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
In this case, <filename>do_install</filename> and <filename>do_package</filename> In this case, <filename>do_install</filename> and <filename>do_package</filename>
output are still valid. outputs are still valid.
However, with a per-recipe approach, the build would not include the However, with a per-recipe approach, the build would not include the
<filename>.deb</filename> files. <filename>.deb</filename> files.
Consequently, you would have to invalidate the whole build and rerun it. Consequently, you would have to invalidate the whole build and rerun it.
Rerunning everything is not the best situation. Rerunning everything is not the best solution.
Also in this case, the core must be "taught" much about specific tasks. Also, in this case, the core must be "taught" much about specific tasks.
This methodology does not scale well and does not allow users to easily add new tasks This methodology does not scale well and does not allow users to easily add new tasks
in layers or as external recipes without touching the packaged-staging core. in layers or as external recipes without touching the packaged-staging core.
</para> </para>
@ -512,17 +514,18 @@
dependent task hashes can be influenced. dependent task hashes can be influenced.
Within the BitBake configuration file, we can give BitBake some extra information Within the BitBake configuration file, we can give BitBake some extra information
to help it construct the basehash. to help it construct the basehash.
The following statements effectively result in a list of global variable The following statement effectively results in a list of global variable
dependency excludes - variables never included in any checksum: dependency excludes - variables never included in any checksum:
<literallayout class='monospaced'> <literallayout class='monospaced'>
BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH" BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \
BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS" SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \
BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER" USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \
BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET" PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \
CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX"
</literallayout> </literallayout>
The previous example actually excludes The previous example excludes
<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
since it is actually constructed as a path within since that variable is actually constructed as a path within
<link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
the whitelist. the whitelist.
</para> </para>
@ -541,7 +544,7 @@
<filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
through this setting in the <filename>bitbake.conf</filename> file: through this setting in the <filename>bitbake.conf</filename> file:
<literallayout class='monospaced'> <literallayout class='monospaced'>
BB_SIGNATURE_HANDLER ?= "OEBasicHash" BB_SIGNATURE_HANDLER ?= "OEBasicHash"
</literallayout> </literallayout>
The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
"OEBasic" version but adds the task hash to the stamp files. "OEBasic" version but adds the task hash to the stamp files.
@ -550,7 +553,7 @@
change that changes the task hash, automatically change that changes the task hash, automatically
causing the task to be run again. causing the task to be run again.
This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link> This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
values and changes to Metadata automatically ripple across the build. values, and changes to Metadata automatically ripple across the build.
</para> </para>
<para> <para>
@ -558,10 +561,10 @@
make some dependency and hash information available to the build. make some dependency and hash information available to the build.
This information includes: This information includes:
<literallayout class='monospaced'> <literallayout class='monospaced'>
BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
BB_TASKHASH - the hash of the currently running task BB_TASKHASH - the hash of the currently running task
</literallayout> </literallayout>
</para> </para>
</section> </section>
@ -571,7 +574,7 @@
<para> <para>
Checksums and dependencies, as discussed in the previous section, solve half the Checksums and dependencies, as discussed in the previous section, solve half the
problem. problem of supporting a shared state.
The other part of the problem is being able to use checksum information during the build The other part of the problem is being able to use checksum information during the build
and being able to reuse or rebuild specific components. and being able to reuse or rebuild specific components.
</para> </para>
@ -581,7 +584,7 @@
is a relatively generic implementation of how to "capture" a snapshot of a given task. is a relatively generic implementation of how to "capture" a snapshot of a given task.
The idea is that the build process does not care about the source of a task's output. The idea is that the build process does not care about the source of a task's output.
Output could be freshly built or it could be downloaded and unpacked from Output could be freshly built or it could be downloaded and unpacked from
somewhere - the build process does not need to worry about its source. somewhere - the build process does not need to worry about its origin.
</para> </para>
<para> <para>
@ -598,7 +601,7 @@
<filename>sstate.bbclass</filename>. <filename>sstate.bbclass</filename>.
From a user's perspective, adding shared state wrapping to a task From a user's perspective, adding shared state wrapping to a task
is as simple as this <filename>do_deploy</filename> example taken from is as simple as this <filename>do_deploy</filename> example taken from
<filename>do_deploy.bbclass</filename>: <filename>deploy.bbclass</filename>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
DEPLOYDIR = "${WORKDIR}/deploy-${PN}" DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
SSTATETASKS += "do_deploy" SSTATETASKS += "do_deploy"
@ -610,8 +613,9 @@
sstate_setscene(d) sstate_setscene(d)
} }
addtask do_deploy_setscene addtask do_deploy_setscene
do_deploy[dirs] = "${DEPLOYDIR} ${B}"
</literallayout> </literallayout>
In the example, we add some extra flags to the task, a name field ("deploy"), an In this example, we add some extra flags to the task, a name field ("deploy"), an
input directory where the task sends data, and the output input directory where the task sends data, and the output
directory where the data from the task should eventually be copied. directory where the data from the task should eventually be copied.
We also add a <filename>_setscene</filename> variant of the task and add the task We also add a <filename>_setscene</filename> variant of the task and add the task
@ -886,7 +890,7 @@
<para> <para>
<ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Wayland</ulink> <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Wayland</ulink>
is a computer display server protocol that when implemented is a computer display server protocol that
provides a method for compositing window managers to communicate provides a method for compositing window managers to communicate
directly with applications and video hardware and expects them to directly with applications and video hardware and expects them to
communicate with input hardware using other libraries. communicate with input hardware using other libraries.
@ -897,7 +901,7 @@
<para> <para>
The Yocto Project provides the Wayland protocol libraries and the The Yocto Project provides the Wayland protocol libraries and the
reference Weston compositor as part of it release. reference Weston compositor as part of its release.
This section describes what you need to do to implement Wayland and This section describes what you need to do to implement Wayland and
use the compositor when building an image for a supporting target. use the compositor when building an image for a supporting target.
</para> </para>
@ -992,7 +996,7 @@
<para> <para>
Alternatively, you can run Weston through the command-line Alternatively, you can run Weston through the command-line
interpretor (CLI), which is better suited for development work. interpretor (CLI), which is better suited for development work.
To run Weston under the CLI you need to do the following after To run Weston under the CLI, you need to do the following after
your image is built: your image is built:
<orderedlist> <orderedlist>
<listitem><para>Run these commands to export <listitem><para>Run these commands to export
@ -1181,7 +1185,7 @@
</literallayout> </literallayout>
As a convenience, you do not need to specify the complete license string As a convenience, you do not need to specify the complete license string
in the whitelist for every package. in the whitelist for every package.
you can use an abbreviated form, which consists You can use an abbreviated form, which consists
of just the first portion or portions of the license string before of just the first portion or portions of the license string before
the initial underscore character or characters. the initial underscore character or characters.
A partial string will match A partial string will match
@ -1203,10 +1207,10 @@
License flag matching allows you to control what recipes the License flag matching allows you to control what recipes the
OpenEmbedded build system includes in the build. OpenEmbedded build system includes in the build.
Fundamentally, the build system attempts to match Fundamentally, the build system attempts to match
<filename>LICENSE_FLAG</filename> strings found in <filename>LICENSE_FLAGS</filename> strings found in
recipes against <filename>LICENSE_FLAGS_WHITELIST</filename> recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
strings found in the whitelist. strings found in the whitelist.
A match, causes the build system to include a recipe in the A match causes the build system to include a recipe in the
build, while failure to find a match causes the build system to build, while failure to find a match causes the build system to
exclude a recipe. exclude a recipe.
</para> </para>
@ -1267,7 +1271,7 @@
<para> <para>
This scheme works even if the This scheme works even if the
<filename>LICENSE_FLAG</filename> string already <filename>LICENSE_FLAGS</filename> string already
has <filename>_${PN}</filename> appended. has <filename>_${PN}</filename> appended.
For example, the build system turns the license flag For example, the build system turns the license flag
"commercial_1.2_foo" into "commercial_1.2_foo_foo" and would "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would