documentation/dev-manual/dev-manual-newbie.xml: edits to build dir term

I beefed up the definition for the term "Yocto Project Build
Directory."  I included the TOPDIR role and also expanded the
discussion on how it is created and the control the user has
over it.

(From yocto-docs rev: d00f30708ccd5fb9e1fc3c8e5240e0ab7a892fe0)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 125 insertions, 111 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 05dccc9745..6017ae9ede 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -130,106 +130,104 @@
         Following is a list of terms and definitions users new to the Yocto Project development 
         environment might find helpful.
         While some of these terms are universal, the list includes them just in case:
-    <itemizedlist>
-        <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to 
-            a recipe file.  
-            Information in append files overrides the information in the similarly-named recipe file.
-            Append files use the <filename>.bbappend</filename> filename suffix.</para></listitem>
-        <listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by 
-            the Yocto Project to build images. 
-            For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'>
-            BitBake documentation</ulink>.</para></listitem>
-        <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
-            and inheritance allowing commonly used patterns to be defined once and easily used 
-            in multiple recipes.  
-            Class files end with the <filename>.bbclass</filename> filename extension.</para></listitem>
-        <listitem><para><emphasis>Configuration File:</emphasis>  Configuration information in various
-            <filename>.conf</filename> files provides global definitions of variables.
-            The <filename>conf/local.conf</filename> configuration file in the Yocto Project
-            build directory contains user-defined variables that affect each build.
-            The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
-            defines Yocto ‘distro’ configuration
-            variables used only when building with this policy.  
-            Machine configuration files, which 
-            are located throughout the Yocto Project file structure, define
-            variables for specific hardware and are only used when building for that target 
-            (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines 
-            variables for the Texas Instruments ARM Cortex-A8 development board).  
-            Configuration files end with a <filename>.conf</filename> filename extension.</para></listitem>
-        <listitem><para><emphasis>Cross-Development Toolchain:</emphasis> A collection of software development
-            tools and utilities that allow you to develop software for targeted architectures.
-            This toolchain contains cross-compilers, linkers, and debuggers that are specific to 
-            an architecture.
-            You can use the Yocto Project to build cross-development toolchains in tarball form that when 
-            unpacked contain the development tools you need to cross-compile and test your software.
-            The Yocto Project ships with images that contain toolchains for supported architectures
-            as well.
-            Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem>
-        <listitem><para><emphasis>Image:</emphasis> An image is the result produced when 
-            BitBake processes a given collection of recipes and related metadata.
-            Images are the binary output that runs on specific hardware and for specific
-            use cases.
-            For a list of the supported image types that the Yocto Project provides, see the
-            "<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>"
-            appendix in The Yocto Project Reference Manual.</para></listitem>
-        <listitem><para><emphasis>Layer:</emphasis> A collection of recipes representing the core, 
-            a BSP, or an application stack.</para></listitem>
-        <listitem><para><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image. 
-            Metadata includes recipes, classes, and configuration files.</para></listitem>
-        <listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating 
-            with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
-            This metadata is found in the <filename>meta</filename> directory of the Yocto Project
-            files.</para></listitem>
-        <listitem><para><emphasis>Package:</emphasis> The packaged output from a baked recipe.
-            A package is generally the compiled binaries produced from the recipe's sources.  
-            You ‘bake’ something by running it through BitBake.</para></listitem>
-        <listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project 
-            uses to create images.</para></listitem>
-        <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.  
-            A recipe describes where you get source code and which patches to apply.
-            Recipes describe dependencies for libraries or for other recipes, and they 
-            also contain configuration and compilation options.  
-            Recipes contain the logical unit of execution, the software/images to build, and 
-            use the <filename>.bb</filename> file extension.</para></listitem>
-        <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.  
-            You simply use Tasks to hold recipes that, when built, usually accomplish a single task.  
-            For example, a task could contain the recipes for a company’s proprietary or value-add software.  
-            Or, the task could contain the recipes that enable graphics. 
-            A task is really just another recipe.  
-            Because task files are recipes, they end with the <filename>.bb</filename> filename 
-            extension.</para></listitem>
-        <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
-            that are not local to the development system but located in a master area that is controlled
-            by the maintainer of the source code.
-            For example, in order for a developer to work on a particular piece of code, they need to 
-            first get a copy of it from an "upstream" source.</para></listitem>
-        <listitem>
-            <para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
+        <itemizedlist>
+            <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to 
+                a recipe file.  
+                Information in append files overrides the information in the similarly-named recipe file.
+                Append files use the <filename>.bbappend</filename> filename suffix.
+                </para></listitem>
+            <listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by 
+                the Yocto Project to build images. 
+                For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'>
+                BitBake documentation</ulink>.</para></listitem>
+            <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
+                and inheritance allowing commonly used patterns to be defined once and easily used 
+                in multiple recipes.  
+                Class files end with the <filename>.bbclass</filename> filename extension.
+                </para></listitem>
+            <listitem><para><emphasis>Configuration File:</emphasis>  Configuration information in various
+                <filename>.conf</filename> files provides global definitions of variables.
+                The <filename>conf/local.conf</filename> configuration file in the Yocto Project
+                build directory contains user-defined variables that affect each build.
+                The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
+                defines Yocto ‘distro’ configuration
+                variables used only when building with this policy.  
+                Machine configuration files, which 
+                are located throughout the Yocto Project file structure, define
+                variables for specific hardware and are only used when building for that target 
+                (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines 
+                variables for the Texas Instruments ARM Cortex-A8 development board).  
+                Configuration files end with a <filename>.conf</filename> filename extension.
+                </para></listitem>
+            <listitem><para><emphasis>Cross-Development Toolchain:</emphasis> 
+                A collection of software development
+                tools and utilities that allow you to develop software for targeted architectures.
+                This toolchain contains cross-compilers, linkers, and debuggers that are specific to 
+                an architecture.
+                You can use the Yocto Project to build cross-development toolchains in tarball form that when 
+                unpacked contain the development tools you need to cross-compile and test your software.
+                The Yocto Project ships with images that contain toolchains for supported architectures
+                as well.
+                Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem>
+            <listitem><para><emphasis>Image:</emphasis> An image is the result produced when 
+                BitBake processes a given collection of recipes and related metadata.
+                Images are the binary output that runs on specific hardware and for specific
+                use cases.
+                For a list of the supported image types that the Yocto Project provides, see the
+                "<ulink url='http://www.yoctoproject.org/docs/latest/poky-ref-manual/poky-ref-manual.html#ref-images'>Reference: Images</ulink>"
+                appendix in The Yocto Project Reference Manual.</para></listitem>
+            <listitem><para><emphasis>Layer:</emphasis> A collection of recipes representing the core, 
+                a BSP, or an application stack.</para></listitem>
+            <listitem><para><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image. 
+                Metadata includes recipes, classes, and configuration files.</para></listitem>
+            <listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating 
+                with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
+                This metadata is found in the <filename>meta</filename> directory of the Yocto Project
+                files.</para></listitem>
+            <listitem><para><emphasis>Package:</emphasis> The packaged output from a baked recipe.
+                A package is generally the compiled binaries produced from the recipe's sources.  
+                You ‘bake’ something by running it through BitBake.</para></listitem>
+            <listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project 
+                uses to create images.</para></listitem>
+            <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.  
+                A recipe describes where you get source code and which patches to apply.
+                Recipes describe dependencies for libraries or for other recipes, and they 
+                also contain configuration and compilation options.  
+                Recipes contain the logical unit of execution, the software/images to build, and 
+                use the <filename>.bb</filename> file extension.</para></listitem>
+            <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.  
+                You simply use Tasks to hold recipes that, when built, usually accomplish a single task.  
+                For example, a task could contain the recipes for a company’s proprietary or value-add software.  
+                Or, the task could contain the recipes that enable graphics. 
+                A task is really just another recipe.  
+                Because task files are recipes, they end with the <filename>.bb</filename> filename 
+                extension.</para></listitem>
+            <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
+                that are not local to the development system but located in a master area that is controlled
+                by the maintainer of the source code.
+                For example, in order for a developer to work on a particular piece of code, they need to 
+                first get a copy of it from an "upstream" source.</para></listitem>
+            <listitem>
+                <para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis>
                 This term refers to the directory structure created as a result of either downloading 
                 and unpacking a Yocto Project release tarball or setting up a Git repository
                 by cloning <filename>git://git.yoctoproject.org/poky</filename>.
