diff options
authorJamie Lenehan <lenehan@twibble.org>2007-06-08 07:48:13 +0000
committerJamie Lenehan <lenehan@twibble.org>2007-06-08 07:48:13 +0000
commitb454cacc26f988f41bfbf450e5c55d764e69165c (patch)
parent483dff1bc453224980751aa6c1751e3225669d4d (diff)
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
- <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}
- <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*'
+%&gt; find tmp/staging -name '*libbz*'
+ <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"
+ <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 id="recipes_autoconf" xreflabel="about autoconf">