getting_oe.xml: Update "Building Software" section.

1 files changed, 310 insertions, 7 deletions

diff --git a/docs/usermanual/chapters/getting_oe.xml b/docs/usermanual/chapters/getting_oe.xml
index 3c685049a4..d71ea71e72 100644
--- a/docs/usermanual/chapters/getting_oe.xml
+++ b/docs/usermanual/chapters/getting_oe.xml
@@ -242,13 +242,316 @@ MACHINE = "om-gta01"</screen>
   <section id="gettingoe_building_software">
     <title>Building Software</title>
 
-    <para>Once BitBake and OpenEmbedded are set up and configured, one can build 
-    software and images like this:
-<screen>
-bitbake &lt;recipe_name&gt;
-</screen>
-            </para>
+    <para>The primary interface to the build system is
+      the <command>bitbake</command> command (see
+      the <ulink url="http://subversion.tigris.org/faq.html#proxy">BitBake
+      users manual</ulink>). BitBake will download and patch files from the
+      internet, so it helps if you are on a well connected machine.
+    </para>
+
+    <para>Note that you should issue all BitBake commands from inside of the
+      <filename>build/</filename> directory, or you should
+      override <varname>TMPDIR</varname> in
+      your <filename>$OEBASE/build/conf/local.conf</filename> to point
+      elsewhere (by default it goes to <filename>tmp/</filename> relative to
+      the directory you run <command>bitbake</command> commands in).
+    </para>
+
+    <note>
+      <para>BitBake might complain that there is a problem with the setting in
+        <filename>/proc/sys/vm/mmap_min_addr</filename>, which needs to be set
+        to zero. You can set it by doing the following as root:
+
+        <screen># echo 0 > /proc/sys/vm/mmap_min_addr</screen>
+
+        Note that you can not use a text editor to do this since files
+        in <filename>/proc</filename> are not real files. Also note that this
+        above change will be lost when you reboot your system. To have the
+        change made automatically when the system boots, some systems provide
+        a <filename>/etc/sysctl.conf</filename> file. Add the following line
+        to that file:
+
+        <screen>vm.mmap_min_addr=0</screen>
+
+        If your system does not provide
+        the <filename>/etc/sysctl.conf</filename> mechanism, you can try adding
+        the above <command>echo</command> command line to
+        your <filename>/etc/rc.local</filename>.
+      </para>
+    </note>
+
+    <para>Once BitBake and OpenEmbedded are set up and configured, you can build
+      software and images like this:
 