-                Sometimes the term "the Yocto Project Files structure" is used as well.
-            </para>
+                Sometimes the term "the Yocto Project Files structure" is used as well.</para>
 
-            <para>
-                The Yocto Project files contain BitBake, Documentation, metadata and 
+                <para>The Yocto Project files contain BitBake, Documentation, metadata and 
                 other files that all support the development environment. 
                 Consequently, you must have the Yocto Project files in place on your development 
-                system in order to do any development using the Yocto Project.
-            </para>
+                system in order to do any development using the Yocto Project.</para>
 
-            <para>
-                The name of the top-level directory of the Yocto Project file structure  
+                <para>The name of the top-level directory of the Yocto Project file structure  
                 is derived from the Yocto Project release tarball.
                 For example, downloading and unpacking <filename>poky-edison-6.0.tar.bz2</filename>
                 results in a Yocto Project file structure whose Yocto Project source directory is named 
                 <filename>poky-edison-6.0</filename>.
                 If you create a Git repository, then you can name the repository anything you like.
-                By default, your local Git repository is named <filename>poky</filename>.
-            </para>
+                By default, your local Git repository is named <filename>poky</filename>.</para>
 
-            <para>
-                It is important to understand the differences between Yocto Project Files created
+                <para>It is important to understand the differences between Yocto Project Files created
                 by unpacking a release tarball as compared to cloning 
                 <filename>git://git.yoctoproject.org/poky</filename>.
                 When you unpack a tarball, you have an exact copy of the files based on the time of 
