summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-11-12 13:35:06 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-12-03 13:52:55 +0000
commitba0f4df64440e416a6160b448c99d04d39d3b377 (patch)
tree90e7f6a751cf97554be33df60894ef7cd98e791d /documentation/dev-manual
parentc2f14db4e0dbcf623a8ebfa36e1a594e166ff710 (diff)
downloadpoky-ba0f4df64440e416a6160b448c99d04d39d3b377.tar.gz
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>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml410
1 files changed, 320 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 @@
1908 </para> 1908 </para>
1909 </section> 1909 </section>
1910 1910
1911 <section id="usingpoky-changes-prbump"> 1911 <section id='working-with-packages'>
1912 <title>Incrementing a Package Revision Number</title> 1912 <title>Working with Packages</title>
1913 1913
1914 <para> 1914 <para>
1915 If a committed change results in changing the package output, 1915 This section describes a few tasks that involve packages:
1916 then the value of the 1916 <itemizedlist>
1917 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> 1917 <listitem><para>Incrementing a package revision number
1918 variable needs to be increased 1918 </para></listitem>
1919 (or "bumped") as part of that commit. 1919 <listitem><para>Handling a package name alias
1920 For new recipes you should add the <filename>PR</filename> 1920 </para></listitem>
1921 variable and set its initial value equal to "r0", which is the default. 1921 <listitem><para>Handling option module packaging
1922 Even though the default value is "r0", the practice of adding it to a new recipe makes 1922 </para></listitem>
1923 it harder to forget to bump the variable when you make changes 1923 </itemizedlist>
1924 to the recipe in future.
1925 </para> 1924 </para>
1926 1925
1927 <para> 1926 <section id="usingpoky-changes-prbump">
1928 If you are sharing a common <filename>.inc</filename> file with multiple recipes, 1927 <title>Incrementing a Package Revision Number</title>
1929 you can also use the
1930 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
1931 variable to ensure that
1932 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
1933 <filename>.inc</filename> file itself is changed.
1934 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
1935 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
1936 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
1937 If the <filename>.inc</filename> file is changed then its
1938 <filename>INC_PR</filename> should be incremented.
1939 </para>
1940 1928
1941 <para> 1929 <para>
1942 When upgrading the version of a package, assuming the 1930 If a committed change results in changing the package output,
1943 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> 1931 then the value of the
1944 changes, the <filename>PR</filename> variable should be reset to "r0" 1932 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1945 (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>). 1933 variable needs to be increased
1946 </para> 1934 (or "bumped") as part of that commit.
1935 For new recipes you should add the <filename>PR</filename>
1936 variable and set its initial value equal to "r0", which is the default.
1937 Even though the default value is "r0", the practice of adding it to a new recipe makes
1938 it harder to forget to bump the variable when you make changes
1939 to the recipe in future.
1940 </para>
1947 1941
1948 <para> 1942 <para>
1949 Usually, version increases occur only to packages. 1943 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
1950 However, if for some reason <filename>PV</filename> changes but does not 1944 you can also use the
1951 increase, you can increase the 1945 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
1952 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename> 1946 variable to ensure that
1953 variable (Package Epoch). 1947 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
1954 The <filename>PE</filename> variable defaults to "0". 1948 <filename>.inc</filename> file itself is changed.
1955 </para> 1949 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
1950 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
1951 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
1952 If the <filename>.inc</filename> file is changed then its
1953 <filename>INC_PR</filename> should be incremented.
1954 </para>
1956 1955
1957 <para> 1956 <para>
1958 Version numbering strives to follow the 1957 When upgrading the version of a package, assuming the
1959 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> 1958 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
1960 Debian Version Field Policy Guidelines</ulink>. 1959 changes, the <filename>PR</filename> variable should be reset to "r0"
1961 These guidelines define how versions are compared and what "increasing" a version means. 1960 (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
1962 </para> 1961 </para>
1963 1962
1964 <para> 1963 <para>
1965 There are two reasons for following the previously mentioned guidelines. 1964 Usually, version increases occur only to packages.
1966 First, to ensure that when a developer updates and rebuilds, they get all the changes to 1965 However, if for some reason <filename>PV</filename> changes but does not
1967 the repository and do not have to remember to rebuild any sections. 1966 increase, you can increase the
1968 Second, to ensure that target users are able to upgrade their 1967 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
1969 devices using package manager commands such as <filename>opkg upgrade</filename> 1968 variable (Package Epoch).
1970 (or similar commands for dpkg/apt or rpm-based systems). 1969 The <filename>PE</filename> variable defaults to "0".
1971 </para> 1970 </para>
1972 1971
1973 <para> 1972 <para>
1974 The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. 1973 Version numbering strives to follow the
1975 </para> 1974 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
1976 </section> 1975 Debian Version Field Policy Guidelines</ulink>.
1976 These guidelines define how versions are compared and what "increasing" a version means.
1977 </para>
1977 1978
1978 <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> 1979 <para>
1979 <title>Handling a Package Name Alias</title> 1980 There are two reasons for following the previously mentioned guidelines.
1980 <para> 1981 First, to ensure that when a developer updates and rebuilds, they get all the changes to
1981 Sometimes a package name you are using might exist under an alias or as a similarly named 1982 the repository and do not have to remember to rebuild any sections.
1982 package in a different distribution. 1983 Second, to ensure that target users are able to upgrade their
1983 The OpenEmbedded build system implements a <filename>distro_check</filename> 1984 devices using package manager commands such as <filename>opkg upgrade</filename>
1984 task that automatically connects to major distributions 1985 (or similar commands for dpkg/apt or rpm-based systems).
1985 and checks for these situations. 1986 </para>
1986 If the package exists under a different name in a different distribution, you get a
1987 <filename>distro_check</filename> mismatch.
1988 You can resolve this problem by defining a per-distro recipe name alias using the
1989 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
1990 variable.
1991 </para>
1992 1987
1993 <para> 1988 <para>
1994 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename> 1989 The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
1995 variable: 1990 </para>
1996 <literallayout class='monospaced'> 1991 </section>
1992
1993 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
1994 <title>Handling a Package Name Alias</title>
1995 <para>
1996 Sometimes a package name you are using might exist under an alias or as a similarly named
1997 package in a different distribution.
1998 The OpenEmbedded build system implements a <filename>distro_check</filename>
1999 task that automatically connects to major distributions
2000 and checks for these situations.
2001 If the package exists under a different name in a different distribution, you get a
2002 <filename>distro_check</filename> mismatch.
2003 You can resolve this problem by defining a per-distro recipe name alias using the
2004 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
2005 variable.
2006 </para>
2007
2008 <para>
2009 Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
2010 variable:
2011 <literallayout class='monospaced'>
1997 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ 2012 DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
1998 distro2=package_name_alias2 \ 2013 distro2=package_name_alias2 \
1999 distro3=package_name_alias3 \ 2014 distro3=package_name_alias3 \
2000 ..." 2015 ..."
2001 </literallayout> 2016 </literallayout>
2002 </para> 2017 </para>
2003 2018
2004 <para> 2019 <para>
2005 If you have more than one distribution alias, separate them with a space. 2020 If you have more than one distribution alias, separate them with a space.
2006 Note that the build system currently automatically checks the 2021 Note that the build system currently automatically checks the
2007 Fedora, OpenSuSE, Debian, Ubuntu, 2022 Fedora, OpenSuSE, Debian, Ubuntu,
2008 and Mandriva distributions for source package recipes without having to specify them 2023 and Mandriva distributions for source package recipes without having to specify them
2009 using the <filename>DISTRO_PN_ALIAS</filename> variable. 2024 using the <filename>DISTRO_PN_ALIAS</filename> variable.
2010 For example, the following command generates a report that lists the Linux distributions 2025 For example, the following command generates a report that lists the Linux distributions
2011 that include the sources for each of the recipes. 2026 that include the sources for each of the recipes.
2012 <literallayout class='monospaced'> 2027 <literallayout class='monospaced'>
2013 $ bitbake world -f -c distro_check 2028 $ bitbake world -f -c distro_check
2014 </literallayout> 2029 </literallayout>
2015 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> 2030 The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
2016 file found in the Source Directory. 2031 file found in the Source Directory.
2017 </para> 2032 </para>
2033 </section>
2034
2035 <section id='handling-optional-module-packaging'>
2036 <title>Handling Optional Module Packaging</title>
2037
2038 <para>
2039 Many pieces of software split functionality into optional
2040 modules (or plugins) and the plugins that are built
2041 might depend on configuration options.
2042 To avoid having to duplicate the logic that determines what
2043 modules are available in your recipe or to avoid having
2044 to package each module by hand, the OpenEmbedded build system
2045 provides functionality to handle module packaging dynamically.
2046 </para>
2047
2048 <para>
2049 To handle optional modual packaging, you need to do two things:
2050 <itemizedlist>
2051 <listitem><para>Ensure the module packaging is actually
2052 done</para></listitem>
2053 <listitem><para>Ensure that any dependencies on optional
2054 modules from other recipes are satisfied by your recipe
2055 </para></listitem>
2056 </itemizedlist>
2057 </para>
2058
2059 <section id='making-sure-the-packaging-is-done'>
2060 <title>Making Sure the Packaging is Done</title>
2061
2062 <para>
2063 To ensure the module packaging actually gets done, you use
2064 the <filename>do_split_packages</filename> function within
2065 the <filename>populate_packages</filename> python function
2066 in your recipe.
2067 The <filename>do_split_packages</filename> function
2068 searches for a pattern of files or directories under a
2069 specified path and creates a package for each one it finds
2070 by appending to the <filename>PACKAGES</filename> variable
2071 and setting the appropriate values for
2072 <filename>FILES_packagename</filename>,
2073 <filename>RDEPENDS_packagename</filename>,
2074 <filename>DESCRIPTION_packagename</filename>, and so forth.
2075 Here is an example from the <filename>lighttpd</filename>
2076 recipe:
2077 <literallayout class='monospaced'>
2078 python populate_packages_prepend () {
2079 lighttpd_libdir = d.expand('${libdir}')
2080 do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
2081 'lighttpd-module-%s', 'Lighttpd module for %s',
2082 extra_depends='')
2083 }
2084 </literallayout>
2085 The previous example specifies a number of things in the
2086 call to <filename>do_split_packages</filename>.
2087 <itemizedlist>
2088 <listitem><para>A directory within the files installed
2089 by your recipe through <filename>do_install</filename>
2090 in which to search.</para></listitem>
2091 <listitem><para>A regular expression to match module
2092 files in that directory.
2093 In the example, note the parentheses () that mark
2094 the part of the expression from which the module
2095 name should be derived.</para></listitem>
2096 <listitem><para>A pattern to use for the package names.
2097 </para></listitem>
2098 <listitem><para>A description for each package.
2099 </para></listitem>
2100 <listitem><para>An empty string for
2101 <filename>extra_depends</filename>, which disables
2102 the default dependency on the main
2103 <filename>lighttpd</filename> package.
2104 Thus, if a file in <filename>${libdir}</filename>
2105 called <filename>mod_alias.so</filename> is found,
2106 a package called <filename>lighttpd-module-alias</filename>
2107 is created for it and the <filename>DESCRIPTION</filename>
2108 is set to "Lighttpd module for alias".</para></listitem>
2109 </itemizedlist>
2110 </para>
2111
2112 <para>
2113 Often, packaging modules is as simple as the previous
2114 example.
2115 However, more advanced options exist that you can employ
2116 to <filename>do_split_packages</filename> to modify its
2117 behavior.
2118 And, if you need to, you can add more logic by specifying
2119 a hook function that is called for each package.
2120 It is also perfectly acceptable to call
2121 <filename>do_split_packages</filename> multiple times if
2122 you have more than one set of modules to package.
2123 </para>
2124
2125 <para>
2126 For more examples that show how to use
2127 <filename>do_split_packages</filename>, see the
2128 <filename>connman.inc</filename> file in the
2129 <filename>meta/recipes-connectivity/connman/</filename>
2130 directory of the <filename>poky</filename> source repository.
2131 You can also find examples in
2132 <filename>meta/classes/kernel.bbclass</filename>.
2133 </para>
2134
2135 <para>
2136 Following is a reference that shows
2137 <filename>do_split_packages</filename> mandatory and
2138 optional arguments:
2139 <literallayout class='monospaced'>
2140 Mandatory arguments
2141
2142 root
2143 The path in which to search
2144 file_regex
2145 Regular expression to match searched files.
2146 Use parentheses () to mark the part of this
2147 expression that should be used to derive the
2148 module name (to be substituted where %s is
2149 used in other function arguments as noted below)
2150 output_pattern
2151 Pattern to use for the package names. Must
2152 include %s.
2153 description
2154 Description to set for each package. Must
2155 include %s.
2156
2157 Optional arguments
2158
2159 postinst
2160 Postinstall script to use for all packages
2161 (as a string)
2162 recursive
2163 True to perform a recursive search - default
2164 False
2165 hook
2166 A hook function to be called for every match.
2167 The function will be called with the following
2168 arguments (in the order listed):
2169
2170 f
2171 Full path to the file/directory match
2172 pkg
2173 The package name
2174 file_regex
2175 As above
2176 output_pattern
2177 As above
2178 modulename
2179 The module name derived using file_regex
2180
2181 extra_depends
2182 Extra runtime dependencies (RDEPENDS) to be
2183 set for all packages. The default value of None
2184 causes a dependency on the main package
2185 (${PN}) - if you do not want this, pass empty
2186 string '' for this parameter.
2187 aux_files_pattern
2188 Extra item(s) to be added to FILES for each
2189 package. Can be a single string item or a list
2190 of strings for multiple items. Must include %s.
2191 postrm
2192 postrm script to use for all packages (as a
2193 string)
2194 allow_dirs
2195 True to allow directories to be matched -
2196 default False
2197 prepend
2198 If True, prepend created packages to PACKAGES
2199 instead of the default False which appends them
2200 match_path
2201 match file_regex on the whole relative path to
2202 the root rather than just the file name
2203 aux_files_pattern_verbatim
2204 Extra item(s) to be added to FILES for each
2205 package, using the actual derived module name
2206 rather than converting it to something legal
2207 for a package name. Can be a single string item
2208 or a list of strings for multiple items. Must
2209 include %s.
2210 allow_links
2211 True to allow symlinks to be matched - default
2212 False
2213 </literallayout>
2214 </para>
2215 </section>
2216
2217 <section id='satisfying-dependencies'>
2218 <title>Satisfying Dependencies</title>
2219
2220 <para>
2221 The second part for handling optional module packaging
2222 is to ensure that any dependencies on optional modules
2223 from other recipes are satisfied by your recipe.
2224 You can be sure these dependencies are satisfied by
2225 using the
2226 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
2227 Here is an example that continues with the
2228 <filename>lighttpd</filename> recipe shown earlier:
2229 <literallayout class='monospaced'>
2230 PACKAGES_DYNAMIC = "lighttpd-module-.*"
2231 </literallayout>
2232 The name specified in the regular expression can of
2233 course be anything.
2234 In this example, it is <filename>lighttpd-module-</filename>
2235 and is specified as the prefix to ensure that any
2236 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
2237 and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
2238 on a package name starting with the prefix are satisfied
2239 during build time.
2240 If you are using <filename>do_split_packages</filename>
2241 as described in the previous section, the value you put in
2242 <filename>PACKAGES_DYNAMIC</filename> should correspond to
2243 the name pattern specified in the call to
2244 <filename>do_split_packages</filename>.
2245 </para>
2246 </section>
2247 </section>
2018 </section> 2248 </section>
2019 2249
2020 <section id="building-software-from-an-external-source"> 2250 <section id="building-software-from-an-external-source">
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-12 15:24:34 +0000