[oe-commits] org.oe.documentation usermanual/recipes: Fill in some details in the staging section.
lenehan commit
openembedded-commits at lists.openembedded.org
Fri Jun 8 07:54:46 UTC 2007
usermanual/recipes: Fill in some details in the staging section.
Author: lenehan at openembedded.org
Branch: org.openembedded.documentation
Revision: 59869e48f6e860c78411327335ed7294119f8b6e
ViewMTN: http://monotone.openembedded.org/revision.psp?id=59869e48f6e860c78411327335ed7294119f8b6e
Files:
1
usermanual/chapters/recipes.xml
Diffs:
#
# mt diff -r945723a395de5b460f57e32632d1142b7d3138cd -r59869e48f6e860c78411327335ed7294119f8b6e
#
#
#
# patch "usermanual/chapters/recipes.xml"
# from [ed61a97afd9865cc4f99b34f2449c58a0dfc1d6c]
# to [d2d81e6527f26204a69db96f411f62e0765c6ffc]
#
============================================================
--- usermanual/chapters/recipes.xml ed61a97afd9865cc4f99b34f2449c58a0dfc1d6c
+++ usermanual/chapters/recipes.xml d2d81e6527f26204a69db96f411f62e0765c6ffc
@@ -2449,21 +2449,113 @@ addtask unpack_extra after do_unpack bef
<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>
- <itemizedlist>
- <listitem>
- <para>Why we have staging</para>
- </listitem>
+ <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>
- <listitem>
- <para>How staging is used</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>What does and does not need to be staged</para>
- </listitem>
- </itemizedlist>
+ <variablelist>
+ <varlistentry>
+ <term>STAGING_INCDIR</term>
+
+ <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>%> find tmp/staging -name '*bzlib*'
+tmp/staging/sh4-linux/include/bzlib.h
+%> 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">
More information about the Openembedded-commits
mailing list