@@ -237,7 +235,9 @@
                 Any changes you make to your local Yocto Project files are on top of the release.
                 On the other hand, when you clone the Yocto Project Git repository, you have an
                 active development repository.
-                In this case, any local changes you make to the Yocto Project can be later applied to active
+       creates a build directory named <filename>YP-6.0</filename>
+                            in your home directory within the directory <filename>mybuilds</filename>.
+                            If <filename>mybuilds</filename> does not exist it is created for you.         In this case, any local changes you make to the Yocto Project can be later applied to active
                 development branches of the upstream Yocto Project Git repository.
                 If you want to track a set of local changes while starting from the same point
                 as a release tarball, you can create a local Git branch that 
@@ -245,34 +245,48 @@
                 You do this using Git tags that are part of the repository.
                 For more information on concepts, see the section 
                 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>".
-            </para>
+                </para>
 
-            <para>
-                You can find instruction on how to set up the Yocto Project files on your 
+                <para>You can find instruction on how to set up the Yocto Project files on your 
                 host development system by reading 
                 the 
                 "<ulink url='http://www.yoctoproject.org/docs/latest/dev-manual/dev-manual.html#getting-setup'>Getting
-                Setup</ulink>" section.
-            </para>
-        </listitem>
-        <listitem><para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis>
-            This term refers to the area used by the Yocto Project for builds.  
-            The area is created when you <filename>source</filename> the Yocto Project setup 
-            environment script that is found in the Yocto Project files area. 
-            (e.g. <filename>oe-init-build-env</filename>).
-            You can create the Yocto Project build directory anywhere you want on your 
-            development system.
-            Here is an example that creates the directory in <filename>mybuilds</filename> 
-            and names the Yocto Project build directory <filename>YP-6.0</filename>:
-            <literallayout class='monospaced'> 
+                Setup</ulink>" section.</para></listitem>
+            <listitem>
+                <para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis>
+                This term refers to the area used by the Yocto Project for builds.  
+                The area is created when you <filename>source</filename> the Yocto Project setup 
+                environment script that is found in the Yocto Project files area
+                (i.e. <filename>oe-init-build-env</filename>).
+                The <filename>TOPDIR</filename> variable points to the build directory.</para>
+           
+                <para>You have a lot of flexibility when creating the Yocto Project Build Directory.
+                Following are some examples that show how to create the directory:
+                   <itemizedlist>
+                        <listitem><para>Create the build directory in your current working directory
+                            and name it <filename>build</filename>.
+                            This is the default behavior.
+                            <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ source oe-init-build-env
+                            </literallayout></para></listitem>
+                        <listitem><para>Provide a directory path and specifically name the build 
+                            directory. 
+                            This next example creates a build directory named <filename>YP-6.0</filename>
+                            in your home directory within the directory <filename>mybuilds</filename>.
+                            If <filename>mybuilds</filename> does not exist, the directory is created for you:
+                            <literallayout class='monospaced'> 
      $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/YP-6.0
-            </literallayout>
-            If you don't specifically name the directory, BitBake creates it 
-            in the current directory and uses the name <filename>build</filename>.
-            Also, if you supply an existing directory, then BitBake uses that 
-            directory as the Yocto Project build directory and populates the build hierarchy
-            beneath it.</para></listitem>
-    </itemizedlist>
+                            </literallayout></para></listitem>
+                        <listitem><para>Provide an existing directory to use as the build directory.
+                            This example uses the existing <filename>mybuilds</filename> directory 
+                            as the build directory.
+                            <literallayout class='monospaced'> 
+     $ source poky-edison-6.0/oe-init-build-env $HOME/mybuilds/
+                            </literallayout></para></listitem>
+                    </itemizedlist> 
+                </para></listitem> 
+        </itemizedlist>
     </para>
 </section>