-    <para>This section is a stub, help us by expanding it</para>
+      <screen>$ bitbake &lt;recipe_name&gt;</screen>
+
+      A recipe name corresponds to a BitBake <filename>.bb</filename> file.  A
+      BitBake file is a logical unit of tasks to be executed. Normally this is
+      a package to be built. Inter-recipe dependencies are obeyed. The recipes
+      are located by BitBake via the <varname>BBFILES</varname> variable (set
+      in your <filename>$OEBASE/build/conf/local/conf</filename>), which is a
+      space separated list of <filename>.bb</filename> files, and does handle
+      wildcards.
+    </para>
+
+    <para>To build a single package, bypassing the long parse step (and
+      therefore its dependencies -- use with care):
+
+      <screen>$ bitbake -b $OEBASE/openembedded/packages/blah/blah.bb</screen>
+    </para>
+
+    <para>There are a few groups of special recipes located in subdirectories
+      of the <filename>$OEBASE/openembedded/packages/</filename>
+      directory. These groups are:
+
+      <variablelist>
+        <varlistentry>
+          <term><filename>tasks/</filename></term>
+          <listitem><para>A collection of meta-packages that depend on real
+              packages to make managing package sets easier.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>meta/</filename></term>
+          <listitem><para>A collection of usefull meta tasks and recipes that
+              don't fit in a general category.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>images/</filename></term>
+          <listitem><para>A collection of image targets that depend on
+              packages that will be installed into an image which can be put
+              on the target system.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </para>
+
+    <section><title>Useful Target Recipes</title>
+      <para>Although BitBake can build individual packages, it is often more
+        useful to build a set of packages and combine them into an image. The
+        following recipe names are commonly used to that effect.
+      </para>
+
+      <section><title>Images</title>
+        <para>
+          <variablelist>
+            <varlistentry>
+              <term><literal>helloworld-image</literal></term>
+              <listitem>
+                <para>Builds an image, that if used as a root filesystem, will
+                  start a static executable that prints hello world then
+                  loops infinitely. Can be used to test the Linux boot
+                  procedure into user space (init).
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>bootstrap-image</literal></term>
+              <listitem>
+                <para>Build image contains task-base packages.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>console-image</literal></term>
+              <listitem>
+                <para>Build an image without the X11, gtk+, or qt windowing
+                  libraries.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>x11-image</literal></term>
+              <listitem>
+                <para>Builds an image with X11.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>beagleboard-demo-image</literal></term>
+              <listitem>
+                <para>Builds the &Aring;ngstr&ouml;m distribution like Koen
+                proposed.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>opie-image</literal></term>
+              <listitem>
+                <para>Build image based on the
+                  <ulink url="http://opie.handhelds.org/">Open Palmtop
+                  Integrated Environment</ulink> (OPIE). OPIE is a completely
+                  Open Source based graphical user environment and suite of
+                  applications for small form-factor devices, such as PDAs,
+                  running Linux.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>opie-kdepim-image</literal></term>
+              <listitem>
+                <para>Build image based on the OPIE and full featured
+                  KDE-based PIM (pi-sync, ko/pi, ka/pi, etc).
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>pivotboot-image</literal></term>
+              <listitem>
+                <para>Build image that is necessary to flash a Sharp SL C3000,
+                  Zaurus. It pivots after booting from the NAND and finalizes
+                  the install to the HD during the first boot.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>twin-image</literal></term>
+              <listitem>
+                <para>A image with task-base plus a couple of editors, nano and
+                  vim (why two?), and a mail reader, mutt.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>uml-image</literal></term>
+              <listitem>
+                <para>A root image for user-mode-linux. Includes task-base,
+                  and parts of opie.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>gpe-image</literal></term>
+              <listitem>
+                <para>Build a <ulink url="http://opie.handhelds.org/">GPE
+                  Palmtop Environment</ulink> based kernel and rootfs. The GPE
+                  provides a user interface environment for palmtop/handheld
+                  computers running the GNU/Linux or any other UNIX-like
+                  operating system.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </para>
+      </section>
+
+      <section><title>Tasks</title>
+        <para>
+          <variablelist>
+            <varlistentry>
+              <term><literal>task-base</literal></term>
+              <listitem>
+                <para>Build a kernel and core packages for a basic
+                  installation. You won't be able to do much more than ssh to
+                  the machine if this is all that is installed.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>task-dvb</literal></term>
+              <listitem>
+                <para>Meta-package for DVB application (DVB = Digital Video
+                Broadcasting).
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>task-python-everything</literal></term>
+              <listitem>
+                <para>All of python.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>task-native-sdk</literal></term>
+              <listitem>
+                <para>Mata-package for native (on-device) SDK.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </para>
+      </section>
+
+      <section><title>Meta</title>
+        <para>
+          <variablelist>
+            <varlistentry>
+              <term><literal>meta-opie</literal></term>
+              <listitem>
+                <para>Build all OPIE related packages and some more for OPIE
+                  based usage.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>meta-gpe</literal></term>
+              <listitem>
+                <para>Basic packages to go with gpe-image.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </para>
+      </section>
+
+      <section><title>Other</title>
+        <para>
+          <variablelist>
+            <varlistentry>
+              <term><literal>helloworld</literal></term>
+              <listitem>
+                <para>Builds a static executable that prints hello
+                  world then loops infinitely.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>world</literal></term>
+              <listitem>
+                <para>Build everything. This takes a long time, a lot
+                  of network bandwidth, and a lot of disc space. Can also
+                  break your toolchain.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>package-index</literal></term>
+              <listitem>
+                <para>Target to update the "feed" files to reflect the current
+                  set of .ipk's that exist in the deploy directory. Commonly
+                  used after building some packages individually to update the
+                  feed and allow them to be installed via a package manager or
+                  the ipkg command line tools.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><literal>virtual/kernel</literal></term>
+              <listitem>
+                <para>Builds the appropriate kernel for your device.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+        </para>
+      </section>
+    </section>
   </section>
 </chapter>