From ba0f4df64440e416a6160b448c99d04d39d3b377 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 12 Nov 2012 13:35:06 -0600 Subject: [PATCH] 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 Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 410 ++++++++++++++---- .../poky-ref-manual/ref-variables.xml | 32 ++ 2 files changed, 352 insertions(+), 90 deletions(-) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index b909305f68..e9f55ce1db 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1908,113 +1908,343 @@ -
- Incrementing a Package Revision Number +
+ Working with Packages - If a committed change results in changing the package output, - then the value of the - PR - variable needs to be increased - (or "bumped") as part of that commit. - For new recipes you should add the PR - variable and set its initial value equal to "r0", which is the default. - Even though the default value is "r0", the practice of adding it to a new recipe makes - it harder to forget to bump the variable when you make changes - to the recipe in future. + This section describes a few tasks that involve packages: + + Incrementing a package revision number + + Handling a package name alias + + Handling option module packaging + + - - If you are sharing a common .inc file with multiple recipes, - you can also use the - INC_PR - variable to ensure that - the recipes sharing the .inc file are rebuilt when the - .inc file itself is changed. - The .inc file must set INC_PR - (initially to "r0"), and all recipes referring to it should set PR - to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. - If the .inc file is changed then its - INC_PR should be incremented. - +
+ Incrementing a Package Revision Number - - When upgrading the version of a package, assuming the - PV - changes, the PR variable should be reset to "r0" - (or "$(INC_PR).0" if you are using INC_PR). - + + If a committed change results in changing the package output, + then the value of the + PR + variable needs to be increased + (or "bumped") as part of that commit. + For new recipes you should add the PR + variable and set its initial value equal to "r0", which is the default. + Even though the default value is "r0", the practice of adding it to a new recipe makes + it harder to forget to bump the variable when you make changes + to the recipe in future. + - - Usually, version increases occur only to packages. - However, if for some reason PV changes but does not - increase, you can increase the - PE - variable (Package Epoch). - The PE variable defaults to "0". - + + If you are sharing a common .inc file with multiple recipes, + you can also use the + INC_PR + variable to ensure that + the recipes sharing the .inc file are rebuilt when the + .inc file itself is changed. + The .inc file must set INC_PR + (initially to "r0"), and all recipes referring to it should set PR + to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed. + If the .inc file is changed then its + INC_PR should be incremented. + - - Version numbering strives to follow the - - Debian Version Field Policy Guidelines. - These guidelines define how versions are compared and what "increasing" a version means. - + + When upgrading the version of a package, assuming the + PV + changes, the PR variable should be reset to "r0" + (or "$(INC_PR).0" if you are using INC_PR). + - - There are two reasons for following the previously mentioned guidelines. - First, to ensure that when a developer updates and rebuilds, they get all the changes to - the repository and do not have to remember to rebuild any sections. - Second, to ensure that target users are able to upgrade their - devices using package manager commands such as opkg upgrade - (or similar commands for dpkg/apt or rpm-based systems). - + + Usually, version increases occur only to packages. + However, if for some reason PV changes but does not + increase, you can increase the + PE + variable (Package Epoch). + The PE variable defaults to "0". + - - The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. - -
+ + Version numbering strives to follow the + + Debian Version Field Policy Guidelines. + These guidelines define how versions are compared and what "increasing" a version means. + -
- Handling a Package Name Alias - - Sometimes a package name you are using might exist under an alias or as a similarly named - package in a different distribution. - The OpenEmbedded build system implements a distro_check - task that automatically connects to major distributions - and checks for these situations. - If the package exists under a different name in a different distribution, you get a - distro_check mismatch. - You can resolve this problem by defining a per-distro recipe name alias using the - DISTRO_PN_ALIAS - variable. - + + There are two reasons for following the previously mentioned guidelines. + First, to ensure that when a developer updates and rebuilds, they get all the changes to + the repository and do not have to remember to rebuild any sections. + Second, to ensure that target users are able to upgrade their + devices using package manager commands such as opkg upgrade + (or similar commands for dpkg/apt or rpm-based systems). + - - Following is an example that shows how you specify the DISTRO_PN_ALIAS - variable: - + + The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. + +
+ +
+ Handling a Package Name Alias + + Sometimes a package name you are using might exist under an alias or as a similarly named + package in a different distribution. + The OpenEmbedded build system implements a distro_check + task that automatically connects to major distributions + and checks for these situations. + If the package exists under a different name in a different distribution, you get a + distro_check mismatch. + You can resolve this problem by defining a per-distro recipe name alias using the + DISTRO_PN_ALIAS + variable. + + + + Following is an example that shows how you specify the DISTRO_PN_ALIAS + variable: + DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ distro2=package_name_alias2 \ distro3=package_name_alias3 \ ..." - - + + - - If you have more than one distribution alias, separate them with a space. - Note that the build system currently automatically checks the - Fedora, OpenSuSE, Debian, Ubuntu, - and Mandriva distributions for source package recipes without having to specify them - using the DISTRO_PN_ALIAS variable. - For example, the following command generates a report that lists the Linux distributions - that include the sources for each of the recipes. - + + If you have more than one distribution alias, separate them with a space. + Note that the build system currently automatically checks the + Fedora, OpenSuSE, Debian, Ubuntu, + and Mandriva distributions for source package recipes without having to specify them + using the DISTRO_PN_ALIAS variable. + For example, the following command generates a report that lists the Linux distributions + that include the sources for each of the recipes. + $ bitbake world -f -c distro_check - - The results are stored in the build/tmp/log/distro_check-${DATETIME}.results - file found in the Source Directory. - + + The results are stored in the build/tmp/log/distro_check-${DATETIME}.results + file found in the Source Directory. + +
+ +
+ Handling Optional Module Packaging + + + 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. + + + + To handle optional modual packaging, you need to do two things: + + Ensure the module packaging is actually + done + Ensure that any dependencies on optional + modules from other recipes are satisfied by your recipe + + + + +
+ Making Sure the Packaging is Done + + + To ensure the module packaging actually gets done, you use + the do_split_packages function within + the populate_packages python function + in your recipe. + The do_split_packages 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 PACKAGES variable + and setting the appropriate values for + FILES_packagename, + RDEPENDS_packagename, + DESCRIPTION_packagename, and so forth. + Here is an example from the lighttpd + recipe: + + 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='') + } + + The previous example specifies a number of things in the + call to do_split_packages. + + A directory within the files installed + by your recipe through do_install + in which to search. + 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. + A pattern to use for the package names. + + A description for each package. + + An empty string for + extra_depends, which disables + the default dependency on the main + lighttpd package. + Thus, if a file in ${libdir} + called mod_alias.so is found, + a package called lighttpd-module-alias + is created for it and the DESCRIPTION + is set to "Lighttpd module for alias". + + + + + Often, packaging modules is as simple as the previous + example. + However, more advanced options exist that you can employ + to do_split_packages 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 + do_split_packages multiple times if + you have more than one set of modules to package. + + + + For more examples that show how to use + do_split_packages, see the + connman.inc file in the + meta/recipes-connectivity/connman/ + directory of the poky source repository. + You can also find examples in + meta/classes/kernel.bbclass. + + + + Following is a reference that shows + do_split_packages mandatory and + optional arguments: + + 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 + + +
+ +
+ Satisfying Dependencies + + + 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 + PACKAGES_DYNAMIC variable. + Here is an example that continues with the + lighttpd recipe shown earlier: + + PACKAGES_DYNAMIC = "lighttpd-module-.*" + + The name specified in the regular expression can of + course be anything. + In this example, it is lighttpd-module- + and is specified as the prefix to ensure that any + RDEPENDS + and RRECOMMENDS + on a package name starting with the prefix are satisfied + during build time. + If you are using do_split_packages + as described in the previous section, the value you put in + PACKAGES_DYNAMIC should correspond to + the name pattern specified in the call to + do_split_packages. + +
+
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml index 282d9f3090..4e7f85c37d 100644 --- a/documentation/poky-ref-manual/ref-variables.xml +++ b/documentation/poky-ref-manual/ref-variables.xml @@ -2012,6 +2012,38 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" + PACKAGES_DYNAMIC + + + A promise that your recipe satisfies runtime dependencies + for optional modules that are found in other recipes. + PACKAGES_DYNAMIC + does not actually satisfy the dependencies, it only states that + they should be satisfied. + For example, if a hard, runtime dependency + (RDEPENDS) of another package is satisfied + at build time through the PACKAGES_DYNAMIC + 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 do_rootfs. + 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 + RRECOMMENDS (a soft runtime dependency) + instead of RDEPENDS. + + + + For an example of how to use the PACKAGES_DYNAMIC + variable when you are splitting packages, see the + "Handling Optional Module Packaging" section + in the Yocto Project Development Manual. + + + + PARALLEL_MAKE Specifies extra options that are passed to the make command during the