Add information on the bitbake command to the User Manual.

1 files changed, 77 insertions, 19 deletions

diff --git a/doc/manual/usermanual.xml b/doc/manual/usermanual.xml
index 799c0df4e..a2cdf230a 100644
--- a/doc/manual/usermanual.xml
+++ b/doc/manual/usermanual.xml
@@ -208,32 +208,90 @@ addtask printdate before do_build</screen></para>
             <para>bbread is a command for displaying BitBake metadata.  When run with no arguments, it has the core parse 'conf/bitbake.conf', as located in BBPATH, and displays that.  If you supply a file on the commandline, such as a .bb, then it parses that afterwards, using the aforementioned configuration metadata.</para>
         </section>
         <section>
-            <title>bbmake</title>
-            <programlisting format="linespecific"><literal>usage: bbmake [options] [package ...]
+            <title>bitbake</title>
+            <section>
+                <title>Introduction</title>
+                <para>bitbake is the primary command in the system.  It facilitates executing tasks in a single .bb file, or executing a given task on a set of multiple .bb files, accounting for interdependencies amongst them.</para>
+            </section>
+            <section>
+                <title>Usage and Syntax</title>
+                <para>
+                    <screen><prompt>$ </prompt>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 seperated list of files to
 be executed.  BBFILES does support wildcards.
-Default packages to be executed are all packages in BBFILES.
 Default BBFILES are the .bb files in the current directory.
 
 options:
-  --version            show program's version number and exit
-  -h, --help           show this help message and exit
-  -k, --continue       continue as much as possible after an error. While the
-                       target that failed, and those that depend on it, cannot
-                       be remade, the other dependencies of these targets can
-                       be processed all the same.
-  -f, --force          force run of specified cmd, regardless of stamp status
-  -cCMD, --cmd=CMD     Specify task to execute
-  -rFILE, --read=FILE  read the specified file before bitbake.conf
-  -v, --verbose        output more chit-chat to the terminal
-  -n, --dry-run        don't execute, just go through the motions
-  -p, --parse-only     quit after parsing the BB files (developers only)
-  -d, --disable-psyco  disable using the psyco just-in-time compiler (not
-                       recommended)
-  -s, --show-versions  show current and preferred versions of all packages</literal>
-            </programlisting>
+  --version             show program's version number and exit
+  -h, --help            show this help message and exit
+  -bBUILDFILE, --buildfile=BUILDFILE
+                        execute the task against this .bb file, rather than a
+                        package from BBFILES.
+  -k, --continue        continue as much as possible after an error. While the
+                        target that failed, and those that depend on it, cannot
+                        be remade, the other dependencies of these targets can
+                        be processed all the same.
+  -f, --force           force run of specified cmd, regardless of stamp status
+  -cCMD, --cmd=CMD      Specify task to execute
+  -rFILE, --read=FILE   read the specified file before bitbake.conf
+  -v, --verbose         output more chit-chat to the terminal
+  -D, --debug           Increase the debug level
+  -n, --dry-run         don't execute, just go through the motions
+  -p, --parse-only      quit after parsing the BB files (developers only)
+  -d, --disable-psyco   disable using the psyco just-in-time compiler (not
+                        recommended)
+  -s, --show-versions   show current and preferred versions of all packages</screen>
+                </para>
+                <para>Executing tasks for a single file is relatively simple.  You specify the file in question, and bitbake parses it and executes the specified task (or <quote>build</quote> by default).  It obeys intertask dependencies when doing so.</para>
+                <para>There are a number of additional complexities introduced when one wants to manage multiple .bb files.  Clearly there needs to be a way to tell bitbake what files are available, and of those, which we want to execute at this time.  There also needs to be a way for each .bb to express its dependencies, both for build time and runtime.  There must be a way for the user to express their preferences when multiple .bb's provide the same functionality, or when there are multiple versions of a .bb.</para>
+            </section>
+            <section>
+                <title>Metadata</title>
+                <para>As you may have seen in the usage information, or in the information about .bb files, the BBFILES variable is how the bitbake tool locates its files.  This variable is a space seperated list of files that are available, and supports wildcards.
+                <example>
+                    <title>Setting BBFILES</title>
+                    <programlisting><varname>BBFILES</varname> = "/path/to/bbfiles/*.bb"</programlisting>
+                </example></para>
+                <para>With regard to dependencies, it expects the .bb to define a <varname>DEPENDS</varname> variable, which contains a space seperated list of <quote>package names</quote>, which themselves are the <varname>PN</varname> variable.  The <varname>PN</varname> variable is, in general, by default, set to a component of the .bb filename.</para>
+                <example>
+                    <title>Depending on another .bb</title>
+                    <para>a.bb:
+    <screen>PN = "package-a"
+    DEPENDS += "package-b"</screen>
+                    </para>
+                    <para>b.bb:
+    <screen>PN = "package-b"</screen>
+                    </para>
+                </example>
+                <example>
+                    <title>Using PROVIDES</title>
+                    <para>This example shows the usage of the PROVIDES variable, which allows a given .bb to specify what functionality it provides.</para>
+                    <para>package1.bb:
+    <screen>PROVIDES += "virtual/package"</screen>
+                    </para>
+                    <para>package2.bb:
+    <screen>DEPENDS += "virtual/package"</screen>
+                    </para>
+                    <para>package3.bb:
+    <screen>PROVIDES += "virtual/package"</screen>
+                    </para>
+                    <para>As you can see, here there are two different .bb's that provide the same functionality (virtual/package).  Clearly, there needs to be a way for the person running bitbake to control which of those providers gets used.  There is, indeed, such a way.</para>
+                    <para>The following would go into a .conf file, to select package1:
+    <screen>PREFERRED_PROVIDER_virtual/package = "package1"</screen>
+                    </para>
+                </example>
+                <example>
+                    <title>Specifying version preference</title>
+                    <para>When there are multiple <quote>versions</quote> of a given package, bitbake defaults to selecting the most recent version, unless otherwise specified.  If the .bb in question has a <varname>DEFAULT_PREFERENCE</varname> set lower than the other .bb's (default is 0), then it will not be selected.  This allows the person or persons maintaining the repository of .bb files to specify their preferences for the default selected version.  In addition, the user can specify their preferences with regard to version.</para>
+                    <para>If the first .bb is named <filename>a_1.1.bb</filename>, then the <varname>PN</varname> variable will be set to <quote>a</quote>, and the <varname>PV</varname> variable will be set to 1.1.</para>
+                    <para>If we then have an <filename>a_1.2.bb</filename>, bitbake will choose 1.2 by default.  However, if we define the following variable in a .conf that bitbake parses, we can change that.
+    <screen>PREFERRED_VERSION_a = "1.1"</screen>
+                    </para>
+                </example>
+            </section>
         </section>
     </chapter>
     <appendix>