From f63d44ab32a4438c3b0708e6bf759b4d6ff01bf0 Mon Sep 17 00:00:00 2001 From: "rpjday@crashcourse.ca" Date: Mon, 23 Mar 2020 07:17:18 -0400 Subject: ref-manual: various touchups, rewordings, corrections to Ch 5 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 Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-structure.xml | 126 ++++++++++++++--------------- 1 file changed, 63 insertions(+), 63 deletions(-) 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 @@ <filename>meta/</filename> - 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 @@ <filename>meta-poky/</filename> - 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.
- <filename>build/buildhistory</filename> + <filename>build/buildhistory/</filename> 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 @@ <filename>build/tmp/deploy/images/</filename> - 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 @@ <filename>meta/recipes-graphics/</filename> - This directory contains X and other graphically related system libraries + This directory contains X and other graphically related system libraries. -- cgit v1.2.3-54-g00ecf