documentation/poky-ref-manual/ref-bitbake.xml: Completed general edits.

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>

1 files changed, 135 insertions, 134 deletions

diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml
index cf019aa..1a98b04 100644
--- a/documentation/poky-ref-manual/ref-bitbake.xml
+++ b/documentation/poky-ref-manual/ref-bitbake.xml
@@ -28,15 +28,15 @@
         <title>Parsing</title>
 
         <para>
-            The first thing BitBake does is work out its configuration by 
-            looking for a file called <filename>bitbake.conf</filename>.
-            BitBake examines the <varname>BBPATH</varname> environment 
-            variable looking for a <filename class="directory">conf/</filename> 
-            directory that contains a <filename>bitbake.conf</filename> file.
-            BitBake adds the first <filename>bitbake.conf</filename> file found in
-            <varname>BBPATH</varname> (similar to the PATH environment variable). 
-            For Poky, <filename>bitbake.conf</filename> is found in <filename 
-            class="directory">meta/conf/</filename>. 
+            BitBake parses configuration files, classes, and <filename>.bb</filename> files. 
+        </para>
+
+        <para>
+            The first thing BitBake does is look for the <filename>bitbake.conf</filename> file.
+            Poky keeps this file in <filename class="directory">meta/conf/</filename>.
+            BitBake finds it by examining the <varname>BBPATH</varname> environment 
+            variable and looking for the <filename class="directory">meta/conf/</filename> 
+            directory.
         </para>
 
         <para>
@@ -75,12 +75,12 @@
         </para>
 
         <para>
-            After the parsing of the configuration files is complete, the 
+            After classes are included, the 
             variable <glossterm><link linkend='var-BBFILES'>BBFILES</link></glossterm> 
             is set, usually in
             <filename>local.conf</filename>, and defines the list of places to search for 
             <filename class="extension">.bb</filename> files. 
-            By default this specifies the <filename class="directory">meta/packages/
+            By default, the BBFILES variable specifies the <filename class="directory">meta/packages/
             </filename> directory within Poky, but other directories such as
             <filename class="directory">meta-extras/</filename> can be included 
             too. 
@@ -92,19 +92,19 @@
             BitBake parses each <filename class="extension">.bb</filename> file in BBFILES and 
             stores the values of various variables.  
             In summary, for each <filename class="extension">.bb</filename> 
-            file the configuration + base class of variables are set, followed 
+            file the configuration plus the base class of variables are set, followed 
             by the data in the <filename class="extension">.bb</filename> file 
             itself, followed by any inherit commands that
             <filename class="extension">.bb</filename> file might contain.
         </para>
 
         <para>
-            Parsing <filename class="extension">.bb</filename> files is a time 
-            consuming process, so a cache is kept to speed up subsequent parsing. 
+            Because parsing <filename class="extension">.bb</filename> files is a time 
+            consuming process, a cache is kept to speed up subsequent parsing. 
             This cache is invalid if the timestamp of the <filename class="extension">.bb</filename> 
-            file itself has changed, or if the timestamps of any of the include, 
+            file itself changes, or if the timestamps of any of the include, 
             configuration or class files the <filename class="extension">.bb</filename>
-            file depends on have changed.
+            file depends on changes.
         </para>
     </section>
 
@@ -113,58 +113,53 @@
 
         <para>
             Once all the <filename class="extension">.bb</filename> files have been 
-            parsed, BitBake will proceed to build "poky-image-sato" (or whatever was
-            specified on the commandline) and looks for providers of that target.
+            parsed, BitBake starts to build the target (poky-image-sato in the previous section's 
+            example) and looks for providers of that target.
             Once a provider is selected, BitBake resolves all the dependencies for  
-            the target. In the case of "poky-image-sato", it would lead to 
-            <filename>task-base.bb</filename>  
-            which in turn would lead to packages like <application>Contacts</application>, 
-            <application>Dates</application>, <application>BusyBox</application>
-            and these in turn depend on glibc and the toolchain.
+            the target. 
+            In the case of "poky-image-sato", it would lead to <filename>task-base.bb</filename>,  
+            which in turn leads to packages like <application>Contacts</application>, 
+            <application>Dates</application> and <application>BusyBox</application>.
+            These packages in turn depend on glibc and the toolchain.
         </para>
 
         <para>
