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

ref-manual: various touchups, rewordings, corrections to Ch 5

Browse Source 
Minor tweaks to chapter 5 of reference manual, including:

 - grammar
 - adding slashes to directory names for consistency
 - collapse trivial paras into one

(From yocto-docs rev: 96b75e723bff042183f70a858d09df4aad094578)

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
rpjday@crashcourse.ca
2020-03-23 07:17:18 -04:00
committed by Richard Purdie
parent a5ac4b6fca
commit f63d44ab32
1 changed files with 63 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
documentation/ref-manual/ref-structure.xml
View File

@@ -8,11 +8,11 @@
<para> <para>
The <link linkend='source-directory'>Source Directory</link> The <link linkend='source-directory'>Source Directory</link>
consists of several components. consists of numerous files, directories and subdirectories;
Understanding them and knowing where they are located is key to using the understanding their locations and contents is key to using the
Yocto Project well. Yocto Project effectively.
This chapter describes the Source Directory and gives information about This chapter describes the Source Directory and gives information about
the various files and directories. those files and directories.
</para> </para>
<para> <para>
@@ -22,12 +22,12 @@
section in the Yocto Project Development Tasks Manual. section in the Yocto Project Development Tasks Manual.
</para> </para>
<note> <note>
The OpenEmbedded build system does not support file or directory names that The OpenEmbedded build system does not support file or directory names that
contain spaces. contain spaces.
Be sure that the Source Directory you use does not contain these types Be sure that the Source Directory you use does not contain these types
of names. of names.
</note> </note>
<section id='structure-core'> <section id='structure-core'>
<title>Top-Level Core Components</title> <title>Top-Level Core Components</title>
@@ -48,18 +48,18 @@
<link linkend='metadata'>Metadata</link> <link linkend='metadata'>Metadata</link>
interpreter, reads the Yocto Project Metadata and runs the tasks interpreter, reads the Yocto Project Metadata and runs the tasks
defined by that data. defined by that data.
Failures are usually from the Metadata and not from BitBake itself. Failures are usually caused by errors in your Metadata and not from BitBake itself;
Consequently, most users do not need to worry about BitBake. consequently, most users do not need to worry about BitBake.
</para> </para>
<para> <para>
When you run the <filename>bitbake</filename> command, the When you run the <filename>bitbake</filename> command, the
main BitBake executable, which resides in the main BitBake executable (which resides in the
<filename>bitbake/bin/</filename> directory, starts. <filename>bitbake/bin/</filename> directory) starts.
Sourcing the environment setup script (i.e. Sourcing the environment setup script (i.e.
<link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>) <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>)
places the <filename>scripts</filename> and places the <filename>scripts/</filename> and
<filename>bitbake/bin</filename> directories (in that order) into <filename>bitbake/bin/</filename> directories (in that order) into
the shell's <filename>PATH</filename> environment variable. the shell's <filename>PATH</filename> environment variable.
</para> </para>
@@ -91,7 +91,7 @@
by providing a directory name when you <filename>source</filename> by providing a directory name when you <filename>source</filename>
the setup script. the setup script.
For information on separating output from your local For information on separating output from your local
Source Directory files, see the Source Directory files (commonly described as an "out of tree" build), see the
"<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>" "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
section. section.
</para> </para>
@@ -104,8 +104,8 @@
This directory holds the source for the Yocto Project documentation This directory holds the source for the Yocto Project documentation
as well as templates and tools that allow you to generate PDF and HTML as well as templates and tools that allow you to generate PDF and HTML
versions of the manuals. versions of the manuals.
Each manual is contained in a sub-folder. Each manual is contained in its own sub-folder;
For example, the files for this manual reside in for example, the files for this reference manual reside in
the <filename>ref-manual/</filename> directory. the <filename>ref-manual/</filename> directory.
</para> </para>
</section> </section>
@@ -114,9 +114,9 @@
<title><filename>meta/</filename></title> <title><filename>meta/</filename></title>
<para> <para>
This directory contains the OpenEmbedded-Core metadata. This directory contains the minimal, underlying OpenEmbedded-Core metadata.
The directory holds recipes, common classes, and machine The directory holds recipes, common classes, and machine
configuration for emulated targets (<filename>qemux86</filename>, configuration for strictly emulated targets (<filename>qemux86</filename>,
<filename>qemuarm</filename>, and so forth.) <filename>qemuarm</filename>, and so forth.)
</para> </para>
</section> </section>
@@ -125,8 +125,8 @@
<title><filename>meta-poky/</filename></title> <title><filename>meta-poky/</filename></title>
<para> <para>
This directory contains the configuration for the Poky Designed above the <filename>meta/</filename> content, this directory
reference distribution. adds just enough metadata to define the Poky reference distribution.
</para> </para>
</section> </section>
@@ -148,9 +148,6 @@
This directory adds additional recipes and append files This directory adds additional recipes and append files
used by the OpenEmbedded selftests to verify the behavior used by the OpenEmbedded selftests to verify the behavior
of the build system. of the build system.
</para>
<para>
You do not have to add this layer to your You do not have to add this layer to your
<filename>bblayers.conf</filename> file unless you want to run the <filename>bblayers.conf</filename> file unless you want to run the
selftests. selftests.
@@ -172,7 +169,7 @@
This directory contains various integration scripts that implement This directory contains various integration scripts that implement
extra functionality in the Yocto Project environment (e.g. QEMU scripts). extra functionality in the Yocto Project environment (e.g. QEMU scripts).
The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link> The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
script appends this directory to the shell's script prepends this directory to the shell's
<filename>PATH</filename> environment variable. <filename>PATH</filename> environment variable.
</para> </para>
@@ -202,7 +199,8 @@
up, a up, a
<link linkend='build-directory'>Build Directory</link> <link linkend='build-directory'>Build Directory</link>
is created, your working directory becomes the Build Directory, is created, your working directory becomes the Build Directory,
and you are presented with a list of common BitBake targets. and you are presented with some simple suggestions as to what to do
next, including a list of some possible targets to build.
Here is an example: Here is an example:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ source oe-init-build-env $ source oe-init-build-env
@@ -219,12 +217,12 @@
You can also run generated qemu images with a command like 'runqemu qemux86-64' You can also run generated qemu images with a command like 'runqemu qemux86-64'
</literallayout> </literallayout>
The script gets its default list of common targets from the The default output of the <filename>oe-init-build-env</filename> script
<filename>conf-notes.txt</filename> file, which is found in the is from the <filename>conf-notes.txt</filename> file, which is found in the
<filename>meta-poky</filename> directory within the <filename>meta-poky</filename> directory within the
<link linkend='source-directory'>Source Directory</link>. <link linkend='source-directory'>Source Directory</link>.
Should you have custom distributions, it is very easy to modify If you design a custom distribution, you can include your own version
this configuration file to include your targets for your of this configuration file to mention the targets defined by your
distribution. distribution.
See the See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
@@ -234,20 +232,20 @@
<para> <para>
By default, running this script without a Build Directory By default, running this script without a Build Directory
argument creates the <filename>build</filename> directory argument creates the <filename>build/</filename> directory
in your current working directory. in your current working directory.
If you provide a Build Directory argument when you If you provide a Build Directory argument when you
<filename>source</filename> the script, you direct the OpenEmbedded <filename>source</filename> the script, you direct the OpenEmbedded
build system to create a Build Directory of your choice. build system to create a Build Directory of your choice.
For example, the following command creates a Build Directory named For example, the following command creates a Build Directory named
<filename>mybuilds</filename> that is outside of the <filename>mybuilds/</filename> that is outside of the
<link linkend='source-directory'>Source Directory</link>: <link linkend='source-directory'>Source Directory</link>:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ source &OE_INIT_FILE; ~/mybuilds $ source &OE_INIT_FILE; ~/mybuilds
</literallayout> </literallayout>
The OpenEmbedded build system uses the template configuration The OpenEmbedded build system uses the template configuration
files, which are found by default in the files, which are found by default in the
<filename>meta-poky/conf</filename> directory in the <filename>meta-poky/conf/</filename> directory in the
Source Directory. Source Directory.
See the See the
"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
@@ -280,28 +278,26 @@
<para> <para>
The OpenEmbedded build system creates the The OpenEmbedded build system creates the
<link linkend='build-directory'>Build Directory</link> <link linkend='build-directory'>Build Directory</link>
when you run the build environment setup scripts (i.e. when you run the build environment setup script
<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). <link
</para> linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
<para>
If you do not give the Build Directory a specific name when you run If you do not give the Build Directory a specific name when you run
a setup script, the name defaults to <filename>build</filename>. the setup script, the name defaults to <filename>build/</filename>.
</para> </para>
<para> <para>
The For subsequent parsing and processing, the name of the Build
<link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable directory is available via the
points to the Build Directory. <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable.
</para> </para>
<section id='structure-build-buildhistory'> <section id='structure-build-buildhistory'>
<title><filename>build/buildhistory</filename></title> <title><filename>build/buildhistory/</filename></title>
<para> <para>
The OpenEmbedded build system creates this directory when you The OpenEmbedded build system creates this directory when you
enable the build history feature. enable build history via the <filename>buildhistory</filename> class file.
The directory tracks build information into image, packages, and The directory organizes build information into image, packages, and
SDK subdirectories. SDK subdirectories.
For information on the build history feature, see the For information on the build history feature, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
@@ -320,14 +316,14 @@
Any variable set here overrides any variable set elsewhere within Any variable set here overrides any variable set elsewhere within
the environment unless that variable is hard-coded within a file the environment unless that variable is hard-coded within a file
(e.g. by using '=' instead of '?='). (e.g. by using '=' instead of '?=').
Some variables are hard-coded for various reasons but these Some variables are hard-coded for various reasons but such
variables are relatively rare. variables are relatively rare.
</para> </para>
<para> <para>
Edit this file to set the At a minimum, you would normally edit this file to select the target
<filename><link linkend='var-MACHINE'>MACHINE</link></filename> <filename><link linkend='var-MACHINE'>MACHINE</link></filename>,
for which you want to build, which package types you wish to use which package types you wish to use
(<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
and the location from which you want to access downloaded files and the location from which you want to access downloaded files
(<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>). (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>).
@@ -338,16 +334,16 @@
start the build, the OpenEmbedded build system creates it from start the build, the OpenEmbedded build system creates it from
<filename>local.conf.sample</filename> when <filename>local.conf.sample</filename> when
you <filename>source</filename> the top-level build environment you <filename>source</filename> the top-level build environment
setup script (i.e. setup script
<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
</para> </para>
<para> <para>
The source <filename>local.conf.sample</filename> file used The source <filename>local.conf.sample</filename> file used
depends on the <filename>$TEMPLATECONF</filename> script variable, depends on the <filename>$TEMPLATECONF</filename> script variable,
which defaults to <filename>meta-poky/conf</filename> which defaults to <filename>meta-poky/conf/</filename>
when you are building from the Yocto Project development when you are building from the Yocto Project development
environment and defaults to <filename>meta/conf</filename> when environment, and to <filename>meta/conf/</filename> when
you are building from the OpenEmbedded-Core environment. you are building from the OpenEmbedded-Core environment.
Because the script variable points to the source of the Because the script variable points to the source of the
<filename>local.conf.sample</filename> file, this implies that <filename>local.conf.sample</filename> file, this implies that
@@ -395,11 +391,12 @@
</para> </para>
<para> <para>
The source <filename>bblayers.conf.sample</filename> file used As with the <filename>local.conf</filename> file,
the source <filename>bblayers.conf.sample</filename> file used
depends on the <filename>$TEMPLATECONF</filename> script variable, depends on the <filename>$TEMPLATECONF</filename> script variable,
which defaults to <filename>meta-poky/conf</filename> which defaults to <filename>meta-poky/conf/</filename>
when you are building from the Yocto Project development when you are building from the Yocto Project development
environment and defaults to <filename>meta/conf</filename> when environment, and to <filename>meta/conf/</filename> when
you are building from the OpenEmbedded-Core environment. you are building from the OpenEmbedded-Core environment.
Because the script variable points to the source of the Because the script variable points to the source of the
<filename>bblayers.conf.sample</filename> file, this implies that <filename>bblayers.conf.sample</filename> file, this implies that
@@ -418,7 +415,7 @@
<link linkend='source-directory'>Source Directory</link>. <link linkend='source-directory'>Source Directory</link>.
You can find the Yocto Project version of the You can find the Yocto Project version of the
<filename>bblayers.conf.sample</filename> file in the <filename>bblayers.conf.sample</filename> file in the
<filename>meta-poky/conf</filename> directory. <filename>meta-poky/conf/</filename> directory.
</note> </note>
</para> </para>
</section> </section>
@@ -572,8 +569,11 @@
<title><filename>build/tmp/deploy/images/</filename></title> <title><filename>build/tmp/deploy/images/</filename></title>
<para> <para>
This directory receives complete filesystem images. This directory is populated with the basic output objects of the
If you want to flash the resulting image from a build onto a device, look here for the image. build (think of them as the "generated artifacts" of the build process),
including things like the boot loader image, kernel, root filesystem and more.
If you want to flash the resulting image from a build onto a device,
look here for the necessary components.
</para> </para>
<para> <para>
@@ -604,7 +604,7 @@
<para> <para>
The OpenEmbedded build system creates this directory to hold The OpenEmbedded build system creates this directory to hold
toolchain installer scripts, which when executed, install the toolchain installer scripts which, when executed, install the
sysroot that matches your target hardware. sysroot that matches your target hardware.
You can find out more about these installers in the You can find out more about these installers in the
"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
@@ -1038,7 +1038,7 @@
<title><filename>meta/recipes-graphics/</filename></title> <title><filename>meta/recipes-graphics/</filename></title>
<para> <para>
This directory contains X and other graphically related system libraries This directory contains X and other graphically related system libraries.
</para> </para>
</section> </section>