diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 17f96b52ff..583d204566 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -153,6 +153,216 @@ +
+ A Closer Look at the Yocto Project Development Environment + + + This section is a work-in-progress for an expanded discussion of the + Yocto Project Development Environment. + The section is rooted in the figure found in the + "Introducing the Yocto Project Development Environment" + section of the Yocto Project Quick Start. + This expanded discussion presents a deeper level of detail regarding + sources of input, generated output, and controlling + Metadata. + + + + I will either replicate the exact figure from the YP Quick Start here + or I will create a more simplified version that can be used as the + top-level diagram from which to base subsequent sections and expanded + illustrations. + + + + [NEED REPEATED FIGURE HERE OR A NEW FIGURE] + + + + This paragraph will introduce the main blocks of the preceding figure + to overview and organize the remainder of the section: + + User Configuration: + Methods by with the user can directly control the build + process. + Metadata Layers: + Various layers that provide software, machine, and + distro Metadata. + Soure Files: + Upstream releases, local projects, and SCMs. + Build System: + Processes inside the BitBake "box". + This block expands on how BitBake fetches source, applies + patches, completes compilation, analyzes output for package + generation, creates and tests packages, generates images, and + generates cross-development tools. + Package Feeds + Package feeds into the BitBake process. + Images + Images produced by the development process. + Where do they go? + Can you mess with them (i.e. freely delete them or move them?). + + Application Development SDK + Cross-development tools that are produced along with an image + or separately with BitBake. + + + +
+ User Configuration + + + User configuration affects how you define the build. + The following figure shows an expanded representation of the + user configuration in the Yocto Project development environment: + + + + + + + + + + BitBake needs some basic configuration files in order to complete + a build. + These files are *.conf files and the + minimally necessary ones reside as example files in the + Source Directory. + For simplicity, this section refers to the Source Directory as + the "Poky Directory." + + Poky is primarily an aggregation of existing repositories and + is not actual canonical upstream source for anything. + + When you clone the poky Git repository or you + download and unpack a Yocto Project release, you can set up the + Source Directory to be named anything you want. + Here, though, we will assume that you have a cloned repository that + has the default name poky. + + + + The meta-yocto layer inside Poky contains + a conf directory that has example + configuration files. + These example files are used as a basis for creating actual + configuration files when you source the build environment + script oe-init-build-env. + + The oe-init-build-env script also exists + in the meta directory of the OE-Core + root directory. + Both scripts look for sample configuration files through + a $TEMPLATECONF variable. + When using the Yocto Project Development Environment, + that location resolves to the samples found in the + poky/meta-yocto/conf directory. + + + + + When you source the build environment script, it creates a + Build Directory + that BitBake uses as the area in which it does all its work + during builds. + The Build Directory has a conf directory that + contains default versions of your local.conf + and bblayers.conf configuration files. + These default configuration files are created by + oe-init-build-env only if versions of these + files do not already exist in the Build Directory you specify + when you run the script. + + + + The local.conf file provides many + basic variables that define your build. + Here is a list of a few. + To see the default configurations in a local.conf + file created by the build environment script, see the + local.conf.sample in the + meta-yocto layer: + + Parallelism Options: + Controlled by the + BB_NUMBER_THREADS + and + PARALLEL_MAKE + variables. + Target Machine Selection: + Controlled by the + MACHINE + variable. + Download Directory: + Controlled by the + DL_DIR + variable. + Shared State Directory: + Controlled by the + SSTATE_DIR + variable. + Build Output: + Controlled by the + TMPDIR + variable. + + + + + The bblayers.conf file tells BitBake what + layers you want it to consider during the build. + The list of layers includes default layers needed by the build + system. + You have to manually add any custom layers that you have created. + You can find more information on working with the + bblayers.conf file in the + "Enabling Your Layer" + section in the Yocto Project Development Manual. + + + + The files site.conf and + auto.conf are not created by the environment + initialization script. + If you want these configuration files, you must create them + yourself. + Here a bit about what these files do: + + site.conf: + I don't really know what this does. + All I know is that if you want it, you need to hand-create + it. + I need some information on it. + auto.conf: + This file is not hand-created. + Rather, the file is usually created and written to by + an autobuilder. + The settings put into the file are typically the same as + you would find in the local.conf + or site.conf files. + + + + + + All configuration files can undergo edits to further define + the build. + This process is represented by the "User Configuration Edits" + box in the figure. + + + + When you launch your build with the + bitbake <target> command, BitBake + draws on the user configurations you have provided in your + Build Directory. + +
+
+
Cross-Development Toolchain Generation