mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-09-24 22:36:21 +02:00
Code Issues Packages Projects Releases Wiki Activity

documentation: poky-ref-manual, dev-manual - optional module packaging

Browse Source 
Fixes [YOCTO_#3366]

Created a new section titled "Handling Optional Module Packaging"
in the dev-manual.  This section is based on the wiki page
that Paul Eggleton authored.

Created a new glossary entry for PACKAGES_DYNAMIC in the
poky-ref-manual.

(From yocto-docs rev: 5af3da5e2af15c33e5e6eb7a9ef3ab3c0923284f)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2012-11-12 13:35:06 -06:00
committed by Richard Purdie
parent c2f14db4e0
commit ba0f4df644
2 changed files with 352 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@@ -1908,6 +1908,21 @@
</para> </para>
</section> </section>
<section id='working-with-packages'>
<title>Working with Packages</title>
<para>
This section describes a few tasks that involve packages:
<itemizedlist>
<listitem><para>Incrementing a package revision number
</para></listitem>
<listitem><para>Handling a package name alias
</para></listitem>
<listitem><para>Handling option module packaging
</para></listitem>
</itemizedlist>
</para>
<section id="usingpoky-changes-prbump"> <section id="usingpoky-changes-prbump">
<title>Incrementing a Package Revision Number</title> <title>Incrementing a Package Revision Number</title>
@@ -2017,6 +2032,221 @@
</para> </para>
</section> </section>
<section id='handling-optional-module-packaging'>
<title>Handling Optional Module Packaging</title>
<para>
Many pieces of software split functionality into optional
modules (or plugins) and the plugins that are built
might depend on configuration options.
To avoid having to duplicate the logic that determines what
modules are available in your recipe or to avoid having
to package each module by hand, the OpenEmbedded build system
provides functionality to handle module packaging dynamically.
</para>
<para>
To handle optional modual packaging, you need to do two things:
<itemizedlist>
<listitem><para>Ensure the module packaging is actually
done</para></listitem>
<listitem><para>Ensure that any dependencies on optional
modules from other recipes are satisfied by your recipe
</para></listitem>
</itemizedlist>
</para>
<section id='making-sure-the-packaging-is-done'>
<title>Making Sure the Packaging is Done</title>
<para>
To ensure the module packaging actually gets done, you use
the <filename>do_split_packages</filename> function within
the <filename>populate_packages</filename> python function
in your recipe.
The <filename>do_split_packages</filename> function
searches for a pattern of files or directories under a
specified path and creates a package for each one it finds
by appending to the <filename>PACKAGES</filename> variable
and setting the appropriate values for
<filename>FILES_packagename</filename>,
<filename>RDEPENDS_packagename</filename>,
<filename>DESCRIPTION_packagename</filename>, and so forth.
Here is an example from the <filename>lighttpd</filename>
recipe:
<literallayout class='monospaced'>
python populate_packages_prepend () {
lighttpd_libdir = d.expand('${libdir}')
do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
'lighttpd-module-%s', 'Lighttpd module for %s',
extra_depends='')
}
</literallayout>
The previous example specifies a number of things in the
call to <filename>do_split_packages</filename>.
<itemizedlist>
<listitem><para>A directory within the files installed
by your recipe through <filename>do_install</filename>
in which to search.</para></listitem>
<listitem><para>A regular expression to match module
files in that directory.
In the example, note the parentheses () that mark
the part of the expression from which the module
name should be derived.</para></listitem>
<listitem><para>A pattern to use for the package names.
</para></listitem>
<listitem><para>A description for each package.
</para></listitem>
<listitem><para>An empty string for
<filename>extra_depends</filename>, which disables
the default dependency on the main
<filename>lighttpd</filename> package.
Thus, if a file in <filename>${libdir}</filename>
called <filename>mod_alias.so</filename> is found,
a package called <filename>lighttpd-module-alias</filename>
is created for it and the <filename>DESCRIPTION</filename>
is set to "Lighttpd module for alias".</para></listitem>
</itemizedlist>
</para>
<para>
Often, packaging modules is as simple as the previous
example.
However, more advanced options exist that you can employ
to <filename>do_split_packages</filename> to modify its
behavior.
And, if you need to, you can add more logic by specifying
a hook function that is called for each package.
It is also perfectly acceptable to call
<filename>do_split_packages</filename> multiple times if
you have more than one set of modules to package.
</para>
<para>
For more examples that show how to use
<filename>do_split_packages</filename>, see the
<filename>connman.inc</filename> file in the
<filename>meta/recipes-connectivity/connman/</filename>
directory of the <filename>poky</filename> source repository.
You can also find examples in
<filename>meta/classes/kernel.bbclass</filename>.
</para>
<para>
Following is a reference that shows
<filename>do_split_packages</filename> mandatory and
optional arguments:
<literallayout class='monospaced'>
Mandatory arguments
root
The path in which to search
file_regex
Regular expression to match searched files.
Use parentheses () to mark the part of this
expression that should be used to derive the
module name (to be substituted where %s is
used in other function arguments as noted below)
output_pattern
Pattern to use for the package names. Must
include %s.
description
Description to set for each package. Must
include %s.
Optional arguments
postinst
Postinstall script to use for all packages
(as a string)
recursive
True to perform a recursive search - default
False
hook
A hook function to be called for every match.
The function will be called with the following
arguments (in the order listed):
f
Full path to the file/directory match
pkg
The package name
file_regex
As above
output_pattern
As above
modulename
The module name derived using file_regex
extra_depends
Extra runtime dependencies (RDEPENDS) to be
set for all packages. The default value of None
causes a dependency on the main package
(${PN}) - if you do not want this, pass empty
string '' for this parameter.
aux_files_pattern
Extra item(s) to be added to FILES for each
package. Can be a single string item or a list
of strings for multiple items. Must include %s.
postrm
postrm script to use for all packages (as a
string)
allow_dirs
True to allow directories to be matched -
default False
prepend
If True, prepend created packages to PACKAGES
instead of the default False which appends them
match_path
match file_regex on the whole relative path to
the root rather than just the file name
aux_files_pattern_verbatim
Extra item(s) to be added to FILES for each
package, using the actual derived module name
rather than converting it to something legal
for a package name. Can be a single string item
or a list of strings for multiple items. Must
include %s.
allow_links
True to allow symlinks to be matched - default
False
</literallayout>
</para>
</section>
<section id='satisfying-dependencies'>
<title>Satisfying Dependencies</title>
<para>
The second part for handling optional module packaging
is to ensure that any dependencies on optional modules
from other recipes are satisfied by your recipe.
You can be sure these dependencies are satisfied by
using the
<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
Here is an example that continues with the
<filename>lighttpd</filename> recipe shown earlier:
<literallayout class='monospaced'>
PACKAGES_DYNAMIC = "lighttpd-module-.*"
</literallayout>
The name specified in the regular expression can of
course be anything.
In this example, it is <filename>lighttpd-module-</filename>
and is specified as the prefix to ensure that any
<ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
on a package name starting with the prefix are satisfied
during build time.
If you are using <filename>do_split_packages</filename>
as described in the previous section, the value you put in
<filename>PACKAGES_DYNAMIC</filename> should correspond to
the name pattern specified in the call to
<filename>do_split_packages</filename>.
</para>
</section>
</section>
</section>
<section id="building-software-from-an-external-source"> <section id="building-software-from-an-external-source">
<title>Building Software from an External Source</title> <title>Building Software from an External Source</title>

