aboutsummaryrefslogtreecommitdiffstats
path: root/usermanual
diff options
context:
space:
mode:
authorJamie Lenehan <lenehan@twibble.org>2007-01-13 05:50:11 +0000
committerJamie Lenehan <lenehan@twibble.org>2007-01-13 05:50:11 +0000
commitbba22bb70eaa7c91aab7480678df4048f44b701e (patch)
tree9b1957f05a7da18e75ccd2844e9462c201f31194 /usermanual
parent9d2ec6bcbaa0f4a83db106a461ba9362da110fbf (diff)
downloadopenembedded-bba22bb70eaa7c91aab7480678df4048f44b701e.tar.gz
usermanual: More updated for the recipes chapter:
- Remove the structure section, it doesn't really fit in this chapter. - Fill in the introduction part of the directories section. - Fill out the packaging section.
Diffstat (limited to 'usermanual')
-rw-r--r--usermanual/chapters/recipes.xml563
1 files changed, 482 insertions, 81 deletions
diff --git a/usermanual/chapters/recipes.xml b/usermanual/chapters/recipes.xml
index bef96db3fe..8259f89b97 100644
--- a/usermanual/chapters/recipes.xml
+++ b/usermanual/chapters/recipes.xml
@@ -558,13 +558,6 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
<para></para>
</section>
- <section id="bb_structure" xreflabel="structure">
- <title>Structure</title>
-
- <para>talk about about what directories and files are involved - using
- bitbake stuff would cover this in detail, just short summary here</para>
- </section>
-
<section id="bb_sources" xreflabel="sources">
<title>Sources: Downloading, patching and additional files</title>
@@ -685,19 +678,84 @@ mv fixed.recipe.bb myrecipe.bb</screen></para>
<section id="bb_directories" xreflabel="directories">
<title>Directories: What goes where</title>
- <para>target directories</para>
+ <para>A large part of the work or a recipe is involved with specifying
+ where files and found and where they have to go. It's important for
+ example that programs do not try and use files from <emphasis
+ role="bold">/usr/include</emphasis> or <emphasis
+ role="bold">/usr/lib</emphasis> since they are for the host system, not
+ the target. Similarly you don't want programs installed into <emphasis
+ role="bold">/usr/bin</emphasis> since that may overwrite your host system
+ programs with versions that don't work on the host!</para>
+
+ <para>The following are some of the directories commonly referred to in
+ recipes and will be described in more detail in the rest of this
+ section:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Working directory: WORKDIR</term>
- <para>unpacked source directory</para>
+ <listitem>
+ <para>This working directory for a recipe is where archive files
+ will be extracted, plain files will be placed, subdirectories for
+ logs, installed files etc will be created.</para>
+ </listitem>
+ </varlistentry>
- <para>work directory</para>
+ <varlistentry>
+ <term>Unpacked source code directory: S</term>
- <para>files/filespath</para>
+ <listitem>
+ <para>This is where patches are applied and where the program is
+ expected to be compiled in.</para>
+ </listitem>
+ </varlistentry>
- <para>staging directories</para>
+ <varlistentry>
+ <term>Destination directory: D</term>
- <para>install directories</para>
+ <listitem>
+ <para>The destination directory. This is where your package should
+ be installed into. The packaging system will then take the files
+ from directories under here and package them up for installation on
+ the target.</para>
+ </listitem>
+ </varlistentry>
- <para></para>
+ <varlistentry>
+ <term>Installation directories: bindir, docdir, ...</term>
+
+ <listitem>
+ <para>There are a set of variables available to describe all of the
+ paths on the target that you may want to use. Recipes should use
+ these variables rather than hard coding any specific paths.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Staging directories: STAGING_LIBDIR, STAGING_INCDIR, ...</term>
+
+ <listitem>
+ <para>Staging directories are a special area for headers, libraries
+ and other files that are generated by one recipe that may be needed
+ by another recipe. A library package for example needs to make the
+ library and headers available to other recipes so that they can link
+ against them.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>File path directories: FILE, FILE_DIRNAME, FILESDIR,
+ FILESPATH</term>
+
+ <listitem>
+ <para>These directories are used to control where files are found.
+ Understanding these can help you separate patches for different
+ versions or releases of your recipes and/or use the same patch over
+ multiple versions etc.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<section>
<title>WORKDIR: The working directory</title>
@@ -1640,103 +1698,446 @@ inherit autotools</screen></para>
<section id="bb_packages" xreflabel="packages">
<title>Packaging: Defining packages and their contents</title>
- <para>[</para>
+ <para>A bitbake recipe is a set of instructions from creating one, or
+ more, packages for installation on the target device. Typically these are
+ .ipkg or .deb packages (although bitbake itself isn't associated with any
+ particular packaging format).</para>
- <para>Talk about multiple packages and putting things in those
- packages</para>
+ <para>By default several packages are produced automatically without any
+ special action required on the part of the recipe author. The following
+ example of the packaging output from the helloworld example above shows
+ this packaging in action:<screen>[NOTE: package helloworld-0.1-r0: task do_package_write: started
+NOTE: Not creating empty archive for helloworld-dbg-0.1-r0
+Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld_0.1-r0_sh4.ipk
+Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/helloworld-doc_0.1-r0_sh4.ipk
+NOTE: Not creating empty archive for helloworld-dev-0.1-r0
+NOTE: Not creating empty archive for helloworld-locale-0.1-r0
+NOTE: package helloworld-0.1-r0: task do_package_write: completed</screen>We
+ can see from above that the packaging did the following:</para>
- <para>philosophy of packaging - dbg, doc, dev, main package, libs,
- additional</para>
+ <itemizedlist>
+ <listitem>
+ <para>Created a main package, <emphasis
+ role="bold">helloworld_0.1-r0_sh4.ipk</emphasis>. This package
+ contains the helloworld binary <emphasis
+ role="bold">/usr/bin/helloworld</emphasis>.</para>
+ </listitem>
- <para>PACKAGES</para>
+ <listitem>
+ <para>Created a documentation package, <emphasis
+ role="bold">helloworld-doc_0.1-r0_sh4.ipk</emphasis>. This package
+ contains the readme file <emphasis
+ role="bold">/usr/share/doc/helloworld/README.txt</emphasis>.</para>
+ </listitem>
- <para>FILES</para>
+ <listitem>
+ <para>Considered creating a debug package, <emphasis
+ role="bold">helloworld-dbg-0.1-r0_sh4.ipk</emphasis>, a development
+ package <emphasis role="bold">helloworld-dev-0.1-r0_sh4.ipk</emphasis>
+ and a locale package <emphasis
+ role="bold">helloworld-locale-0.1-r0_sh4.ipk</emphasis>. It didn't
+ create the package due to the fact that it couldn't find any files
+ that would actually go in the package.</para>
+ </listitem>
+ </itemizedlist>
- <para>wildcards and how they effect dir/file selection</para>
+ <para>There are several things happening here which are important to
+ understand:</para>
- <para>debian naming?</para>
+ <orderedlist>
+ <listitem>
+ <para>There is a default set of packages that are considered for
+ creation. This set of packages is controlled via the <emphasis
+ role="bold">PACKAGES</emphasis> variable.</para>
+ </listitem>
- <para>-dbg packages and how to handle them</para>
+ <listitem>
+ <para>For each package there is a default set of files and/or
+ directories that are considered to belong to those packages. The
+ documentation packages for example include anything found <emphasis
+ role="bold">/usr/share/doc</emphasis>. The set of files and
+ directories is controlled via the <emphasis
+ role="bold">FILES_&lt;package-name&gt;</emphasis> variables.</para>
+ </listitem>
- <para>package ordering and how it effects wildcards</para>
+ <listitem>
+ <para>By default packages that contain no files are not created and no
+ error is generated. The decision to create empty packages or not is
+ controlled via the <emphasis role="bold">ALLOW_EMPTY</emphasis>
+ variable.</para>
+ </listitem>
+ </orderedlist>
- <para>modifying vs replacing PACKAGES</para>
+ <section>
+ <title>Philosophy</title>
- <para>"find tmp/&lt;package-name&gt;/install"</para>
+ <para>Separate packaging, where possible, is of high importance in
+ OpenEmbedded. Many of the target devices have limited storage space and
+ RAM and giving distributions and users the option of not installing a
+ part of the package they don't need allows them to reduce the amount of
+ storage space required.</para>
- <para>]</para>
+ <para>As an example almost no distributions will include documentation
+ or development libraries since they are not required for the day to day
+ operation of the device. In particular if your package provides multiple
+ binaries, and it would be common to only use one or the other, then you
+ should consider separating them into separate packages.</para>
- <para></para>
+ <para>By default several groups of files are automatically separate out,
+ including:</para>
- <para>The default assignment of PACKAGES and FILES is:</para>
+ <variablelist>
+ <varlistentry>
+ <term>dev</term>
- <variablelist>
- <varlistentry>
- <term>PACKAGES</term>
+ <listitem>
+ <para>Any files required for development. This includes header
+ files, static libraries, the shared library symlinks required only
+ for linking etc. These would only ever need to be installed by
+ someone attempt to compile applications on the target device.
+ While this does happen it is very uncommon and so these files are
+ automatically moved into a separate package</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>Lists the names of each of the packages which are to be
- generated.<screen>PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen></para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>doc</term>
- <varlistentry>
- <term>FILES_${PN}</term>
+ <listitem>
+ <para>Any documentation related files, including man pages. These
+ are files which are of informational purposes only. For many
+ embedded devices there is no way for the user to see any of the
+ documentation anyway, and documentation can consume a lot of
+ space. By separating these out they don't take any space by
+ default but distributions and/or users may choose to install them
+ if they need some documentation on a specific package.</para>
+ </listitem>
+ </varlistentry>
- <listitem>
- <para>The base package, this includes everything needed to actually
- run the application on the target system.<screen>FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*.so.* \
-${sysconfdir} ${sharedstatedir} ${localstatedir} /bin/* /sbin/* \
-/lib/*.so* ${datadir}/${PN} ${libdir}/${PN}/* ${datadir}/pixmaps \
-${datadir}/applications ${datadir}/idl ${datadir}/omf \
-${datadir}/sounds ${libdir}/bonobo/servers"</screen></para>
- </listitem>
- </varlistentry>
+ <varlistentry>
+ <term>locale</term>
- <varlistentry>
- <term>FILES_${PN}-dbg</term>
+ <listitem>
+ <para>Locale information provides translation information for
+ packages. Many users do not require these translations, and many
+ devices will only want to provide them for user visible
+ components, such as UI related items, and not for system binaries.
+ By separating these out it is left up to the distribution or users
+ to decide if they are required or not.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
- <listitem>
- <para>Non-stripped versions executable's. OE automatically runs
- strip on binary commands but leaves the originals in a .debug
- directory.<screen>FILES_${PN}-dbg = "${bindir}/.debug ${sbindir}/.debug \
-${libexecdir}/.debug ${libdir}/.debug /bin/.debug /sbin/.debug \
-/lib/.debug ${libdir}/${PN}/.debug"</screen></para>
- </listitem>
- </varlistentry>
+ <section>
+ <title>Default packages and files</title>
+
+ <para>The defaults package settings are defined in <emphasis
+ role="bold">conf/bitbake.conf</emphasis> and are suitable for a lot of
+ recipes without any changes. The following list shows the default values
+ for the packaging related variables:</para>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>PACKAGES</term>
+
+ <listitem>
+ <para>This variable lists the names of each of the packages that
+ are to be generated.<screen>PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen>Note
+ that the order of packages is important: the packages are
+ processed in the listed order. So if two packages specify the
+ same file then the first package listed in packages will get the
+ file. This is important when packages use wildcards to specify
+ their contents.</para>
+
+ <para>For example if the main package, <emphasis
+ role="bold">${PN}</emphasis>, contains <emphasis
+ role="bold">/usr/bin/*</emphasis> (i.e. all files in <emphasis
+ role="bold">/usr/bin</emphasis>), but you want <emphasis
+ role="bold">/usr/bin/tprogram</emphasis> in a separate package,
+ <emphasis role="bold">${PN}-tpackage</emphasis>, you would need
+ to either ensure that <emphasis
+ role="bold">${PN}-tpackage</emphasis> is listed prior to
+ <emphasis role="bold">${PN}</emphasis> in <emphasis
+ role="bold">PACKAGES</emphasis> or that <emphasis
+ role="bold">FILES_${PN}</emphasis> was modified to not contain
+ the wildcard that matches <emphasis
+ role="bold">/usr/bin/tprogram</emphasis>.</para>
+
+ <para>Note that the -dbg package contains the debugging
+ information that has been extracted from binaries and libraries
+ prior to them being stripped. This package should always be the
+ first package in the package list to ensure that the debugging
+ information is correctly extracted and moved to the package
+ prior to any other packaging decisions being made.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FILES_${PN}</term>
+
+ <listitem>
+ <para>The base package, this includes everything needed to
+ actually run the application on the target system.<screen>FILES_${PN} = "\
+ ${bindir}/* \
+ ${sbindir}/* \
+ ${libexecdir}/* \
+ ${libdir}/lib*.so.* \
+ ${sysconfdir} \
+ ${sharedstatedir} \
+ ${localstatedir} \
+ /bin/* \
+ /sbin/* \
+ /lib/*.so* \
+ ${datadir}/${PN} \
+ ${libdir}/${PN}/* \
+ ${datadir}/pixmaps \
+ ${datadir}/applications \
+ ${datadir}/idl \
+ ${datadir}/omf \
+ ${datadir}/sounds \
+ ${libdir}/bonobo/servers"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FILES_${PN}-dbg</term>
+
+ <listitem>
+ <para>The debugging information extracted from non-stripped
+ versions of libraries and executable's. OpenEmbedded
+ automatically extracts the debugging information into files in
+ .debug directories and then strips the original files.<screen>FILES_${PN}-dbg = "\
+ ${bindir}/.debug \
+ ${sbindir}/.debug \
+ ${libexecdir}/.debug \
+ ${libdir}/.debug \
+ /bin/.debug \
+ /sbin/.debug \
+ /lib/.debug \
+ ${libdir}/${PN}/.debug"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FILES_${PN}-doc</term>
+
+ <listitem>
+ <para>Documentation related files. All documentation is
+ separated into it's own package so that it does not need to be
+ installed unless explicitly required.<screen>FILES_${PN}-doc = "\
+ ${docdir} \
+ ${mandir} \
+ ${infodir} \
+ ${datadir}/gtk-doc \
+ ${datadir}/gnome/help"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FILES_${PN}-dev</term>
+
+ <listitem>
+ <para>Development related files. Any headers, libraries and
+ support files needed for development work on the target.<screen>FILES_${PN}-dev = "\
+ ${includedir} \
+ ${libdir}/lib*.so \
+ ${libdir}/*.la \
+ ${libdir}/*.a \
+ ${libdir}/*.o \
+ ${libdir}/pkgconfig \
+ /lib/*.a \
+ /lib/*.o \
+ ${datadir}/aclocal"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FILES_${PN}-locale</term>
+
+ <listitem>
+ <para>Locale related files.<screen>FILES_${PN}-locale = "${datadir}/locale"</screen></para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
- <varlistentry>
- <term>FILES_${PN}-doc</term>
+ <section>
+ <title>Wildcards</title>
+ <para>Wildcards used in the <emphasis role="bold">FILES</emphasis>
+ variables are processed via the python function <emphasis
+ role="bold">fnmatch</emphasis>. The following items are of note about
+ this function:</para>
+
+ <itemizedlist>
<listitem>
- <para>Documentation related files. All documentation is separated
- into it's own package so that it does not need to be installed
- unless explicitly required.<screen>FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
-${datadir}/gnome/help"</screen></para>
+ <para><emphasis role="bold">/&lt;dir&gt;/*</emphasis>: This will
+ match all files and directories in the <emphasis
+ role="bold">dir</emphasis>., it will not match other
+ directories.</para>
</listitem>
- </varlistentry>
-
- <varlistentry>
- <term>FILES_${PN}-dev</term>
<listitem>
- <para>Development related files. Any headers, libraries and support
- files needed for development work on the target.<screen>FILES_${PN}-dev = "${includedir} ${libdir}/lib*.so ${libdir}/*.la
-${libdir}/*.a ${libdir}/*.o ${libdir}/pkgconfig /lib/*.a /lib/*.o
-${datadir}/aclocal"</screen></para>
+ <para><emphasis role="bold">/&lt;dir&gt;/a*</emphasis>: This will
+ only match files, and not directories.</para>
</listitem>
- </varlistentry>
-
- <varlistentry>
- <term>FILES_${PN}-locale</term>
<listitem>
- <para>Locale related files.<screen>FILES_${PN}-locale = "${datadir}/locale"</screen></para>
+ <para><emphasis role="bold">/dir</emphasis>: will include the
+ directory <emphasis role="bold">dir</emphasis> in the package, which
+ in turn will include all files in the directory and all
+ subdirectories.</para>
</listitem>
- </varlistentry>
- </variablelist>
+ </itemizedlist>
- <para></para>
+ <para>Note that the order of packages effects the files that will be
+ matched via wildcards. Consider the case where we have three binaries in
+ the /usr/bin directory and we want the test program in a separate
+ package:<screen>/usr/bin/programa /usr/bin/programb /usr/bin/test</screen>So
+ we define are now package, list the file and included in the list of
+ packages:</para>
+
+ <screen>FILES-${PN}-test = "${bindir}/test"
+PACKAGES += "FILES-${PN}-test"</screen>
+
+ <para>When the package is regenerated no <emphasis
+ role="bold">${PN}-test</emphasis> package will be created. The reason
+ for this is that the <emphasis role="bold">PACKAGES</emphasis> line now
+ looks like this:<screen>{PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale ${PN}-test</screen>Note
+ how <emphasis role="bold">${PN}</emphasis> is listed prior to <emphasis
+ role="bold">${PN}-test</emphasis>, and if we look at the definition of
+ <emphasis role="bold">FILES-${PN}</emphasis> it contains the <emphasis
+ role="bold">${bindir}/*</emphasis> wildcard. Since <emphasis
+ role="bold">${PN}</emphasis> is first it'll match that wildcard are be
+ moved into the <emphasis role="bold">${PN}</emphasis> package prior to
+ processing of the <emphasis role="bold">${PN}-test</emphasis>
+ package.</para>
+
+ <para>To make these work we have two options:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Modify the definition of <emphasis
+ role="bold">${PN}</emphasis> so that the wildcard does not match the
+ test program.</para>
+
+ <para>We could do this for example:<screen>FILES-${PN} = "${bindir}/p*"</screen>So
+ now this will only match things in the bindir that start with p, and
+ therefore not match our test program. Note that <emphasis
+ role="bold">FILES-${PN}</emphasis> contains a lot more entries and
+ we'd need to add any of the other that refer to files that are to be
+ included in the package. In this case we have no other files, so
+ it's safe to do this simple declaration.</para>
+ </listitem>
+
+ <listitem>
+ <para>Modify the order of packages so that the <emphasis
+ role="bold">${PN}-test</emphasis> package is listed first.</para>
+
+ <para>The most obvious way to do this would be to prepend our new
+ package name to the packages list instead of appending it:<screen>PACKAGES =+ "FILES-${PN}-test"</screen>In
+ some cases this would work fine, however there is a problem with
+ this for packages that include binaries. The package will now be
+ listed before the -dbg package and often this will result in the
+ .debug directories being included in the package. In this case we
+ are explicitly listing only a single file (and not using wildcards)
+ and therefore it would be ok.</para>
+
+ <para>In general it's more common to have to redefine the entire
+ package list to include your new package plus any of the default
+ packages that you require:<screen>PACKAGES = "${PN}-dbg ${PN}-test ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen></para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Checking the packages</title>
+
+ <para>During recipe development it's useful to be able to check on
+ exactly what files went into each package, which files were not packaged
+ and which packages contain no files.</para>
+
+ <para>One of easiest method is to run find on the install directory. In
+ the install directory there is one subdirectory created per package, and
+ the files are moved into the install directory as they are matched to a
+ specific package. The following shows the packages and files for the
+ helloworld example:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/install
+tmp/work/helloworld-0.1-r0/install
+tmp/work/helloworld-0.1-r0/install/helloworld-locale
+tmp/work/helloworld-0.1-r0/install/helloworld-dbg
+tmp/work/helloworld-0.1-r0/install/helloworld-dev
+tmp/work/helloworld-0.1-r0/install/helloworld-doc
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld/README.txt
+tmp/work/helloworld-0.1-r0/install/helloworld
+tmp/work/helloworld-0.1-r0/install/helloworld/usr
+tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin
+tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld
+~/oe%&gt;</screen>The above shows that the -local, -dbg and -dev packages are
+ all empty, and the -doc and base package contain a single file each.
+ Uses "<emphasis role="bold">-type f</emphasis>" option to find to show
+ just files will make this clearer as well.</para>
+
+ <para>In addition to the install directory the image directory (which
+ corresponds to the destination directory, <emphasis
+ role="bold">D</emphasis>) will contain any files that were not
+ packaged:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/image
+tmp/work/helloworld-0.1-r0/image
+tmp/work/helloworld-0.1-r0/image/usr
+tmp/work/helloworld-0.1-r0/image/usr/bin
+tmp/work/helloworld-0.1-r0/image/usr/share
+tmp/work/helloworld-0.1-r0/image/usr/share/doc
+tmp/work/helloworld-0.1-r0/image/usr/share/doc/helloworld
+~/oe%&gt;</screen>In this case all files were packaged and so there are no
+ left over files. Using find with "<emphasis role="bold">-type
+ f</emphasis>" makes this much clearer:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/image -type f
+~/oe%&gt;</screen></para>
+
+ <para>Messages reading missing files are also display by bitbake during
+ the package task:<screen>NOTE: package helloworld-0.1-r0: task do_package: started
+NOTE: the following files were installed but not shipped in any package:
+NOTE: /usualdir/README.txt
+NOTE: package helloworld-0.1-r0: task do_package: completed</screen>Except in
+ very unusual circumstances there should be no unpackaged files left
+ behind by a recipe.</para>
+ </section>
+
+ <section>
+ <title>Debian naming</title>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>Empty packages</title>
+
+ <para>By default empty packages are ignored. Occasionally you may wish
+ to actually created empty packages, typically done when you want a
+ virtual package which will install other packages via dependencies
+ without actually installing anything itself. The <emphasis
+ role="bold">ALLOW_EMPTY</emphasis> variable is used to control the
+ creation of empty packages:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>ALLOW_EMPTY</term>
+
+ <listitem>
+ <para>Controls if empty packages will be created or not. By
+ default this is <emphasis role="bold">"0"</emphasis> and empty
+ packages are not created. Setting this to <emphasis
+ role="bold">"1"</emphasis> will permit the creation of empty
+ packages (packages containing no files).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para></para>
+ </section>
</section>
<section id="bb_tasks" xreflabel="tasks">