documentation: poky-ref-manual, dev-manual - optional module packaging
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
Richard Purdie
parent
c2f14db4e0
commit
ba0f4df644
|
|
@ -1908,6 +1908,21 @@
|
|||
</para>
|
||||
</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">
|
||||
<title>Incrementing a Package Revision Number</title>
|
||||
|
||||
|
|
@ -2017,6 +2032,221 @@
|
|||
</para>
|
||||
</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">
|
||||
<title>Building Software from an External Source</title>
|
||||
|
||||
|
|
|
|||
|
|
@ -2012,6 +2012,38 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
|
|||
</glossdef>
|
||||
</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>
|
||||
<glossdef>
|
||||
<para>Specifies extra options that are passed to the <filename>make</filename> command during the
|
||||
|
|
|
|||
Loading…
Reference in New Issue