usermanual/recipes: Fill in some details in the staging section.

1 files changed, 104 insertions, 12 deletions

diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml
index 18238cead0..5693b825b9 100644
--- a/usermanual/chapters/recipes.xml
+++ b/usermanual/chapters/recipes.xml
@@ -2449,21 +2449,113 @@ addtask unpack_extra after do_unpack before do_patch</screen></para>
     <title>Staging: Making includes and libraries available for
     building</title>
 
-    <para>This section is to be completed:</para>
+    <para>Staging is the process of making files, such as include files and
+    libraries, available for use by other recipes. This is different to
+    installing because installing is about making things available for
+    packaging and then eventually for use on the target device. Staging on the
+    other hand is about making things available on the host system for use by
+    building later applications.</para>
+
+    <para>Taking bzip2 as an example you can see that it stages a header file
+    and it's library files:<screen>do_stage () {
+    install -m 0644 bzlib.h ${STAGING_INCDIR}/
+    oe_libinstall -a -so libbz2 ${STAGING_LIBDIR}
+}</screen></para>
 
-    <itemizedlist>
-      <listitem>
-        <para>Why we have staging</para>
-      </listitem>
+    <para>The <emphasis>oe_libinstall</emphasis> method used in the bzip2
+    recipe is described in the <xref linkend="recipes_methods" /> section, and
+    it takes care of installing libraries (into the staging area in this
+    case). The staging variables are automatically defined to the correct
+    staging location, in this case the main staging variables are used:</para>
 
-      <listitem>
-        <para>How staging is used</para>
-      </listitem>
+    <variablelist>
+      <varlistentry>
+        <term>STAGING_INCDIR</term>
 
-      <listitem>
-        <para>What does and does not need to be staged</para>
-      </listitem>
-    </itemizedlist>
+        <listitem>
+          <para>The directory into which staged headers files should be
+          installed. This is the equivalent of the standard <emphasis
+          role="bold">/usr/include</emphasis> directory.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>STAGING_LIBDIR</term>
+
+        <listitem>
+          <para>The directory into which staged library files should be
+          installed. This is the equivalent of the standard <emphasis
+          role="bold">/usr/lib</emphasis> directory.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Additional staging related variables are covered in the <xref
+    linkend="directories_staging" /> section in <xref
+    linkend="chapter_reference" />.</para>
+
+    <para>Looking in the staging area under tmp you can see the result of the
+    bzip2 recipes staging task:<screen>%&gt; find tmp/staging -name '*bzlib*'
+tmp/staging/sh4-linux/include/bzlib.h
+%&gt; find tmp/staging -name '*libbz*'
+tmp/staging/sh4-linux/lib/libbz2.so
+tmp/staging/sh4-linux/lib/libbz2.so.1.0
+tmp/staging/sh4-linux/lib/libbz2.so.1
+tmp/staging/sh4-linux/lib/libbz2.so.1.0.2
+tmp/staging/sh4-linux/lib/libbz2.a</screen></para>
+
+    <para>As well as being used during the stage task the staging related
+    variables are used when building other packages. Looking at the gnupg
+    recipe we see two bzip2 related items:<screen>DEPENDS = "zlib <emphasis
+          role="bold">bzip2</emphasis>"
+...
+EXTRA_OECONF = "--disable-ldap \
+        --with-zlib=${STAGING_LIBDIR}/.. \
+        <emphasis role="bold">--with-bzip2=${STAGING_LIBDIR}/..</emphasis> \
+        --disable-selinux-support"
+</screen></para>
+
+    <para>Bzip2 is referred to in two places in the recipe:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>DEPENDS</term>
+
+        <listitem>
+          <para>Remember that <emphasis role="bold">DEPENDS</emphasis> defines
+          the list of build time dependencies. In this case the staged headers
+          and libraries from bzip2 are required to build gnupg, and therefore
+          we need to make sure the bzip2 recipe has run and staging the
+          headers and libraries. By adding the <emphasis
+          role="bold">DEPENDS</emphasis> on bzip2 this ensures that this
+          happens.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><emphasis role="bold">EXTRA_OECONF</emphasis></term>
+
+        <listitem>
+          <para>This variable is used by the <xref
+          linkend="autotools_class" /> to provide options to the configure
+          script of the package. In the gnupg case it needs to be told where
+          the bzip2 headers and libraries files are, and this is done via the
+          <emphasis>--with-bzip2</emphasis> option. In this case it needs to
+          the directory which include the lib and include subdirectories.
+          Since OE doesn't define a variable for one level above the include
+          and lib directories <emphasis role="bold">..</emphasis> is used to
+          indicate one directory up. Without this gnupg would search the host
+          system headers and libraries instead of those we have provided in
+          the staging area for the target.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Remember that staging is used to make things, such as headers and
+    libraries, available to used by other recipes later on. While header and
+    libraries are the most common item requiring staging other items such as
+    the pkgconfig files need to be staged as well, while for native packages
+    the binaries also need to be staged.</para>
   </section>
 
   <section id="recipes_autoconf" xreflabel="about autoconf">