-            Sometimes a target might have multiple providers and a common example 
-            is "virtual/kernel" that is provided by each kernel package. Each machine
-            will often elect the best provider of its kernel with a line like the 
+            Sometimes a target might have multiple providers.
+            An common example is "virtual/kernel", which is provided by each kernel package. 
+            Each machine often elects the best kernel provider by using a line similar to the 
             following in the machine configuration file:
         </para>
-        <programlisting><glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm>_virtual/kernel = "linux-rp"</programlisting>
+
+        <programlisting>
+PREFERRED_PROVIDER_virtual/kernel = "linux-rp"
+        </programlisting>
+
         <para>
-            The default <glossterm><link linkend='var-PREFERRED_PROVIDER'>
-            PREFERRED_PROVIDER</link></glossterm> is the provider with the same name as
-            the target.
+            The default <glossterm><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></glossterm> 
+            is the provider with the same name as the target.
         </para>
 
         <para>
-            Understanding how providers are chosen is complicated by the fact
-            multiple versions might be present. BitBake defaults to the highest 
-            version of a provider by default. Version comparisons are made using 
-            the same method as Debian. The <glossterm><link 
-            linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm>
-            variable can be used to specify a particular version 
-            (usually in the distro configuration) but the order can 
-            also be influenced by the <glossterm><link
-                    linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> 
-            variable. By default files 
-            have a preference of "0". Setting the
-            <glossterm><link
-                    linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> to "-1" will 
-            make a package unlikely to be used unless it was explicitly referenced and
-            "1" makes it likely the package will be used. 
-            <glossterm><link
-                    linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm> overrides 
-            any <glossterm><link
-                    linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm>. <glossterm><link
-                    linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> 
-            is often used to mark more 
-            experimental new versions of packages until they've undergone sufficient 
-            testing to be considered stable.
+            Understanding how providers are chosen is made complicated by the fact
+            that multiple versions might exist. 
+            BitBake defaults to the highest version of a provider.
+            Version comparisons are made using the same method as Debian. 
+            You can use the <glossterm><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></glossterm>
+            variable to specify a particular version (usually in the distro configuration).
+            You can influence the order by using the 
+            <glossterm><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></glossterm> 
+            variable. 
+            By default, files have a preference of "0". 
+            Setting the DEFAULT_PREFERENCE to "-1" makes the package unlikely to be used unless it is
+            explicitly referenced.
+            Setting the DEFAULT_PREFERENCE to "1" makes it likely the package is used. 
+            PREFERRED_VERSION overrides any DEFAULT_PREFERENCE setting.
+            DEFAULT_PREFERENCE is often used to mark newer and more experimental package
+            versions until they have undergone sufficient testing to be considered stable.
         </para>
 
         <para>
-            The end result is that internally, BitBake has now built a list of 
-            providers for each target it needs in order of priority.
+            In summary, BitBake has created a list of providers, which is prioritized, for each target.
         </para>
     </section>
 
@@ -172,18 +167,20 @@
         <title>Dependencies</title>
 
         <para>
-            Each target BitBake builds consists of multiple tasks (e.g. fetch, 
-            unpack, patch, configure, compile etc.). For best performance on 
-            multi-core systems, BitBake considers each task as an independent 
-            entity with a set of dependencies. There are many variables that 
-            are used to signify these dependencies and more information can be found 
-            about these in the <ulink url='http://bitbake.berlios.de/manual/'>
-            BitBake manual</ulink>. At a basic level it is sufficient to know 
-        that BitBake uses the <glossterm><link
-                linkend='var-DEPENDS'>DEPENDS</link></glossterm> and 
-        <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when 
-            calculating dependencies and descriptions of these variables are 
-            available through the links. 
+            Each target BitBake builds consists of multiple tasks such as fetch, unpack, patch, configure, 
+            and compile. 
+            For best performance on multi-core systems, BitBake considers each task as an independent 
+            entity with its own set of dependencies. 
+        </para>
+  
+        <para>
+            Dependencies are defined through several variables.
+            You can find information about variables BitBake uses in the 
+            <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>. 
+            At a basic level it is sufficient to know that BitBake uses the 
+            <glossterm><link linkend='var-DEPENDS'>DEPENDS</link></glossterm> and 
+            <glossterm><link linkend='var-RDEPENDS'>RDEPENDS</link></glossterm> variables when 
+            calculating dependencies. 
         </para>
 
     </section>
