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