diff options
Diffstat (limited to 'yocto-poky/documentation/ref-manual/ref-classes.xml')
-rw-r--r-- | yocto-poky/documentation/ref-manual/ref-classes.xml | 378 |
1 files changed, 286 insertions, 92 deletions
diff --git a/yocto-poky/documentation/ref-manual/ref-classes.xml b/yocto-poky/documentation/ref-manual/ref-classes.xml index d87c9ff58..b2941b8bf 100644 --- a/yocto-poky/documentation/ref-manual/ref-classes.xml +++ b/yocto-poky/documentation/ref-manual/ref-classes.xml @@ -52,20 +52,22 @@ and a C library as pre-requisites, and splitting out of debug symbols during packaging). <note> - Unlike e.g. Debian, OpenEmbedded recipes that produce packages - which + <para>Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes + that produce packages that depend on tunings through use of the <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> - on + and <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link> - packages should never be made <filename>allarch</filename>, even - if they do not produce architecture-specific output. This would - cause the do_package_write_* tasks to have different signatures - for - <link linkend='var-MACHINE'><filename>MACHINE</filename></link>s - with different - <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>, - thus unnecessary rebuilds every single time an image for a different - MACHINE is built (even without any change to the recipe). + variables, should never be configured for all architectures + using <filename>allarch</filename>. + This is the case even if the recipes do not produce + architecture-specific output.</para> + <para>Configuring such recipes for all architectures causes the + <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link> + tasks to have different signatures for the machines with different + tunings. + Additionally, unnecessary rebuilds occur every time an + image for a different <filename>MACHINE</filename> is built + even when the recipe never changes.</para> </note> </para> @@ -101,55 +103,76 @@ </section> <section id='ref-classes-autotools'> - <title><filename>autotools.bbclass</filename></title> + <title><filename>autotools*.bbclass</filename></title> <para> - The <filename>autotools</filename> class supports Autotooled + The <filename>autotools*</filename> classes support Autotooled packages. </para> <para> The <filename>autoconf</filename>, <filename>automake</filename>, - and <filename>libtool</filename> bring standardization. - This class defines a set of tasks (configure, compile etc.) that + and <filename>libtool</filename> packages bring standardization. + This class defines a set of tasks (e.g. + <filename>configure</filename>, <filename>compile</filename> and + so forth) that work for all Autotooled packages. It should usually be enough to define a few standard variables and then simply <filename>inherit autotools</filename>. - This class can also work with software that emulates Autotools. + These classes can also work with software that emulates Autotools. For more information, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>" section in the Yocto Project Development Manual. </para> <para> - By default, the <filename>autotools</filename> class - uses out-of-tree builds + By default, the <filename>autotools*</filename> classes + use out-of-tree builds (i.e. + <filename>autotools.bbclass</filename> and + <filename>autotools_stage.bbclass</filename>). (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename> <link linkend='var-S'><filename>S</filename></link>). + </para> + + <para> If the software being built by a recipe does not support using out-of-tree builds, you should have the recipe inherit the - <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> - class. + <filename>autotools-brokensep</filename> class. + The <filename>autotools-brokensep</filename> class behaves the same + as the <filename>autotools</filename> and + <filename>autotools_stage</filename> classes but builds with + <link linkend='var-B'><filename>B</filename></link> == + <link linkend='var-S'><filename>S</filename></link>. + This method is useful when out-of-tree build support is either not + present or is broken. + <note> + It is recommended that out-of-tree support be fixed and used + if at all possible. + </note> </para> <para> - It's useful to have some idea of how the tasks defined by this class work - and what they do behind the scenes. + It's useful to have some idea of how the tasks defined by + the <filename>autotools*</filename> classes work and what they do + behind the scenes. <itemizedlist> <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - Regenerates the - configure script (using <filename>autoreconf</filename>) and then launches it - with a standard set of arguments used during cross-compilation. - You can pass additional parameters to <filename>configure</filename> through the + configure script (using <filename>autoreconf</filename>) and + then launches it with a standard set of arguments used during + cross-compilation. + You can pass additional parameters to + <filename>configure</filename> through the <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. </para></listitem> - <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - Runs <filename>make</filename> with - arguments that specify the compiler and linker. + <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - + Runs <filename>make</filename> with arguments that specify the + compiler and linker. You can pass additional arguments through the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. </para></listitem> - <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - Runs <filename>make install</filename> - and passes in + <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - + Runs <filename>make install</filename> and passes in <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> as <filename>DESTDIR</filename>. </para></listitem> @@ -157,25 +180,6 @@ </para> </section> -<section id='ref-classes-autotools-brokensep'> - <title><filename>autotools-brokensep.bbclass</filename></title> - - <para> - The <filename>autotools-brokensep</filename> class behaves the same - as the - <link linkend='ref-classes-autotools'><filename>autotools</filename></link> - class but builds with - <link linkend='var-B'><filename>B</filename></link> == - <link linkend='var-S'><filename>S</filename></link>. - This method is useful when out-of-tree build support is either not - present or is broken. - <note> - It is recommended that out-of-tree support be fixed and used - if at all possible. - </note> - </para> -</section> - <section id='ref-classes-base'> <title><filename>base.bbclass</filename></title> @@ -211,14 +215,22 @@ use for this class. <note> For RPMs and other packages that do not contain a subdirectory, - you should specify a "subdir" parameter. + you should specify an appropriate fetcher parameter to point to + the subdirectory. + For example, if BitBake is using the Git fetcher + (<filename>git://</filename>), the "subpath" parameter limits + the checkout to a specific subpath of the tree. Here is an example where <filename>${BP}</filename> is used so that the files are extracted into the subdirectory expected by the default value of <link linkend='var-S'><filename>S</filename></link>: <literallayout class='monospaced'> - SRC_URI = "http://example.com/downloads/somepackage.rpm;subdir=${BP}" + SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" </literallayout> + See the + "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>" + section in the BitBake User Manual for more information on + supported BitBake Fetchers. </note> </para> </section> @@ -552,10 +564,10 @@ </section> <section id='ref-classes-cpan'> - <title><filename>cpan.bbclass</filename></title> + <title><filename>cpan*.bbclass</filename></title> <para> - The <filename>cpan</filename> class supports Perl modules. + The <filename>cpan*</filename> classes support Perl modules. </para> <para> @@ -574,6 +586,8 @@ using <filename>cpan_build.bbclass</filename> in their recipes. </para></listitem> </itemizedlist> + Both build methods inherit the <filename>cpan-base</filename> class + for basic Perl support. </para> </section> @@ -707,25 +721,20 @@ <para> The class is not included by default. - To use it, you must include the following files and set the + To use it, you must set the <link linkend='var-INHERIT'><filename>INHERIT</filename></link> variable: <literallayout class='monospaced'> - include conf/distro/include/distro_alias.inc - include conf/distro/include/recipe_color.inc - include conf/distro/include/maintainers.inc - include conf/distro/include/upstream_tracking.inc - include conf/distro/include/package_regex.inc INHERIT+= "distrodata" </literallayout> </para> </section> <section id='ref-classes-distutils'> - <title><filename>distutils.bbclass</filename></title> + <title><filename>distutils*.bbclass</filename></title> <para> - The <filename>distutils</filename> class supports recipes for Python + The <filename>distutils*</filename> classes support recipes for Python version 2.x extensions, which are simple. These recipes usually only need to point to the source's archive and then inherit the proper class. @@ -733,8 +742,8 @@ module authors used. <itemizedlist> <listitem><para>Extensions that use an Autotools-based build system - require Autotools and - <filename>distutils</filename>-based classes in their recipes. + require Autotools and the classes based on + <filename>distutils</filename> in their recipes. </para></listitem> <listitem><para>Extensions that use build systems based on <filename>distutils</filename> require @@ -746,18 +755,26 @@ class in their recipes. </para></listitem> </itemizedlist> + The <filename>distutils-common-base</filename> class is required by + some of the <filename>distutils*</filename> classes to provide common + Python2 support. + </para> + + <para> + The <filename>distutils-tools</filename> class supports recipes for + additional "distutils" tools. </para> </section> <section id='ref-classes-distutils3'> - <title><filename>distutils3.bbclass</filename></title> + <title><filename>distutils3*.bbclass</filename></title> <para> - The <filename>distutils3</filename> class supports recipes for Python + The <filename>distutils3*</filename> classes support recipes for Python version 3.x extensions, which are simple. These recipes usually only need to point to the source's archive and then inherit the proper class. - Building is split into two methods depending on which method the + Building is split into three methods depending on which method the module authors used. <itemizedlist> <listitem><para>Extensions that use an Autotools-based build system @@ -774,6 +791,14 @@ class in their recipes. </para></listitem> </itemizedlist> + The <filename>distutils3*</filename> classes either inherit their + corresponding <filename>distutils*</filename> class or replicate them + using a Python3 version instead (e.g. + <filename>distutils3-base</filename> inherits + <filename>distutils-common-base</filename>, which is the same as + <filename>distutils-base</filename> but inherits + <filename>python3native</filename> instead of + <filename>pythonnative</filename>). </para> </section> @@ -905,6 +930,19 @@ </para> </section> +<section id='ref-classes-fs-uuid'> + <title><filename>fs-uuid.bbclass</filename></title> + + <para> + The <filename>fs-uuid</filename> class extracts UUID from + <filename>${</filename><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link><filename>}</filename>, + which must have been built by the time that this function gets called. + The <filename>fs-uuid</filename> class only works on + <filename>ext</filename> file systems and depends on + <filename>tune2fs</filename>. + </para> +</section> + <section id='ref-classes-gconf'> <title><filename>gconf.bbclass</filename></title> @@ -1255,6 +1293,15 @@ </para> </section> +<section id='ref-classes-image-buildinfo'> + <title><filename>image-buildinfo.bbclass</filename></title> + + <para> + The <filename>image-buildinfo</filename> class writes information + to the target filesystem on <filename>/etc/build</filename>. + </para> +</section> + <section id='ref-classes-image_types'> <title><filename>image_types.bbclass</filename></title> @@ -1364,10 +1411,21 @@ the OpenEmbedded build process. <note> This class is currently unmaintained. + The <filename>strace</filename> package needs to be installed + in the build host as a dependency for this tool. </note> </para> </section> +<section id='ref-classes-image-vm'> + <title><filename>image-vm.bbclass</filename></title> + + <para> + The <filename>image-vm</filename> class supports building VM + images. + </para> +</section> + <section id='ref-classes-image-vmdk'> <title><filename>image-vmdk.bbclass</filename></title> @@ -1868,6 +1926,25 @@ </para> </section> +<section id='ref-classes-kernel-fitimage'> + <title><filename>kernel-fitimage.bbclass</filename></title> + + <para> + The <filename>kernel-fitimage</filename> class provides support to + pack zImages. + </para> +</section> + +<section id='ref-classes-kernel-grub'> + <title><filename>kernel-grub.bbclass</filename></title> + + <para> + The <filename>kernel-grub</filename> class updates the boot area and + the boot menu with the kernel as the priority boot mechanism while + installing a RPM to update the kernel on a deployed target. + </para> +</section> + <section id='ref-classes-kernel-module-split'> <title><filename>kernel-module-split.bbclass</filename></title> @@ -1878,6 +1955,24 @@ </para> </section> +<section id='ref-classes-kernel-uboot'> + <title><filename>kernel-uboot.bbclass</filename></title> + + <para> + The <filename>kernel-uboot</filename> class provides support for + building from vmlinux-style kernel sources. + </para> +</section> + +<section id='ref-classes-kernel-uimage'> + <title><filename>kernel-uimage.bbclass</filename></title> + + <para> + The <filename>kernel-uimage</filename> class provides support to + pack uImage. + </para> +</section> + <section id='ref-classes-kernel-yocto'> <title><filename>kernel-yocto.bbclass</filename></title> @@ -1888,6 +1983,15 @@ </para> </section> +<section id='ref-classes-kernelsrc'> + <title><filename>kernelsrc.bbclass</filename></title> + + <para> + The <filename>kernelsrc</filename> class sets the Linux kernel + source and version. + </para> +</section> + <section id='ref-classes-lib_package'> <title><filename>lib_package.bbclass</filename></title> @@ -1902,6 +2006,25 @@ </para> </section> +<section id='ref-classes-libc*'> + <title><filename>libc*.bbclass</filename></title> + + <para> + The <filename>libc*</filename> classes support recipes that build + packages with <filename>libc</filename>: + <itemizedlist> + <listitem><para>The <filename>libc-common</filename> class + provides common support for building with + <filename>libc</filename>. + </para></listitem> + <listitem><para>The <filename>libc-package</filename> class + supports packaging up <filename>glibc</filename> and + <filename>eglibc</filename>. + </para></listitem> + </itemizedlist> + </para> +</section> + <section id='ref-classes-license'> <title><filename>license.bbclass</filename></title> @@ -1926,6 +2049,16 @@ </para> </section> +<section id='ref-classes-linuxloader'> + <title><filename>linuxloader.bbclass</filename></title> + + <para> + Provides the function <filename>linuxloader()</filename>, which gives + the value of the dynamic loader/linker provided on the platform. + This value is used by a number of other classes. + </para> +</section> + <section id='ref-classes-logging'> <title><filename>logging.bbclass</filename></title> @@ -1971,6 +2104,15 @@ </para> </section> +<section id='ref-classes-migrate_localcount'> + <title><filename>migrate_localcount.bbclass</filename></title> + + <para> + The <filename>migrate_localcount</filename> class verifies a recipe's + localcount data and increments it appropriately. + </para> +</section> + <section id='ref-classes-mime'> <title><filename>mime.bbclass</filename></title> @@ -2487,17 +2629,18 @@ <title><filename>pkgconfig.bbclass</filename></title> <para> - The <filename>pkg-config</filename> class provides a standard way to get - header and library information. + The <filename>pkgconfig</filename> class provides a standard way to get + header and library information by using <filename>pkg-config</filename>. This class aims to smooth integration of <filename>pkg-config</filename> into libraries that use it. </para> <para> - During staging, BitBake installs <filename>pkg-config</filename> data into the - <filename>sysroots/</filename> directory. - By making use of sysroot functionality within <filename>pkg-config</filename>, - this class no longer has to manipulate the files. + During staging, BitBake installs <filename>pkg-config</filename> + data into the <filename>sysroots/</filename> directory. + By making use of sysroot functionality within + <filename>pkg-config</filename>, the <filename>pkgconfig</filename> + class no longer has to manipulate the files. </para> </section> @@ -2536,6 +2679,9 @@ Supports creation of the SDK given the opkg (IPK format) package manager. </para></listitem> + <listitem><para><emphasis><filename>populate_sdk_ext</filename>:</emphasis> + Supports extensible SDK creation under all package managers. + </para></listitem> </itemizedlist> </para> @@ -2692,6 +2838,16 @@ </para> </section> +<section id='ref-classes-python3native'> + <title><filename>python3native.bbclass</filename></title> + + <para> + The <filename>python3native</filename> class supports using the + native version of Python 3 built by the build system rather than + support of the version provided by the build host. + </para> +</section> + <section id='ref-classes-pythonnative'> <title><filename>pythonnative.bbclass</filename></title> @@ -2773,6 +2929,16 @@ </para> </section> +<section id='ref-classes-recipe_sanity'> + <title><filename>recipe_sanity.bbclass</filename></title> + + <para> + The <filename>recipe_sanity</filename> class checks for the presence + of any host system recipe prerequisites that might affect the + build (e.g. variables that are set or software that is present). + </para> +</section> + <section id='ref-classes-relocatable'> <title><filename>relocatable.bbclass</filename></title> @@ -2871,6 +3037,11 @@ The <filename>rootfs_ipk</filename> class, which supports creation of root filesystems for images built using <filename>.ipk</filename> packages.</para></listitem> + <listitem><para> + The <filename>rootfsdebugfiles</filename> class, which installs + additional files found on the build host directly into the + root filesystem. + </para></listitem> </itemizedlist> </para> @@ -2948,6 +3119,15 @@ </para> </section> +<section id='ref-classes-sign_rpm'> + <title><filename>sign_rpm.bbclass</filename></title> + + <para> + The <filename>sign_rpm</filename> class supports generating signed + RPM packages. + </para> +</section> + <section id='ref-classes-sip'> <title><filename>sip.bbclass</filename></title> @@ -3181,28 +3361,40 @@ </para> </section> -<section id='ref-classes-testimage'> - <title><filename>testimage.bbclass</filename></title> +<section id='ref-classes-testimage*'> + <title><filename>testimage*.bbclass</filename></title> <para> - The <filename>testimage</filename> class supports running automated - tests against images using QEMU and on actual hardware. - The class handles loading the tests and starting the image. + The <filename>testimage*</filename> classes support running + automated tests against images using QEMU and on actual hardware. + The classes handle loading the tests and starting the image. + To use the classes, you need to perform steps to set up the + environment. </para> <para> - To use the class, you need to perform steps to set up the - environment. The tests are commands that run on the target system over <filename>ssh</filename>. - they are written in Python and make use of the + Each test is written in Python and makes use of the <filename>unittest</filename> module. </para> <para> + The <filename>testimage.bbclass</filename> runs tests on an image + when called using the following: + <literallayout class='monospaced'> + $ bitbake -c testimage <replaceable>image</replaceable> + </literallayout> + The <filename>testimage-auto</filename> class runs tests on an image + after the image is constructed (i.e. + <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link> + must be set to "1"). + </para> + + <para> For information on how to enable, run, and create new tests, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" - section. + section in the Yocto Project Development Manual. </para> </section> @@ -3385,24 +3577,29 @@ </section> <section id='ref-classes-useradd'> - <title><filename>useradd.bbclass</filename></title> + <title><filename>useradd*.bbclass</filename></title> <para> - The <filename>useradd</filename> class supports the addition of users + The <filename>useradd*</filename> classes support the addition of users or groups for usage by the package on the target. For example, if you have packages that contain system services that - should be run under their own user or group, you can use this class to - enable creation of the user or group. + should be run under their own user or group, you can use these classes + to enable creation of the user or group. The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename> recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> provides a simple example that shows how to add three users and groups to two packages. See the <filename>useradd-example.bb</filename> recipe for more - information on how to use this class. + information on how to use these classes. </para> <para> - The <filename>useradd</filename> class supports the + The <filename>useradd_base</filename> class provides basic + functionality for user or groups settings. + </para> + + <para> + The <filename>useradd*</filename> classes support the <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>, <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>, <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>, @@ -3410,10 +3607,6 @@ <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link> variables. </para> -</section> - -<section id='ref-classes-useradd-staticids'> - <title><filename>useradd-staticids.bbclass</filename></title> <para> The <filename>useradd-staticids</filename> class supports the addition @@ -3457,7 +3650,8 @@ </para> <note><title>Notes</title> - You do not use this class directly. + You do not use the <filename>useradd-staticids</filename> + class directly. You either enable or disable the class by setting the <filename>USERADDEXTENSION</filename> variable. If you enable or disable the class in a configured system, |