diff options
author | Jamie Lenehan <lenehan@twibble.org> | 2007-06-08 07:48:13 +0000 |
---|---|---|
committer | Jamie Lenehan <lenehan@twibble.org> | 2007-06-08 07:48:13 +0000 |
commit | b454cacc26f988f41bfbf450e5c55d764e69165c (patch) | |
tree | f03ab015b318e920e37738460b28b6b05245e81f /usermanual | |
parent | 483dff1bc453224980751aa6c1751e3225669d4d (diff) | |
download | openembedded-b454cacc26f988f41bfbf450e5c55d764e69165c.tar.gz |
usermanual/recipes: Fill in some details in the staging section.
Diffstat (limited to 'usermanual')
-rw-r--r-- | usermanual/chapters/recipes.xml | 116 |
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>%> 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"> |