32
documentation/poky-ref-manual/ref-variables.xml
View File

@@ -2012,6 +2012,38 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
</glossdef> </glossdef>
</glossentry> </glossentry>
<glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
<glossdef>
<para>
A promise that your recipe satisfies runtime dependencies
for optional modules that are found in other recipes.
<filename>PACKAGES_DYNAMIC</filename>
does not actually satisfy the dependencies, it only states that
they should be satisfied.
For example, if a hard, runtime dependency
(<filename>RDEPENDS</filename>) of another package is satisfied
at build time through the <filename>PACKAGES_DYNAMIC</filename>
variable, but a package with the module name is never actually
produced, then the other package will be broken.
Thus, if you attempt to include that package in an image,
you will get a dependency failure from the packaging system
during <filename>do_rootfs</filename>.
Typically, if there is a chance that such a situation can
occur and the package that is not created is valid
without the dependency being satisfied, then you should use
<filename>RRECOMMENDS</filename> (a soft runtime dependency)
instead of <filename>RDEPENDS</filename>.
</para>
<para>
For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
variable when you are splitting packages, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
in the Yocto Project Development Manual.
</para>
</glossdef>
</glossentry>
<glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm> <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
<glossdef> <glossdef>
<para>Specifies extra options that are passed to the <filename>make</filename> command during the <para>Specifies extra options that are passed to the <filename>make</filename> command during the