[oe-commits] org.oe.documentation usermanual: More updated for the recipes chapter:
lenehan commit
openembedded-commits at lists.openembedded.org
Sat Jan 13 05:54:08 UTC 2007
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.
Author: lenehan at openembedded.org
Branch: org.openembedded.documentation
Revision: b82c868ce076875d6e233944e06159919afc2ce4
ViewMTN: http://monotone.openembedded.org/revision.psp?id=b82c868ce076875d6e233944e06159919afc2ce4
Files:
1
usermanual/chapters/recipes.xml
Diffs:
#
# mt diff -r7e65f37c1d2a123cd1d71b74fb43fd2983bf0db0 -rb82c868ce076875d6e233944e06159919afc2ce4
#
#
#
# patch "usermanual/chapters/recipes.xml"
# from [2d8ef3de09f87d99d78baf281c80c86d23edadb1]
# to [b2b4056652ff43026f9f61d20176a084b7ea06ab]
#
============================================================
--- usermanual/chapters/recipes.xml 2d8ef3de09f87d99d78baf281c80c86d23edadb1
+++ usermanual/chapters/recipes.xml b2b4056652ff43026f9f61d20176a084b7ea06ab
@@ -558,13 +558,6 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<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,20 +678,85 @@ mv fixed.recipe.bb myrecipe.bb</screen><
<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>unpacked source directory</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>
- <para>work directory</para>
+ <variablelist>
+ <varlistentry>
+ <term>Working directory: WORKDIR</term>
- <para>files/filespath</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>staging directories</para>
+ <varlistentry>
+ <term>Unpacked source code directory: S</term>
- <para>install directories</para>
+ <listitem>
+ <para>This is where patches are applied and where the program is
+ expected to be compiled in.</para>
+ </listitem>
+ </varlistentry>
- <para></para>
+ <varlistentry>
+ <term>Destination directory: D</term>
+ <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>
+
+ <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_<package-name></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/<package-name>/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>
+ <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>FILE%s
>>> DIFF TRUNCATED @ 16K
More information about the Openembedded-commits
mailing list