mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-04-30 12:32:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

concepts-manual: General edits

Browse Source 
Removed redundant links, changed some wordings.  This was a general
scrub of the prose.

(From yocto-docs rev: 2c0ff0af7df3aa46fc05aaf28039a2ffb380424a)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2018-01-31 13:03:11 -08:00
committed by Richard Purdie
parent d74420e778
commit 01a70aaea9
1 changed files with 58 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
documentation/concepts-manual/concepts-manual-concepts.xml
View File

@@ -5,13 +5,6 @@
<chapter id=' concepts-manual-concepts'>
<title>Yocto Project Concepts</title>
<para>
This chapter describes concepts for various areas of the Yocto Project.
Currently, topics include Yocto Project components, cross-development
generation, shared state (sstate) cache, runtime dependencies,
Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses.
</para>
<section id='yocto-project-components'>
<title>Yocto Project Components</title>
@@ -67,8 +60,9 @@
<title>BitBake</title>
<para>
BitBake is the tool at the heart of the OpenEmbedded build
system and is responsible for parsing the
BitBake is the tool at the heart of the
<ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
and is responsible for parsing the
<ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>,
generating a list of tasks from it, and then executing those
tasks.
@@ -93,8 +87,7 @@
The most common usage for BitBake is
<filename>bitbake <replaceable>packagename</replaceable></filename>,
where <filename>packagename</filename> is the name of the
package you want to build (referred to as the "target" in this
manual).
package you want to build (referred to as the "target").
The target often equates to the first part of a recipe's
filename (e.g. "foo" for a recipe named
<filename>foo_1.3.0-r0.bb</filename>).
@@ -180,8 +173,10 @@
in the build's configuration file (e.g.
<filename>poky/build/conf/local.conf</filename>).
<note>
Any recipe that PROVIDES a <filename>virtual/*</filename>
item that is ultimately not selected through
Any recipe that
<ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
a <filename>virtual/*</filename> item that is ultimately
not selected through
<filename>PREFERRED_PROVIDER</filename> does not get built.
Preventing these recipes from building is usually the
desired behavior since this mechanism's purpose is to
@@ -224,9 +219,7 @@
<para>
Class files (<filename>.bbclass</filename>) contain information
that is useful to share between
<ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
files.
that is useful to share between Metadata files.
An example is the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink>
class, which contains common settings for any application that
@@ -288,16 +281,18 @@
<para>
Most of the work occurs on the Build Host.
This is the machine used to build images and generally work within the
the Yocto Project environment.
When you run BitBake to create an image, the OpenEmbedded build system
This is the machine used to build images and generally work within
the the Yocto Project environment.
When you run
<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
to create an image, the OpenEmbedded build system
uses the host <filename>gcc</filename> compiler to bootstrap a
cross-compiler named <filename>gcc-cross</filename>.
The <filename>gcc-cross</filename> compiler is what BitBake uses to
compile source files when creating the target image.
You can think of <filename>gcc-cross</filename> simply as an
automatically generated cross-compiler that is used internally within
BitBake only.
automatically generated cross-compiler that is used internally
within BitBake only.
<note>
The extensible SDK does not use
<filename>gcc-cross-canadian</filename> since this SDK
@@ -370,11 +365,11 @@
<para>
You can use the OpenEmbedded build system to build an installer for
the relocatable SDK used to develop applications.
When you run the installer, it installs the toolchain, which contains
the development tools (e.g., the
<filename>gcc-cross-canadian</filename>),
When you run the installer, it installs the toolchain, which
contains the development tools (e.g.,
<filename>gcc-cross-canadian</filename>,
<filename>binutils-cross-canadian</filename>, and other
<filename>nativesdk-*</filename> tools,
<filename>nativesdk-*</filename> tools),
which are tools native to the SDK (i.e. native to
<ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_ARCH'><filename>SDK_ARCH</filename></ulink>),
you need to cross-compile and test your software.
@@ -476,8 +471,9 @@
<para>
By design, the OpenEmbedded build system builds everything from
scratch unless BitBake can determine that parts do not need to be
rebuilt.
scratch unless
<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
can determine that parts do not need to be rebuilt.
Fundamentally, building from scratch is attractive as it means all
parts are built fresh and there is no possibility of stale data
causing problems.
@@ -518,9 +514,10 @@
</para>
<para>
For the first question, the build system detects changes in the
"inputs" to a given task by creating a checksum (or signature) of
the task's inputs.
For the first question, the
<ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
detects changes in the "inputs" to a given task by creating a
checksum (or signature) of the task's inputs.
If the checksum changes, the system assumes the inputs have changed
and the task needs to be rerun.
For the second question, the shared state (sstate) code tracks
@@ -607,7 +604,8 @@
Also, the build process has the objective of making native
or cross packages relocatable.
<note>
Both native and cross packages run on the build host.
Both native and cross packages run on the
<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>.
However, cross packages generate output for the target
architecture.
</note>
@@ -629,7 +627,7 @@
</para>
<para>
So far we have solutions for shell scripts.
So far, solutions for shell scripts exist.
What about Python tasks?
The same approach applies even though these tasks are more
difficult.
@@ -643,7 +641,7 @@
<para>
Like the <filename>WORKDIR</filename> case, situations exist
where dependencies should be ignored.
For these cases, you can instruct the build process to
For these situations, you can instruct the build process to
ignore a dependency by using a line like the following:
<literallayout class='monospaced'>
PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
@@ -656,7 +654,7 @@
</para>
<para>
Equally, there are cases where we need to add dependencies
Equally, there are cases where you need to add dependencies
BitBake is not able to find.
You can accomplish this by using a line like the following:
<literallayout class='monospaced'>
@@ -668,7 +666,7 @@
</para>
<para>
Consider a case with in-line Python, for example, where
As an example, consider a case with in-line Python where
BitBake is not able to figure out dependencies.
When running in debug mode (i.e. using
<filename>-DDD</filename>), BitBake produces output when it
@@ -696,9 +694,9 @@
</para>
<para>
At the code level, there are a variety of ways both the
At the code level, a variety of ways exist by which both the
basehash and the dependent task hashes can be influenced.
Within the BitBake configuration file, we can give BitBake
Within the BitBake configuration file, you can give BitBake
some extra information to help it construct the basehash.
The following statement effectively results in a list of
global variable dependency excludes - variables never
@@ -799,8 +797,8 @@
</para>
<para>
There are two types of output, one is just about creating a
directory in
Two types of output exist.
One type is just about creating a directory in
<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
A good example is the output of either
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
@@ -1156,8 +1154,7 @@
current version of the package that provides the shared
library must be used, as if
"<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)"
had been added to
<ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>.
had been added to <filename>RDEPENDS</filename>.
This forces an upgrade of the package containing the shared
library when installing the package that depends on the
library, if needed.</para>
@@ -1170,18 +1167,15 @@
</para></listitem>
<listitem><para>
<filename>pcdeps</filename>:
During the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
task of each recipe, all pkg-config modules
During the <filename>do_package</filename> task of each
recipe, all pkg-config modules
(<filename>*.pc</filename> files) installed by the recipe
are located.
For each module, the package that contains the module is
registered as providing the module.
The resulting module-to-package mapping is saved globally in
<ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
by the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
task.</para>
<filename>PKGDATA_DIR</filename> by the
<filename>do_packagedata</filename> task.</para>
<para>Simultaneously, all pkg-config modules installed by
the recipe are inspected to see what other pkg-config
@@ -1238,8 +1232,7 @@
<para>
The <filename>do_package</filename> task depends on the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-packagedata'><filename>do_packagedata</filename></ulink>
task of each recipe in
<filename>do_packagedata</filename> task of each recipe in
<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
through use of a
<filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
@@ -1268,7 +1261,9 @@
<para>
One approach to allowing tasks to perform root-only operations
would be to require BitBake to run as root.
would be to require
<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
to run as root.
However, this method is cumbersome and has security issues.
The approach that is actually used is to run tasks that benefit
from root privileges in a "fake" root environment.
@@ -1288,8 +1283,9 @@
</para>
<para>
In the OpenEmbedded build system, the program that implements
fakeroot is known as Pseudo.
In the
<ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>,
the program that implements fakeroot is known as Pseudo.
Pseudo overrides system calls by using the environment variable
<filename>LD_PRELOAD</filename>, which results in the illusion
of running as root.
@@ -1469,8 +1465,9 @@
<title>Licenses</title>
<para>
This section describes the mechanism by which the OpenEmbedded
build system tracks changes to licensing text.
This section describes the mechanism by which the
<ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
tracks changes to licensing text.
The section also describes how to enable commercially licensed
recipes, which by default are disabled.
</para>
@@ -1611,7 +1608,9 @@
<itemizedlist>
<listitem><para>
If you specify an empty or invalid "md5"
parameter, BitBake returns an md5 mis-match
parameter,
<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
returns an md5 mis-match
error and displays the correct "md5" parameter
value during the build.
The correct parameter is also captured in
@@ -1704,9 +1703,8 @@
License flag matching allows you to control what recipes
the OpenEmbedded build system includes in the build.
Fundamentally, the build system attempts to match
<ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
strings found in recipes against
<ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
<filename>LICENSE_FLAGS</filename> strings found in recipes
against <filename>LICENSE_FLAGS_WHITELIST</filename>
strings found in the whitelist.
A match causes the build system to include a recipe in the
build, while failure to find a match causes the build
@@ -1834,8 +1832,7 @@
Of course, you could also create a matching whitelist
for those components using the more general "commercial"
in the whitelist, but that would also enable all the
other packages with
<ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
other packages with <filename>LICENSE_FLAGS</filename>
containing "commercial", which you may or may not want:
<literallayout class='monospaced'>
LICENSE_FLAGS_WHITELIST = "commercial"