@@ -193,69 +190,75 @@
 
         <para>
             Based on the generated list of providers and the dependency information, 
-            BitBake can now calculate exactly which tasks it needs to run and in what 
-            order. The build now starts with BitBake forking off threads up to
-            the limit set in the <glossterm><link
-                    linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable
-            as long as there are tasks ready to run, i.e. tasks with all their
-            dependencies met.
+            BitBake can now calculate exactly what tasks it needs to run and in what 
+            order it needs to run them. 
+            The build now starts with BitBake forking off threads up to the limit set in the 
+            <glossterm><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></glossterm> variable.
+            BitBake continues to fork threads as long as there are tasks ready to run,
+            those taksks have all their dependencies met, and the thread threshold has not been 
+            exceeded.
         </para>
 
         <para>
-            As each task completes, a timestamp is written to the directory 
-            specified by the <glossterm><link
-                    linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually 
-            <filename class="directory">build/tmp/stamps/*/</filename>). On 
-            subsequent runs, BitBake looks at the <glossterm><link
-                    linkend='var-STAMPS'>STAMPS</link></glossterm>
-            directory and will not rerun 
-            tasks its already completed unless a timestamp is found to be invalid. 
-            Currently, invalid timestamps are only considered on a per <filename 
-            class="extension">.bb</filename> file basis so if for example the configure stamp has a timestamp greater than the 
-            compile timestamp for a given target the compile task would rerun but this 
-            has no effect on other providers depending on that target. This could 
-            change or become configurable in future versions of BitBake. Some tasks 
-            are marked as "nostamp" tasks which means no timestamp file will be written 
-            and the task will always rerun.
+            As each task completes, a timestamp is written to the directory specified by the 
+            <glossterm><link linkend='var-STAMPS'>STAMPS</link></glossterm> variable (usually 
+            <filename class="directory">build/tmp/stamps/*/</filename>). 
+            On subsequent runs, BitBake looks at the STAMPS directory and does not rerun 
+            tasks that are already completed unless a timestamp is found to be invalid. 
+            Currently, invalid timestamps are only considered on a per 
+            <filename class="extension">.bb</filename> file basis.
+            So, for example, if the configure stamp has a timestamp greater than the 
+            compile timestamp for a given target then the compile task would rerun.
+            Running the compile task again, however, has no effect on other providers 
+            that depend on that target. 
+            This behavior could change or become configurable in future versions of BitBake. 
         </para>
-
-        <para>Once all the tasks have been completed BitBake exits.</para> 
-
+ 
+        <note><para>
+            Some tasks are marked as "nostamp" tasks.
+            No timestamp file is created when these tasks are run.
+            Consequently, "nostamp" tasks are always rerun.
+        </para></note>
     </section>
 
     <section id='ref-bitbake-runtask'>
         <title>Running a Task</title>
 
         <para>
-            It's worth noting what BitBake does to run a task. A task can either
-            be a shell task or a python task. For shell tasks, BitBake writes a
-            shell script to <filename>${WORKDIR}/temp/run.do_taskname.pid</filename>
-            and then executes the script. The generated
-            shell script contains all the exported variables, and the shell functions 
-            with all variables expanded. Output from the shell script is 
-            sent to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
-            Looking at the
-            expanded shell functions in the run file and the output in the log files 
+            Tasks can either be a shell task or a python task.
+            For shell tasks, BitBake writes a shell script to 
+            <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script. 
+            The generated shell script contains all the exported variables, and the shell functions 
+            with all variables expanded. 
+            Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
+            Looking at the expanded shell functions in the run file and the output in the log files 
             is a useful debugging technique.
         </para>
 
         <para>
-            Python functions are executed internally to BitBake itself and 
-            logging goes to the controlling terminal. Future versions of BitBake will 
-            write the functions to files in a similar way to shell functions and 
-            logging will also go to the log files in a similar way.
+            For Python tasks, BitBake executes the task internally and logs information to the 
+            controlling terminal. 
+            Future versions of BitBake will write the functions to files similar to the way 
+            shell tasks are handled.
+            Logging will be handled in way similar to shell tasks as well.
         </para>
+
+        <para>
+            Once all the tasks have been completed BitBake exits.
+        </para> 
     </section>
 
 
     <section id='ref-bitbake-commandline'>
