Staging: Making includes and libraries available for building

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.

Taking bzip2 as an example you can see that it stages a header file and it's library files:

do_stage () {
    install -m 0644 bzlib.h ${STAGING_INCDIR}/
    oe_libinstall -a -so libbz2 ${STAGING_LIBDIR}
}

The oe_libinstall method used in the bzip2 recipe is described in the 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:

STAGING_INCDIR

The directory into which staged headers files should be installed. This is the equivalent of the standard /usr/include directory.

STAGING_LIBDIR

The directory into which staged library files should be installed. This is the equivalent of the standard /usr/lib directory.

Additional staging related variables are covered in the Staging directories section in ChapterReference.

Looking in the staging area under tmp you can see the result of the bzip2 recipes staging task:

%> 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

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:

DEPENDS = "zlib bzip2"
...
EXTRA_OECONF = "--disable-ldap \
        --with-zlib=${STAGING_LIBDIR}/.. \
        --with-bzip2=${STAGING_LIBDIR}/.. \
        --disable-selinux-support"

Bzip2 is referred to in two places in the recipe:

DEPENDS

Remember that DEPENDS 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 DEPENDS on bzip2 this ensures that this happens.

EXTRA_OECONF

This variable is used by the 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 --with-bzip2 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 .. 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.

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.