diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-07-08 21:42:32 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-08-13 13:18:38 +0100 |
commit | 95cdad1c2edd8f4698a245ad88e2bccb0cf93e6d (patch) | |
tree | 8512729b5bbaa456237435d0ede335090a76a2d2 /documentation | |
parent | 482943bd2cd8b5a39dd8d8aa3ad1111fa3c72038 (diff) | |
download | ast2050-yocto-poky-95cdad1c2edd8f4698a245ad88e2bccb0cf93e6d.zip ast2050-yocto-poky-95cdad1c2edd8f4698a245ad88e2bccb0cf93e6d.tar.gz |
ref-manual: Start of new section on deeper look into dev env.
Start of the new section on the closer look into the development
environment.
(From yocto-docs rev: e1f1cee951433144d1adedcb4f0bbc8d8296c444)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/ref-manual/technical-details.xml | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 17f96b5..583d204 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -153,6 +153,216 @@ </section> </section> +<section id="a-closer-look-at-the-yocto-project-development-environment"> + <title>A Closer Look at the Yocto Project Development Environment</title> + + <para> + 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 + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-intro'>Introducing the Yocto Project Development Environment</ulink>" + section of the Yocto Project Quick Start. + This expanded discussion presents a deeper level of detail regarding + sources of input, generated output, and controlling + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>. + </para> + + <para> + 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. + </para> + + <para> + [NEED REPEATED FIGURE HERE OR A NEW FIGURE] + </para> + + <para> + This paragraph will introduce the main blocks of the preceding figure + to overview and organize the remainder of the section: + <itemizedlist> + <listitem><para><emphasis>User Configuration:</emphasis> + Methods by with the user can directly control the build + process.</para></listitem> + <listitem><para><emphasis>Metadata Layers:</emphasis> + Various layers that provide software, machine, and + distro Metadata.</para></listitem> + <listitem><para><emphasis>Soure Files:</emphasis> + Upstream releases, local projects, and SCMs.</para></listitem> + <listitem><para><emphasis>Build System:</emphasis> + 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.</para></listitem> + <listitem><para><emphasis>Package Feeds</emphasis> + Package feeds into the BitBake process.</para></listitem> + <listitem><para><emphasis>Images</emphasis> + Images produced by the development process. + Where do they go? + Can you mess with them (i.e. freely delete them or move them?). + </para></listitem> + <listitem><para><emphasis>Application Development SDK</emphasis> + Cross-development tools that are produced along with an image + or separately with BitBake.</para></listitem> + </itemizedlist> + </para> + + <section id="user-configuration"> + <title>User Configuration</title> + + <para> + 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: + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="figures/user-configuration.png" + format="PNG" align='center' scalefit='1' width="100%"/> + </imageobject> + </mediaobject> + + <para> + BitBake needs some basic configuration files in order to complete + a build. + These files are <filename>*.conf</filename> files and the + minimally necessary ones reside as example files in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + For simplicity, this section refers to the Source Directory as + the "Poky Directory." + <note> + Poky is primarily an aggregation of existing repositories and + is not actual canonical upstream source for anything. + </note> + When you clone the <filename>poky</filename> 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 <filename>poky</filename>. + </para> + + <para> + The <filename>meta-yocto</filename> layer inside Poky contains + a <filename>conf</filename> 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 <filename>oe-init-build-env</filename>. + <note> + The <filename>oe-init-build-env</filename> script also exists + in the <filename>meta</filename> directory of the OE-Core + root directory. + Both scripts look for sample configuration files through + a <filename>$TEMPLATECONF</filename> variable. + When using the Yocto Project Development Environment, + that location resolves to the samples found in the + <filename>poky/meta-yocto/conf</filename> directory. + </note> + </para> + + <para> + When you source the build environment script, it creates a + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + that BitBake uses as the area in which it does all its work + during builds. + The Build Directory has a <filename>conf</filename> directory that + contains default versions of your <filename>local.conf</filename> + and <filename>bblayers.conf</filename> configuration files. + These default configuration files are created by + <filename>oe-init-build-env</filename> only if versions of these + files do not already exist in the Build Directory you specify + when you run the script. + </para> + + <para> + The <filename>local.conf</filename> file provides many + basic variables that define your build. + Here is a list of a few. + To see the default configurations in a <filename>local.conf</filename> + file created by the build environment script, see the + <filename>local.conf.sample</filename> in the + <filename>meta-yocto</filename> layer: + <itemizedlist> + <listitem><para><emphasis>Parallelism Options:</emphasis> + Controlled by the + <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> + and + <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> + variables.</para></listitem> + <listitem><para><emphasis>Target Machine Selection:</emphasis> + Controlled by the + <link linkend='var-MACHINE'><filename>MACHINE</filename></link> + variable.</para></listitem> + <listitem><para><emphasis>Download Directory:</emphasis> + Controlled by the + <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link> + variable.</para></listitem> + <listitem><para><emphasis>Shared State Directory:</emphasis> + Controlled by the + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + variable.</para></listitem> + <listitem><para><emphasis>Build Output:</emphasis> + Controlled by the + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + variable.</para></listitem> + </itemizedlist> + </para> + + <para> + The <filename>bblayers.conf</filename> 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 + <filename>bblayers.conf</filename> file in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>" + section in the Yocto Project Development Manual. + </para> + + <para> + The files <filename>site.conf</filename> and + <filename>auto.conf</filename> 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: + <itemizedlist> + <listitem><para><emphasis><filename>site.conf</filename>:</emphasis> + 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.</para></listitem> + <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis> + 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 <filename>local.conf</filename> + or <filename>site.conf</filename> files. + </para></listitem> + </itemizedlist> + </para> + + <para> + All configuration files can undergo edits to further define + the build. + This process is represented by the "User Configuration Edits" + box in the figure. + </para> + + <para> + When you launch your build with the + <filename>bitbake <target></filename> command, BitBake + draws on the user configurations you have provided in your + Build Directory. + </para> + </section> +</section> + <section id="cross-development-toolchain-generation"> <title>Cross-Development Toolchain Generation</title> |