[poky] [PATCH 031/186] ref-manual: Start of new section on deeper look into dev env.
Stoicescu Cornel
corneliux.stoicescu at intel.com
Tue Aug 20 02:45:13 PDT 2013
From: Scott Rifenbark <scott.m.rifenbark at intel.com>
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 at intel.com>
Signed-off-by: Richard Purdie <richard.purdie at linuxfoundation.org>
---
documentation/ref-manual/technical-details.xml | 210 ++++++++++++++++++++++++
1 file changed, 210 insertions(+)
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>
--
1.7.9.5
More information about the poky
mailing list