-        <title>Commandline</title>
+        <title>BitBake Command Line</title>
 
         <para>
-            To quote from "bitbake --help":
+            Following is the bitbake manpage:
         </para>
 
-        <screen>Usage: bitbake [options] [package ...]
+        <screen>
+$ bitbake --help
+Usage: bitbake [options] [package ...]
 
 Executes the specified task (default is 'build') for a given set of BitBake files.
 It expects that BBFILES is defined, which is a space separated list of files to
@@ -275,6 +278,8 @@ Options:
   -a, --tryaltconfigs   continue with builds by trying to use alternative
                         providers where possible.
   -f, --force           force run of specified cmd, regardless of stamp status
+  -i, --interactive     drop into the interactive mode also called the BitBake
+                        shell.
   -c CMD, --cmd=CMD     Specify task to execute. Note that this only executes
                         the specified task for the providee and the packages
                         it depends on, i.e. 'compile' does not implicitly call
@@ -287,9 +292,6 @@ Options:
   -D, --debug           Increase the debug level. You can specify this more
                         than once.
   -n, --dry-run         don't execute, just go through the motions
-  -S, --dump-signatures
-                        don't execute, just dump out the signature
-                        construction information
   -p, --parse-only      quit after parsing the BB files (developers only)
   -d, --disable-psyco   disable using the psyco just-in-time compiler (not
                         recommended)
@@ -298,46 +300,45 @@ Options:
                         what used to be bbread)
   -g, --graphviz        emit the dependency trees of the specified packages in
                         the dot syntax
-  -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
-                        Assume these dependencies don't exist and are already
-                        provided (equivalent to ASSUME_PROVIDED). Useful to
-                        make dependency graphs more appealing
+  -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
+                        Stop processing at the given list of dependencies when
+                        generating dependency graphs. This can help to make
+                        the graph more appealing
   -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
                         Show debug logging for the specified logging domains
   -P, --profile         profile the command and print a report
-  -u UI, --ui=UI        userinterface to use
-  --revisions-changed   Set the exit code depending on whether upstream
-                        floating revisions have changed or not</screen>
-
+        </screen>
     </section>
 
     <section id='ref-bitbake-fetchers'>
         <title>Fetchers</title>
 
         <para>
-            As well as the containing the parsing and task/dependency handling 
-            code, BitBake also contains a set of "fetcher" modules which allow 
-            fetching of source code from various types of sources. Example 
-            sources might be from disk with the metadata, from websites, from 
-            remote shell accounts or from SCM systems like cvs/subversion/git. 
+            BitBake also contains a set of "fetcher" modules that allow 
+            retrieval of source code from various types of sources. 
+            For example, BitBake can get source code from a disk with the metadata, from websites, 
+            from remote shell accounts or from Source Code Management (SCM) systems 
+            like <filename>cvs/subversion/git</filename>. 
         </para>
 
         <para>
-            The fetchers are usually triggered by entries in 
-            <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. Information about the 
-            options and formats of entries for specific fetchers can be found in the 
-            <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>.
+            Fetchers are usually triggered by entries in 
+            <glossterm><link linkend='var-SRC_URI'>SRC_URI</link></glossterm>. 
+            You can find information about the options and formats of entries for specific 
+            fetchers in the <ulink url='http://bitbake.berlios.de/manual/'>BitBake manual</ulink>.
         </para>
 
         <para>
             One useful feature for certain SCM fetchers is the ability to 
-            "auto-update" when the upstream SCM changes version. Since this 
-            requires certain functionality from the SCM only certain systems 
-            support it, currently Subversion, Bazaar and to a limited extent, Git. It 
-            works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link>
-            </glossterm> variable. See the <link linkend='platdev-appdev-srcrev'>
-            developing with an external SCM based project</link> section for more
-            information.
+            "auto-update" when the upstream SCM changes version. 
+            Since this ability requires certain functionality from the SCM, not all
+            systems support it.
+            Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update". 
+            This feature works using the <glossterm><link linkend='var-SRCREV'>SRCREV</link></glossterm> 
+            variable. 
+            See the 
+            <link linkend='platdev-appdev-srcrev'>Developing within Poky with an External SCM-based Package</link> 
+            section for more information.
         </para>
 
     </section>