diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml | 3715 |
1 files changed, 3715 insertions, 0 deletions
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml new file mode 100644 index 000000000..e919bd7eb --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml @@ -0,0 +1,3715 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='ref-classes'> +<title>Classes</title> + +<para> + Class files are used to abstract common functionality and share it amongst + multiple recipe (<filename>.bb</filename>) files. + To use a class file, you simply make sure the recipe inherits the class. + In most cases, when a recipe inherits a class it is enough to enable its + features. + There are cases, however, where in the recipe you might need to set + variables or override some default behavior. +</para> + +<para> + Any <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> usually + found in a recipe can also be placed in a class file. + Class files are identified by the extension <filename>.bbclass</filename> + and are usually placed in a <filename>classes/</filename> directory beneath + the <filename>meta*/</filename> directory found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + Class files can also be pointed to by + <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link> + (e.g. <filename>build/</filename>) in the same way as + <filename>.conf</filename> files in the <filename>conf</filename> directory. + Class files are searched for in + <link linkend='var-BBPATH'><filename>BBPATH</filename></link> + using the same method by which <filename>.conf</filename> files are + searched. +</para> + +<para> + This chapter discusses only the most useful and important classes. + Other classes do exist within the <filename>meta/classes</filename> + directory in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + You can reference the <filename>.bbclass</filename> files directly + for more information. +</para> + +<section id='ref-classes-allarch'> + <title><filename>allarch.bbclass</filename></title> + + <para> + The <filename>allarch</filename> class is inherited + by recipes that do not produce architecture-specific output. + The class disables functionality that is normally needed for recipes + that produce executable binaries (such as building the cross-compiler + and a C library as pre-requisites, and splitting out of debug symbols + during packaging). + <note> + <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> + and + <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link> + 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> + + <para> + By default, all recipes inherit the + <link linkend='ref-classes-base'><filename>base</filename></link> and + <link linkend='ref-classes-package'><filename>package</filename></link> + classes, which enable functionality + needed for recipes that produce executable output. + If your recipe, for example, only produces packages that contain + configuration files, media files, or scripts (e.g. Python and Perl), + then it should inherit the <filename>allarch</filename> class. + </para> +</section> + +<section id='ref-classes-archiver'> + <title><filename>archiver.bbclass</filename></title> + + <para> + The <filename>archiver</filename> class supports releasing + source code and other materials with the binaries. + </para> + + <para> + For more details on the source archiver, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" + section in the Yocto Project Development Manual. + You can also see the + <link linkend='var-ARCHIVER_MODE'><filename>ARCHIVER_MODE</filename></link> + variable for information about the variable flags (varflags) + that help control archive creation. + </para> +</section> + +<section id='ref-classes-autotools'> + <title><filename>autotools*.bbclass</filename></title> + + <para> + The <filename>autotools*</filename> classes support Autotooled + packages. + </para> + + <para> + The <filename>autoconf</filename>, <filename>automake</filename>, + 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>. + 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> classes + use out-of-tree builds (i.e. + <filename>autotools.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 + <filename>autotools-brokensep</filename> class. + The <filename>autotools-brokensep</filename> class behaves the same + as the <filename>autotools</filename> 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> + + <para> + 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 + <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. + 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 + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> + as <filename>DESTDIR</filename>. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-base'> + <title><filename>base.bbclass</filename></title> + + <para> + The <filename>base</filename> class is special in that every + <filename>.bb</filename> file implicitly inherits the class. + This class contains definitions for standard basic + tasks such as fetching, unpacking, configuring (empty by default), + compiling (runs any <filename>Makefile</filename> present), installing + (empty by default) and packaging (empty by default). + These classes are often overridden or extended by other classes + such as the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class or the + <link linkend='ref-classes-package'><filename>package</filename></link> + class. + The class also contains some commonly used functions such as + <filename>oe_runmake</filename>. + </para> +</section> + +<section id='ref-classes-bash-completion'> + <title><filename>bash-completion.bbclass</filename></title> + + <para> + Sets up packaging and dependencies appropriate for recipes that + build software that includes bash-completion data. + </para> +</section> + +<section id='ref-classes-bin-package'> + <title><filename>bin_package.bbclass</filename></title> + + <para> + The <filename>bin_package</filename> class is a + helper class for recipes that extract the contents of a binary package + (e.g. an RPM) and install those contents rather than building the + binary from source. + The binary package is extracted and new packages in the configured + output package format are created. + Extraction and installation of proprietary binaries is a good example + use for this class. + <note> + For RPMs and other packages that do not contain a subdirectory, + 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 = "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> + +<section id='ref-classes-binconfig'> + <title><filename>binconfig.bbclass</filename></title> + + <para> + The <filename>binconfig</filename> class helps to correct paths in + shell scripts. + </para> + + <para> + Before <filename>pkg-config</filename> had become widespread, libraries + shipped shell scripts to give information about the libraries and + include paths needed to build software (usually named + <filename>LIBNAME-config</filename>). + This class assists any recipe using such scripts. + </para> + + <para> + During staging, the OpenEmbedded build system installs such scripts + into the <filename>sysroots/</filename> directory. + Inheriting this class results in all paths in these scripts being + changed to point into the <filename>sysroots/</filename> directory so + that all builds that use the script use the correct directories + for the cross compiling layout. + See the + <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link> + variable for more information. + </para> +</section> + +<section id='ref-classes-binconfig-disabled'> + <title><filename>binconfig-disabled.bbclass</filename></title> + + <para> + An alternative version of the + <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> + class, which disables binary configuration scripts by making them + return an error in favor of using <filename>pkg-config</filename> + to query the information. + The scripts to be disabled should be specified using the + <link linkend='var-BINCONFIG'><filename>BINCONFIG</filename></link> + variable within the recipe inheriting the class. + </para> +</section> + +<section id='ref-classes-blacklist'> + <title><filename>blacklist.bbclass</filename></title> + + <para> + The <filename>blacklist</filename> class prevents + the OpenEmbedded build system from building specific recipes + (blacklists them). + To use this class, inherit the class globally and set + <link linkend='var-PNBLACKLIST'><filename>PNBLACKLIST</filename></link> + for each recipe you wish to blacklist. + Specify the <link linkend='var-PN'><filename>PN</filename></link> + value as a variable flag (varflag) and provide a reason, which is + reported, if the package is requested to be built as the value. + For example, if you want to blacklist a recipe called "exoticware", + you add the following to your <filename>local.conf</filename> + or distribution configuration: + <literallayout class='monospaced'> + INHERIT += "blacklist" + PNBLACKLIST[exoticware] = "Not supported by our organization." + </literallayout> + </para> +</section> + +<section id='ref-classes-bluetooth'> + <title><filename>bluetooth.bbclass</filename></title> + + <para> + The <filename>bluetooth</filename> class defines a variable that + expands to the recipe (package) providing core + bluetooth support on the platform. + </para> + + <para> + For details on how the class works, see the + <filename>meta/classes/bluetooth.bbclass</filename> file in the Yocto + Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </para> +</section> + +<section id='ref-classes-bugzilla'> + <title><filename>bugzilla.bbclass</filename></title> + + <para> + The <filename>bugzilla</filename> class supports setting up an + instance of Bugzilla in which you can automatically files bug reports + in response to build failures. + For this class to work, you need to enable the XML-RPC interface in + the instance of Bugzilla. + </para> +</section> + +<section id='ref-classes-buildhistory'> + <title><filename>buildhistory.bbclass</filename></title> + + <para> + The <filename>buildhistory</filename> class records a + history of build output metadata, which can be used to detect possible + regressions as well as used for analysis of the build output. + For more information on using Build History, see the + "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" + section. + </para> +</section> + +<section id='ref-classes-buildstats'> + <title><filename>buildstats.bbclass</filename></title> + + <para> + The <filename>buildstats</filename> class records + performance statistics about each task executed during the build + (e.g. elapsed time, CPU usage, and I/O usage). + </para> + + <para> + When you use this class, the output goes into the + <link linkend='var-BUILDSTATS_BASE'><filename>BUILDSTATS_BASE</filename></link> + directory, which defaults to <filename>${TMPDIR}/buildstats/</filename>. + You can analyze the elapsed time using + <filename>scripts/pybootchartgui/pybootchartgui.py</filename>, which + produces a cascading chart of the entire build process and can be + useful for highlighting bottlenecks. + </para> + + <para> + Collecting build statistics is enabled by default through the + <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link> + variable from your <filename>local.conf</filename> file. + Consequently, you do not have to do anything to enable the class. + However, if you want to disable the class, simply remove "buildstats" + from the <filename>USER_CLASSES</filename> list. + </para> +</section> + +<section id='ref-classes-buildstats-summary'> + <title><filename>buildstats-summary.bbclass</filename></title> + + <para> + When inherited globally, prints statistics at the end of the build + on sstate re-use. + In order to function, this class requires the + <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link> + class be enabled. + </para> +</section> + +<section id='ref-classes-ccache'> + <title><filename>ccache.bbclass</filename></title> + + <para> + The <filename>ccache</filename> class enables the + <ulink url='http://ccache.samba.org/'>C/C++ Compiler Cache</ulink> + for the build. + This class is used to give a minor performance boost during the build. + However, using the class can lead to unexpected side-effects. + Thus, it is recommended that you do not use this class. + See <ulink url='http://ccache.samba.org/'></ulink> for information on + the C/C++ Compiler Cache. + </para> +</section> + +<section id='ref-classes-chrpath'> + <title><filename>chrpath.bbclass</filename></title> + + <para> + The <filename>chrpath</filename> class + is a wrapper around the "chrpath" utility, which is used during the + build process for <filename>nativesdk</filename>, + <filename>cross</filename>, and + <filename>cross-canadian</filename> recipes to change + <filename>RPATH</filename> records within binaries in order to make + them relocatable. + </para> +</section> + +<section id='ref-classes-clutter'> + <title><filename>clutter.bbclass</filename></title> + + <para> + The <filename>clutter</filename> class consolidates the + major and minor version naming and other common items used by Clutter + and related recipes. + <note> + Unlike some other classes related to specific libraries, recipes + building other software that uses Clutter do not need to + inherit this class unless they use the same recipe versioning + scheme that the Clutter and related recipes do. + </note> + </para> +</section> + +<section id='ref-classes-cmake'> + <title><filename>cmake.bbclass</filename></title> + + <para> + The <filename>cmake</filename> class allows for + recipes that need to build software using the CMake build system. + You can use the + <link linkend='var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></link> + variable to specify additional configuration options to be passed on + the <filename>cmake</filename> command line. + </para> +</section> + +<section id='ref-classes-cml1'> + <title><filename>cml1.bbclass</filename></title> + + <para> + The <filename>cml1</filename> class provides basic support for the + Linux kernel style build configuration system. + </para> +</section> + +<section id='ref-classes-compress_doc'> + <title><filename>compress_doc.bbclass</filename></title> + + <para> + Enables compression for man pages and info pages. + This class is intended to be inherited globally. + The default compression mechanism is gz (gzip) but you can + select an alternative mechanism by setting the + <link linkend='var-DOC_COMPRESS'><filename>DOC_COMPRESS</filename></link> + variable. + </para> +</section> + +<section id='ref-classes-copyleft_compliance'> + <title><filename>copyleft_compliance.bbclass</filename></title> + + <para> + The <filename>copyleft_compliance</filename> class + preserves source code for the purposes of license compliance. + This class is an alternative to the <filename>archiver</filename> + class and is still used by some users even though it has been + deprecated in favor of the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + </para> +</section> + +<section id='ref-classes-copyleft_filter'> + <title><filename>copyleft_filter.bbclass</filename></title> + + <para> + A class used by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + and + <link linkend='ref-classes-copyleft_compliance'><filename>copyleft_compliance</filename></link> + classes for filtering licenses. + The <filename>copyleft_filter</filename> class is an internal class + and is not intended to be used directly. + </para> +</section> + +<section id='ref-classes-core-image'> + <title><filename>core-image.bbclass</filename></title> + + <para> + The <filename>core-image</filename> class + provides common definitions for the + <filename>core-image-*</filename> image recipes, such as support for + additional + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. + </para> +</section> + +<section id='ref-classes-cpan'> + <title><filename>cpan*.bbclass</filename></title> + + <para> + The <filename>cpan*</filename> classes support Perl modules. + </para> + + <para> + Recipes for Perl modules are simple. + These recipes usually only need to point to the source's archive and + then inherit the proper class file. + Building is split into two methods depending on which method the module + authors used. + <itemizedlist> + <listitem><para>Modules that use old + <filename>Makefile.PL</filename>-based build system require + <filename>cpan.bbclass</filename> in their recipes. + </para></listitem> + <listitem><para>Modules that use + <filename>Build.PL</filename>-based build system require + 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> + +<section id='ref-classes-cross'> + <title><filename>cross.bbclass</filename></title> + + <para> + The <filename>cross</filename> class provides support for the recipes + that build the cross-compilation tools. + </para> +</section> + +<section id='ref-classes-cross-canadian'> + <title><filename>cross-canadian.bbclass</filename></title> + + <para> + The <filename>cross-canadian</filename> class + provides support for the recipes that build the Canadian + Cross-compilation tools for SDKs. + See the + "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" + section for more discussion on these cross-compilation tools. + </para> +</section> + +<section id='ref-classes-crosssdk'> + <title><filename>crosssdk.bbclass</filename></title> + + <para> + The <filename>crosssdk</filename> class + provides support for the recipes that build the cross-compilation + tools used for building SDKs. + See the + "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" + section for more discussion on these cross-compilation tools. + </para> +</section> + +<section id='ref-classes-debian'> + <title><filename>debian.bbclass</filename></title> + + <para> + The <filename>debian</filename> class renames output packages so that + they follow the Debian naming policy (i.e. <filename>glibc</filename> + becomes <filename>libc6</filename> and <filename>glibc-devel</filename> + becomes <filename>libc6-dev</filename>.) + Renaming includes the library name and version as part of the package + name. + </para> + + <para> + If a recipe creates packages for multiple libraries + (shared object files of <filename>.so</filename> type), use the + <link linkend='var-LEAD_SONAME'><filename>LEAD_SONAME</filename></link> + variable in the recipe to specify the library on which to apply the + naming scheme. + </para> +</section> + +<section id='ref-classes-deploy'> + <title><filename>deploy.bbclass</filename></title> + + <para> + The <filename>deploy</filename> class handles deploying files + to the + <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link> + directory. + The main function of this class is to allow the deploy step to be + accelerated by shared state. + Recipes that inherit this class should define their own + <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link> + function to copy the files to be deployed to + <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>, + and use <filename>addtask</filename> to add the task at the appropriate + place, which is usually after + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + or + <link linkend='ref-tasks-install'><filename>do_install</filename></link>. + The class then takes care of staging the files from + <filename>DEPLOYDIR</filename> to + <filename>DEPLOY_DIR_IMAGE</filename>. + </para> +</section> + +<section id='ref-classes-devshell'> + <title><filename>devshell.bbclass</filename></title> + + <para> + The <filename>devshell</filename> class adds the + <filename>do_devshell</filename> task. + Distribution policy dictates whether to include this class. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section + in the Yocto Project Development Manual for more information about + using <filename>devshell</filename>. + </para> +</section> + +<section id='ref-classes-distro_features_check'> + <title><filename>distro_features_check.bbclass</filename></title> + + <para> + The <filename>distro_features_check</filename> class + allows individual recipes to check for required and conflicting + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + </para> + + <para> + This class provides support for the + <link linkend='var-REQUIRED_DISTRO_FEATURES'><filename>REQUIRED_DISTRO_FEATURES</filename></link> + and + <link linkend='var-CONFLICT_DISTRO_FEATURES'><filename>CONFLICT_DISTRO_FEATURES</filename></link> + variables. + If any conditions specified in the recipe using the above variables are + not met, the recipe will be skipped. + </para> +</section> + +<section id='ref-classes-distrodata'> + <title><filename>distrodata.bbclass</filename></title> + + <para> + The <filename>distrodata</filename> class + provides for automatic checking for upstream recipe updates. + The class creates a comma-separated value (CSV) spreadsheet that + contains information about the recipes. + The information provides the + <link linkend='ref-tasks-distrodata'><filename>do_distrodata</filename></link> + and + <filename>do_distro_check</filename> tasks, which do upstream checking + and also verify if a package is used in multiple major distributions. + </para> + + <para> + The class is not included by default. + To use it, you must set the + <link linkend='var-INHERIT'><filename>INHERIT</filename></link> + variable: + <literallayout class='monospaced'> + INHERIT+= "distrodata" + </literallayout> + </para> + + <para> + The <filename>distrodata</filename> class also provides the + <link linkend='ref-tasks-checkpkg'><filename>do_checkpkg</filename></link> + task, which can be used against a simple recipe or against an + image to get all its recipe information. + </para> +</section> + +<section id='ref-classes-distutils'> + <title><filename>distutils*.bbclass</filename></title> + + <para> + 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. + Building is split into two methods depending on which method the + module authors used. + <itemizedlist> + <listitem><para>Extensions that use an Autotools-based build system + 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 + the <filename>distutils</filename> class in their recipes. + </para></listitem> + <listitem><para>Extensions that use build systems based on + <filename>setuptools</filename> require the + <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link> + 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> + + <para> + 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 three methods depending on which method the + 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. + </para></listitem> + <listitem><para>Extensions that use + <filename>distutils</filename>-based build systems require + the <filename>distutils</filename> class in their recipes. + </para></listitem> + <listitem><para>Extensions that use build systems based on + <filename>setuptools3</filename> require the + <link linkend='ref-classes-setuptools'><filename>setuptools3</filename></link> + 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> + +<section id='ref-classes-externalsrc'> + <title><filename>externalsrc.bbclass</filename></title> + + <para> + The <filename>externalsrc</filename> class supports building software + from source code that is external to the OpenEmbedded build system. + Building software from an external source tree means that the build + system's normal fetch, unpack, and patch process is not used. + </para> + + <para> + By default, the OpenEmbedded build system uses the + <link linkend='var-S'><filename>S</filename></link> and + <link linkend='var-B'><filename>B</filename></link> variables to + locate unpacked recipe source code and to build it, respectively. + When your recipe inherits the <filename>externalsrc</filename> class, + you use the + <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link> + and + <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link> + variables to ultimately define <filename>S</filename> and + <filename>B</filename>. + </para> + + <para> + By default, this class expects the source code to support recipe builds + that use the <link linkend='var-B'><filename>B</filename></link> + variable to point to the directory in which the OpenEmbedded build + system places the generated objects built from the recipes. + By default, the <filename>B</filename> directory is set to the + following, which is separate from the source directory + (<filename>S</filename>): + <literallayout class='monospaced'> + ${WORKDIR}/${BPN}/{PV}/ + </literallayout> + See these variables for more information: + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>, + <link linkend='var-BPN'><filename>BPN</filename></link>, and + <link linkend='var-PV'><filename>PV</filename></link>, + </para> + + <para> + For more information on the + <filename>externalsrc</filename> class, see the comments in + <filename>meta/classes/externalsrc.bbclass</filename> in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + For information on how to use the <filename>externalsrc</filename> + class, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>" + section in the Yocto Project Development Manual. + </para> +</section> + +<section id='ref-classes-extrausers'> + <title><filename>extrausers.bbclass</filename></title> + + <para> + The <filename>extrausers</filename> class allows + additional user and group configuration to be applied at the image + level. + Inheriting this class either globally or from an image recipe allows + additional user and group operations to be performed using the + <link linkend='var-EXTRA_USERS_PARAMS'><filename>EXTRA_USERS_PARAMS</filename></link> + variable. + <note> + The user and group operations added using the + <filename>extrausers</filename> class are not tied to a specific + recipe outside of the recipe for the image. + Thus, the operations can be performed across the image as a whole. + Use the + <link linkend='ref-classes-useradd'><filename>useradd</filename></link> + class to add user and group configuration to a specific recipe. + </note> + Here is an example that uses this class in an image recipe: + <literallayout class='monospaced'> + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -p '' tester; \ + groupadd developers; \ + userdel nobody; \ + groupdel -g video; \ + groupmod -g 1020 developers; \ + usermod -s /bin/sh tester; \ + " + </literallayout> + Here is an example that adds two users named "tester-jim" and + "tester-sue" and assigns passwords: + <literallayout class='monospaced'> + inherit extrausers + EXTRA_USERS_PARAMS = "\ + useradd -P tester01 tester-jim; \ + useradd -P tester01 tester-sue; \ + " + </literallayout> + Finally, here is an example that sets the root password to + "1876*18": + <literallayout class='monospaced'> + inherit extrausers + EXTRA_USERS_PARAMS = "\ + usermod -P 1876*18 root; \ + " + </literallayout> + </para> +</section> + +<section id='ref-classes-fontcache'> + <title><filename>fontcache.bbclass</filename></title> + + <para> + The <filename>fontcache</filename> class generates the + proper post-install and post-remove (postinst and postrm) + scriptlets for font packages. + These scriptlets call <filename>fc-cache</filename> (part of + <filename>Fontconfig</filename>) to add the fonts to the font + information cache. + Since the cache files are architecture-specific, + <filename>fc-cache</filename> runs using QEMU if the postinst + scriptlets need to be run on the build host during image creation. + </para> + + <para> + If the fonts being installed are in packages other than the main + package, set + <link linkend='var-FONT_PACKAGES'><filename>FONT_PACKAGES</filename></link> + to specify the packages containing the fonts. + </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> + + <para> + The <filename>gconf</filename> class provides common + functionality for recipes that need to install GConf schemas. + The schemas will be put into a separate package + (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-gconf</filename>) + that is created automatically when this class is inherited. + This package uses the appropriate post-install and post-remove + (postinst/postrm) scriptlets to register and unregister the schemas + in the target image. + </para> +</section> + +<section id='ref-classes-gettext'> + <title><filename>gettext.bbclass</filename></title> + + <para> + The <filename>gettext</filename> class provides support for + building software that uses the GNU <filename>gettext</filename> + internationalization and localization system. + All recipes building software that use + <filename>gettext</filename> should inherit this class. + </para> +</section> + +<section id='ref-classes-gnome'> + <title><filename>gnome.bbclass</filename></title> + + <para> + The <filename>gnome</filename> class supports recipes that + build software from the GNOME stack. + This class inherits the + <link linkend='ref-classes-gnomebase'><filename>gnomebase</filename></link>, + <link linkend='ref-classes-gtk-icon-cache'><filename>gtk-icon-cache</filename></link>, + <link linkend='ref-classes-gconf'><filename>gconf</filename></link> and + <link linkend='ref-classes-mime'><filename>mime</filename></link> classes. + The class also disables GObject introspection where applicable. + </para> +</section> + +<section id='ref-classes-gnomebase'> + <title><filename>gnomebase.bbclass</filename></title> + + <para> + The <filename>gnomebase</filename> class is the base + class for recipes that build software from the GNOME stack. + This class sets + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> to + download the source from the GNOME mirrors as well as extending + <link linkend='var-FILES'><filename>FILES</filename></link> + with the typical GNOME installation paths. + </para> +</section> + +<section id='ref-classes-gobject-introspection'> + <title><filename>gobject-introspection.bbclass</filename></title> + + <para> + Provides support for recipes building software that + supports GObject introspection. + This functionality is only enabled if the + "gobject-introspection-data" feature is in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + as well as "qemu-usermode" being in + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. + <note> + This functionality is backfilled by default and, + if not applicable, should be disabled through + <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> + or + <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>, + respectively. + </note> + </para> +</section> + +<section id='ref-classes-grub-efi'> + <title><filename>grub-efi.bbclass</filename></title> + + <para> + The <filename>grub-efi</filename> + class provides <filename>grub-efi</filename>-specific functions for + building bootable images. + </para> + + <para> + This class supports several variables: + <itemizedlist> + <listitem><para> + <link linkend='var-INITRD'><filename>INITRD</filename></link>: + Indicates list of filesystem images to concatenate and use + as an initial RAM disk (initrd) (optional). + </para></listitem> + <listitem><para> + <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>: + Indicates a filesystem image to include as the root filesystem + (optional).</para></listitem> + <listitem><para> + <link linkend='var-GRUB_GFXSERIAL'><filename>GRUB_GFXSERIAL</filename></link>: + Set this to "1" to have graphics and serial in the boot menu. + </para></listitem> + <listitem><para> + <link linkend='var-LABELS'><filename>LABELS</filename></link>: + A list of targets for the automatic configuration. + </para></listitem> + <listitem><para> + <link linkend='var-APPEND'><filename>APPEND</filename></link>: + An override list of append strings for each + <filename>LABEL</filename>. + </para></listitem> + <listitem><para> + <link linkend='var-GRUB_OPTS'><filename>GRUB_OPTS</filename></link>: + Additional options to add to the configuration (optional). + Options are delimited using semi-colon characters + (<filename>;</filename>).</para></listitem> + <listitem><para> + <link linkend='var-GRUB_TIMEOUT'><filename>GRUB_TIMEOUT</filename></link>: + Timeout before executing the default <filename>LABEL</filename> + (optional). + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-gsettings'> + <title><filename>gsettings.bbclass</filename></title> + + <para> + The <filename>gsettings</filename> class + provides common functionality for recipes that need to install + GSettings (glib) schemas. + The schemas are assumed to be part of the main package. + Appropriate post-install and post-remove (postinst/postrm) + scriptlets are added to register and unregister the schemas in the + target image. + </para> +</section> + +<section id='ref-classes-gtk-doc'> + <title><filename>gtk-doc.bbclass</filename></title> + + <para> + The <filename>gtk-doc</filename> class + is a helper class to pull in the appropriate + <filename>gtk-doc</filename> dependencies and disable + <filename>gtk-doc</filename>. + </para> +</section> + +<section id='ref-classes-gtk-icon-cache'> + <title><filename>gtk-icon-cache.bbclass</filename></title> + + <para> + The <filename>gtk-icon-cache</filename> class + generates the proper post-install and post-remove (postinst/postrm) + scriptlets for packages that use GTK+ and install icons. + These scriptlets call <filename>gtk-update-icon-cache</filename> to add + the fonts to GTK+'s icon cache. + Since the cache files are architecture-specific, + <filename>gtk-update-icon-cache</filename> is run using QEMU if the + postinst scriptlets need to be run on the build host during image + creation. + </para> +</section> + +<section id='ref-classes-gtk-immodules-cache'> + <title><filename>gtk-immodules-cache.bbclass</filename></title> + + <para> + The <filename>gtk-immodules-cache</filename> class + generates the proper post-install and post-remove (postinst/postrm) + scriptlets for packages that install GTK+ input method modules for + virtual keyboards. + These scriptlets call <filename>gtk-update-icon-cache</filename> to add + the input method modules to the cache. + Since the cache files are architecture-specific, + <filename>gtk-update-icon-cache</filename> is run using QEMU if the + postinst scriptlets need to be run on the build host during image + creation. + </para> + + <para> + If the input method modules being installed are in packages other than + the main package, set + <link linkend='var-GTKIMMODULES_PACKAGES'><filename>GTKIMMODULES_PACKAGES</filename></link> + to specify the packages containing the modules. + </para> +</section> + +<section id='ref-classes-gummiboot'> + <title><filename>gummiboot.bbclass</filename></title> + + <para> + The <filename>gummiboot</filename> class provides functions specific + to the gummiboot bootloader for building bootable images. + This is an internal class and is not intended to be + used directly. + Set the + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + variable to "gummiboot" to use this class. + </para> + + <para> + For information on more variables used and supported in this class, + see the + <link linkend='var-GUMMIBOOT_CFG'><filename>GUMMIBOOT_CFG</filename></link>, + <link linkend='var-GUMMIBOOT_ENTRIES'><filename>GUMMIBOOT_ENTRIES</filename></link>, + and + <link linkend='var-GUMMIBOOT_TIMEOUT'><filename>GUMMIBOOT_TIMEOUT</filename></link> + variables. + </para> + + <para> + You can also see the + <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink> + for more information. + </para> +</section> + +<section id='ref-classes-gzipnative'> + <title><filename>gzipnative.bbclass</filename></title> + + <para> + The <filename>gzipnative</filename> class enables the use of + different native versions of <filename>gzip</filename> + and <filename>pigz</filename> rather than the versions of these tools + from the build host. + </para> +</section> + +<section id='ref-classes-icecc'> + <title><filename>icecc.bbclass</filename></title> + + <para> + The <filename>icecc</filename> class supports + <ulink url='https://github.com/icecc/icecream'>Icecream</ulink>, which + facilitates taking compile jobs and distributing them among remote + machines. + </para> + + <para> + The class stages directories with symlinks from <filename>gcc</filename> + and <filename>g++</filename> to <filename>icecc</filename>, for both + native and cross compilers. + Depending on each configure or compile, the OpenEmbedded build system + adds the directories at the head of the <filename>PATH</filename> list + and then sets the <filename>ICECC_CXX</filename> and + <filename>ICEC_CC</filename> variables, which are the paths to the + <filename>g++</filename> and <filename>gcc</filename> compilers, + respectively. + </para> + + <para> + For the cross compiler, the class creates a <filename>tar.gz</filename> + file that contains the Yocto Project toolchain and sets + <filename>ICECC_VERSION</filename>, which is the version of the + cross-compiler used in the cross-development toolchain, accordingly. + </para> + + <para> + The class handles all three different compile stages + (i.e native ,cross-kernel and target) and creates the necessary + environment <filename>tar.gz</filename> file to be used by the remote + machines. + The class also supports SDK generation. + </para> + + <para> + If <link linkend='var-ICECC_PATH'><filename>ICECC_PATH</filename></link> + is not set in your <filename>local.conf</filename> file, then the + class tries to locate the <filename>icecc</filename> binary + using <filename>which</filename>. + + If + <link linkend='var-ICECC_ENV_EXEC'><filename>ICECC_ENV_EXEC</filename></link> + is set in your <filename>local.conf</filename> file, the variable should + point to the <filename>icecc-create-env</filename> script + provided by the user. + If you do not point to a user-provided script, the build system + uses the default script provided by the recipe + <filename>icecc-create-env-native.bb</filename>. + <note> + This script is a modified version and not the one that comes with + <filename>icecc</filename>. + </note> + </para> + + <para> + If you do not want the Icecream distributed compile support to apply + to specific recipes or classes, you can effectively "blacklist" them + by listing the recipes and classes using the + <link linkend='var-ICECC_USER_PACKAGE_BL'><filename>ICECC_USER_PACKAGE_BL</filename></link> + and + <link linkend='var-ICECC_USER_CLASS_BL'><filename>ICECC_USER_CLASS_BL</filename></link>, + variables, respectively, in your <filename>local.conf</filename> file. + Doing so causes the OpenEmbedded build system to handle these + compilations locally. + </para> + + <para> + Additionally, you can list recipes using the + <link linkend='var-ICECC_USER_PACKAGE_WL'><filename>ICECC_USER_PACKAGE_WL</filename></link> + variable in your <filename>local.conf</filename> file to force + <filename>icecc</filename> to be enabled for recipes using an empty + <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> + variable. + </para> + + <para> + Inheriting the <filename>icecc</filename> class changes all sstate + signatures. + Consequently, if a development team has a dedicated build system + that populates + <link linkend='var-SSTATE_MIRRORS'><filename>STATE_MIRRORS</filename></link> + and they want to reuse sstate from + <filename>STATE_MIRRORS</filename>, then all developers and the + build system need to either inherit the <filename>icecc</filename> + class or nobody should. + </para> + + <para> + At the distribution level, you can inherit the + <filename>icecc</filename> class to be sure that all builders start + with the same sstate signatures. + After inheriting the class, you can then disable the feature by setting + the + <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link> + variable to "1" as follows: + <literallayout class='monospaced'> + INHERIT_DISTRO_append = " icecc" + ICECC_DISABLED ??= "1" + </literallayout> + This practice makes sure everyone is using the same signatures but also + requires individuals that do want to use Icecream to enable the feature + individually as follows in your <filename>local.conf</filename> file: + <literallayout class='monospaced'> + ICECC_DISABLED = "" + </literallayout> + </para> +</section> + +<section id='ref-classes-image'> + <title><filename>image.bbclass</filename></title> + + <para> + The <filename>image</filename> class helps support creating images + in different formats. + First, the root filesystem is created from packages using + one of the <filename>rootfs*.bbclass</filename> + files (depending on the package format used) and then one or more image + files are created. + <itemizedlist> + <listitem><para>The + <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename> + variable controls the types of images to generate. + </para></listitem> + <listitem><para>The + <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename> + variable controls the list of packages to install into the + image.</para></listitem> + </itemizedlist> + For information on customizing images, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>" + section in the Yocto Project Development Manual. + For information on how images are created, see the + "<link linkend='images-dev-environment'>Images</link>" section elsewhere + in this manual. + </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> + + <para> + The <filename>image_types</filename> class defines all of + the standard image output types that you can enable through the + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> + variable. + You can use this class as a reference on how to add support for custom + image output types. + </para> + + <para> + By default, this class is enabled through the + <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link> + variable in + <link linkend='ref-classes-image'><filename>image.bbclass</filename></link>. + If you define your own image types using a custom BitBake class and + then use <filename>IMAGE_CLASSES</filename> to enable it, the custom + class must either inherit <filename>image_types</filename> or + <filename>image_types</filename> must also appear in + <filename>IMAGE_CLASSES</filename>. + </para> +</section> + +<section id='ref-classes-image_types_uboot'> + <title><filename>image_types_uboot.bbclass</filename></title> + + <para> + The <filename>image_types_uboot</filename> class + defines additional image types specifically for the U-Boot bootloader. + </para> +</section> + +<section id='ref-classes-image-live'> + <title><filename>image-live.bbclass</filename></title> + + <para> + The <filename>image-live</filename> class supports building "live" + images. + </para> + + <para> + Normally, you do not use this class directly. + Instead, you add "live" to + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. + For example, if you were building an ISO image, you would add "live" + to <filename>IMAGE_FSTYPES</filename>, set the + <link linkend='var-NOISO'><filename>NOISO</filename></link> variable to + "0" and the build system would use the <filename>image-live</filename> + class to build the ISO image. + </para> +</section> + +<section id='ref-classes-image-mklibs'> + <title><filename>image-mklibs.bbclass</filename></title> + + <para> + The <filename>image-mklibs</filename> class + enables the use of the <filename>mklibs</filename> utility during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task, which optimizes the size of + libraries contained in the image. + </para> + + <para> + By default, the class is enabled in the + <filename>local.conf.template</filename> using the + <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link> + variable as follows: + <literallayout class='monospaced'> + USER_CLASSES ?= "buildstats image-mklibs image-prelink" + </literallayout> + </para> +</section> + +<section id='ref-classes-image-prelink'> + <title><filename>image-prelink.bbclass</filename></title> + + <para> + The <filename>image-prelink</filename> class + enables the use of the <filename>prelink</filename> utility during + the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task, which optimizes the dynamic + linking of shared libraries to reduce executable startup time. + </para> + + <para> + By default, the class is enabled in the + <filename>local.conf.template</filename> using the + <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link> + variable as follows: + <literallayout class='monospaced'> + USER_CLASSES ?= "buildstats image-mklibs image-prelink" + </literallayout> + </para> +</section> + +<section id='ref-classes-image-swab'> + <title><filename>image-swab.bbclass</filename></title> + + <para> + The <filename>image-swab</filename> class enables the + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/swabber'>Swabber</ulink> + tool in order to detect and log accesses to the host system during + 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> + + <para> + The <filename>image-vmdk</filename> class supports building VMware + VMDK images. + Normally, you do not use this class directly. + Instead, you add "vmdk" to + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. + </para> +</section> + +<section id='ref-classes-insane'> + <title><filename>insane.bbclass</filename></title> + + <para> + The <filename>insane</filename> class adds a step to the package + generation process so that output quality assurance checks are + generated by the OpenEmbedded build system. + A range of checks are performed that check the build's output + for common problems that show up during runtime. + Distribution policy usually dictates whether to include this class. + </para> + + <para> + You can configure the sanity checks so that specific test failures + either raise a warning or an error message. + Typically, failures for new tests generate a warning. + Subsequent failures for the same test would then generate an error + message once the metadata is in a known and good condition. + See the + "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>" + Chapter for a list of all the warning and error messages + you might encounter using a default configuration. + </para> + + <para> + Use the + <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and + <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link> + variables to control the behavior of + these checks at the global level (i.e. in your custom distro + configuration). + However, to skip one or more checks in recipes, you should use + <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>. + For example, to skip the check for symbolic link + <filename>.so</filename> files in the main package of a recipe, + add the following to the recipe. + You need to realize that the package name override, in this example + <filename>${PN}</filename>, must be used: + <literallayout class='monospaced'> + INSANE_SKIP_${PN} += "dev-so" + </literallayout> + Please keep in mind that the QA checks exist in order to detect real + or potential problems in the packaged output. + So exercise caution when disabling these checks. + </para> + + <para> + The following list shows the tests you can list with the + <filename>WARN_QA</filename> and <filename>ERROR_QA</filename> + variables: + <itemizedlist> + <listitem><para><emphasis><filename>already-stripped:</filename></emphasis> + Checks that produced binaries have not already been + stripped prior to the build system extracting debug symbols. + It is common for upstream software projects to default to + stripping debug symbols for output binaries. + In order for debugging to work on the target using + <filename>-dbg</filename> packages, this stripping must be + disabled. + </para></listitem> + <listitem><para><emphasis><filename>arch:</filename></emphasis> + Checks the Executable and Linkable Format (ELF) type, bit size, + and endianness of any binaries to ensure they match the target + architecture. + This test fails if any binaries do not match the type since + there would be an incompatibility. + The test could indicate that the + wrong compiler or compiler options have been used. + Sometimes software, like bootloaders, might need to bypass + this check. + </para></listitem> + <listitem><para><emphasis><filename>buildpaths:</filename></emphasis> + Checks for paths to locations on the build host inside the + output files. + Currently, this test triggers too many false positives and + thus is not normally enabled. + </para></listitem> + <listitem><para><emphasis><filename>build-deps:</filename></emphasis> + Determines if a build-time dependency that is specified through + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>, + explicit + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, + or task-level dependencies exists to match any runtime + dependency. + This determination is particularly useful to discover where + runtime dependencies are detected and added during packaging. + If no explicit dependency has been specified within the + metadata, at the packaging stage it is too late to ensure that + the dependency is built, and thus you can end up with an + error when the package is installed into the image during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task because the auto-detected dependency was not satisfied. + An example of this would be where the + <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link> + class automatically adds a dependency on the + <filename>initscripts-functions</filename> package to packages + that install an initscript that refers to + <filename>/etc/init.d/functions</filename>. + The recipe should really have an explicit + <filename>RDEPENDS</filename> for the package in question on + <filename>initscripts-functions</filename> so that the + OpenEmbedded build system is able to ensure that the + <filename>initscripts</filename> recipe is actually built and + thus the <filename>initscripts-functions</filename> package is + made available. + </para></listitem> + <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis> + Checks the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + log for indications + that paths to locations on the build host were used. + Using such paths might result in host contamination of the + build output. + </para></listitem> + <listitem><para><emphasis><filename>debug-deps:</filename></emphasis> + Checks that all packages except <filename>-dbg</filename> + packages do not depend on <filename>-dbg</filename> + packages, which would cause a packaging bug. + </para></listitem> + <listitem><para><emphasis><filename>debug-files:</filename></emphasis> + Checks for <filename>.debug</filename> directories in anything but the + <filename>-dbg</filename> package. + The debug files should all be in the <filename>-dbg</filename> package. + Thus, anything packaged elsewhere is incorrect packaging.</para></listitem> + <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis> + Checks for invalid version comparison statements in runtime + dependency relationships between packages (i.e. in + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>, + <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>, + <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>, + <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>, + and + <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link> + variable values). + Any invalid comparisons might trigger failures or undesirable + behavior when passed to the package manager. + </para></listitem> + <listitem><para><emphasis><filename>desktop:</filename></emphasis> + Runs the <filename>desktop-file-validate</filename> program + against any <filename>.desktop</filename> files to validate + their contents against the specification for + <filename>.desktop</filename> files.</para></listitem> + <listitem><para><emphasis><filename>dev-deps:</filename></emphasis> + Checks that all packages except <filename>-dev</filename> + or <filename>-staticdev</filename> packages do not depend on + <filename>-dev</filename> packages, which would be a + packaging bug.</para></listitem> + <listitem><para><emphasis><filename>dev-so:</filename></emphasis> + Checks that the <filename>.so</filename> symbolic links are in the + <filename>-dev</filename> package and not in any of the other packages. + In general, these symlinks are only useful for development purposes. + Thus, the <filename>-dev</filename> package is the correct location for + them. + Some very rare cases do exist for dynamically loaded modules where + these symlinks are needed instead in the main package. + </para></listitem> + <listitem><para><emphasis><filename>file-rdeps:</filename></emphasis> + Checks that file-level dependencies identified by the + OpenEmbedded build system at packaging time are satisfied. + For example, a shell script might start with the line + <filename>#!/bin/bash</filename>. + This line would translate to a file dependency on + <filename>/bin/bash</filename>. + Of the three package managers that the OpenEmbedded build + system supports, only RPM directly handles file-level + dependencies, resolving them automatically to packages + providing the files. + However, the lack of that functionality in the other two + package managers does not mean the dependencies do not still + need resolving. + This QA check attempts to ensure that explicitly declared + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + exist to handle any file-level dependency detected in + packaged files. + </para></listitem> + <listitem><para><emphasis><filename>files-invalid:</filename></emphasis> + Checks for + <link linkend='var-FILES'><filename>FILES</filename></link> + variable values that contain "//", which is invalid. + </para></listitem> + <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis> + Report when packages are excluded from being created due to + being marked with a license that is in + <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>. + </para></listitem> + <listitem><para><emphasis><filename>install-host-path:</filename></emphasis> + Checks the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + log for indications + that paths to locations on the build host were used. + Using such paths might result in host contamination of the + build output. + </para></listitem> + <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis> + Reports when files have been installed within + <filename>do_install</filename> but have not been included in + any package by way of the + <link linkend='var-FILES'><filename>FILES</filename></link> + variable. + Files that do not appear in any package cannot be present in + an image later on in the build process. + Ideally, all installed files should be packaged or not + installed at all. + These files can be deleted at the end of + <filename>do_install</filename> if the files are not + needed in any package. + </para></listitem> + <listitem><para><emphasis><filename>la:</filename></emphasis> + Checks <filename>.la</filename> files for any <filename>TMPDIR</filename> + paths. + Any <filename>.la</filename> file containing these paths is incorrect since + <filename>libtool</filename> adds the correct sysroot prefix when using the + files automatically itself.</para></listitem> + <listitem><para><emphasis><filename>ldflags:</filename></emphasis> + Ensures that the binaries were linked with the + <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link> + options provided by the build system. + If this test fails, check that the <filename>LDFLAGS</filename> variable + is being passed to the linker command.</para></listitem> + <listitem><para><emphasis><filename>libdir:</filename></emphasis> + Checks for libraries being installed into incorrect + (possibly hardcoded) installation paths. + For example, this test will catch recipes that install + <filename>/lib/bar.so</filename> when + <filename>${base_libdir}</filename> is "lib32". + Another example is when recipes install + <filename>/usr/lib64/foo.so</filename> when + <filename>${libdir}</filename> is "/usr/lib". + </para></listitem> + <listitem><para><emphasis><filename>libexec:</filename></emphasis> + Checks if a package contains files in + <filename>/usr/libexec</filename>. + This check is not performed if the + <filename>libexecdir</filename> variable has been set + explicitly to <filename>/usr/libexec</filename>. + </para></listitem> + <listitem><para><emphasis><filename>packages-list:</filename></emphasis> + Checks for the same package being listed multiple times through + the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + variable value. + Installing the package in this manner can cause errors during + packaging. + </para></listitem> + <listitem><para><emphasis><filename>perm-config:</filename></emphasis> + Reports lines in <filename>fs-perms.txt</filename> that have + an invalid format. + </para></listitem> + <listitem><para><emphasis><filename>perm-line:</filename></emphasis> + Reports lines in <filename>fs-perms.txt</filename> that have + an invalid format. + </para></listitem> + <listitem><para><emphasis><filename>perm-link:</filename></emphasis> + Reports lines in <filename>fs-perms.txt</filename> that + specify 'link' where the specified target already exists. + </para></listitem> + <listitem><para><emphasis><filename>perms:</filename></emphasis> + Currently, this check is unused but reserved. + </para></listitem> + <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis> + Checks <filename>.pc</filename> files for any + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + paths. + Any <filename>.pc</filename> file containing these paths is incorrect + since <filename>pkg-config</filename> itself adds the correct sysroot prefix + when the files are accessed.</para></listitem> + <listitem><para><emphasis><filename>pkgname:</filename></emphasis> + Checks that all packages in + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + have names that do not contain invalid characters (i.e. + characters other than 0-9, a-z, ., +, and -). + </para></listitem> + <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis> + Checks to see if the <filename>PKGV</filename> variable + is undefined during + <link linkend='ref-tasks-package'><filename>do_package</filename></link>. + </para></listitem> + <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis> + Checks through the variables + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>, + <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>, + <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>, + <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>, + <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>, + <link linkend='var-FILES'><filename>FILES</filename></link>, + <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>, + <filename>pkg_preinst</filename>, + <filename>pkg_postinst</filename>, + <filename>pkg_prerm</filename> + and <filename>pkg_postrm</filename>, and reports if there are + variable sets that are not package-specific. + Using these variables without a package suffix is bad practice, + and might unnecessarily complicate dependencies of other packages + within the same recipe or have other unintended consequences. + </para></listitem> + <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis> + Checks that a recipe does not have a name + (<link linkend='var-PN'><filename>PN</filename></link>) value + that appears in + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>. + If a recipe is named such that its <filename>PN</filename> + value matches something already in + <filename>OVERRIDES</filename> (e.g. <filename>PN</filename> + happens to be the same as + <link linkend='var-MACHINE'><filename>MACHINE</filename></link> + or + <link linkend='var-DISTRO'><filename>DISTRO</filename></link>), + it can have unexpected consequences. + For example, assignments such as + <filename>FILES_${PN} = "xyz"</filename> effectively turn into + <filename>FILES = "xyz"</filename>. + </para></listitem> + <listitem><para><emphasis><filename>rpaths:</filename></emphasis> + Checks for rpaths in the binaries that contain build system paths such + as <filename>TMPDIR</filename>. + If this test fails, bad <filename>-rpath</filename> options are being + passed to the linker commands and your binaries have potential security + issues.</para></listitem> + <listitem><para><emphasis><filename>split-strip:</filename></emphasis> + Reports that splitting or stripping debug symbols from binaries + has failed. + </para></listitem> + <listitem><para><emphasis><filename>staticdev:</filename></emphasis> + Checks for static library files (<filename>*.a</filename>) in + non-<filename>staticdev</filename> packages. + </para></listitem> + <listitem><para><emphasis><filename>symlink-to-sysroot:</filename></emphasis> + Checks for symlinks in packages that point into + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + on the host. + Such symlinks will work on the host, but are clearly invalid + when running on the target. + </para></listitem> + <listitem><para><emphasis><filename>textrel:</filename></emphasis> + Checks for ELF binaries that contain relocations in their + <filename>.text</filename> sections, which can result in a + performance impact at runtime. + See the explanation for the + <link linkend='qa-issue-textrel'><filename>ELF binary</filename></link> + message for more information regarding runtime performance issues. + </para></listitem> + <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis> + Reports when a binary installed in + <filename>${base_libdir}</filename>, + <filename>${base_bindir}</filename>, or + <filename>${base_sbindir}</filename>, depends on another + binary installed under <filename>${exec_prefix}</filename>. + This dependency is a concern if you want the system to remain + basically operable if <filename>/usr</filename> is mounted + separately and is not mounted. + <note> + Defaults for binaries installed in + <filename>${base_libdir}</filename>, + <filename>${base_bindir}</filename>, and + <filename>${base_sbindir}</filename> are + <filename>/lib</filename>, <filename>/bin</filename>, and + <filename>/sbin</filename>, respectively. + The default for a binary installed + under <filename>${exec_prefix}</filename> is + <filename>/usr</filename>. + </note> + </para></listitem> + <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis> + Reports when a script file installed in + <filename>${base_libdir}</filename>, + <filename>${base_bindir}</filename>, or + <filename>${base_sbindir}</filename>, depends on files + installed under <filename>${exec_prefix}</filename>. + This dependency is a concern if you want the system to remain + basically operable if <filename>/usr</filename> is mounted + separately and is not mounted. + <note> + Defaults for binaries installed in + <filename>${base_libdir}</filename>, + <filename>${base_bindir}</filename>, and + <filename>${base_sbindir}</filename> are + <filename>/lib</filename>, <filename>/bin</filename>, and + <filename>/sbin</filename>, respectively. + The default for a binary installed + under <filename>${exec_prefix}</filename> is + <filename>/usr</filename>. + </note> + </para></listitem> + <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis> + Checks for dynamic library load paths (rpaths) in the binaries that + by default on a standard system are searched by the linker (e.g. + <filename>/lib</filename> and <filename>/usr/lib</filename>). + While these paths will not cause any breakage, they do waste space and + are unnecessary.</para></listitem> + <listitem><para><emphasis><filename>var-undefined:</filename></emphasis> + Reports when variables fundamental to packaging (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>, + <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>, + <link linkend='var-D'><filename>D</filename></link>, + <link linkend='var-PN'><filename>PN</filename></link>, and + <link linkend='var-PKGD'><filename>PKGD</filename></link>) are + undefined during + <link linkend='ref-tasks-package'><filename>do_package</filename></link>. + </para></listitem> + <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis> + If Build History is enabled, reports when a package + being written out has a lower version than the previously + written package under the same name. + If you are placing output packages into a feed and + upgrading packages on a target system using that feed, the + version of a package going backwards can result in the target + system not correctly upgrading to the "new" version of the + package. + <note> + If you are not using runtime package management on your + target system, then you do not need to worry about + this situation. + </note> + </para></listitem> + <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis> + Checks that all packages containing Xorg drivers have ABI + dependencies. + The <filename>xserver-xorg</filename> recipe provides driver + ABI names. + All drivers should depend on the ABI versions that they have + been built against. + Driver recipes that include + <filename>xorg-driver-input.inc</filename> + or <filename>xorg-driver-video.inc</filename> will + automatically get these versions. + Consequently, you should only need to explicitly add + dependencies to binary driver recipes. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-insserv'> + <title><filename>insserv.bbclass</filename></title> + + <para> + The <filename>insserv</filename> class + uses the <filename>insserv</filename> utility to update the order of + symbolic links in <filename>/etc/rc?.d/</filename> within an image + based on dependencies specified by LSB headers in the + <filename>init.d</filename> scripts themselves. + </para> +</section> + +<section id='ref-classes-kernel'> + <title><filename>kernel.bbclass</filename></title> + + <para> + The <filename>kernel</filename> class handles building Linux kernels. + The class contains code to build all kernel trees. + All needed headers are staged into the + <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename> + directory to allow out-of-tree module builds using + the + <link linkend='ref-classes-module'><filename>module</filename></link> + class. + </para> + + <para> + This means that each built kernel module is packaged separately and inter-module + dependencies are created by parsing the <filename>modinfo</filename> output. + If all modules are required, then installing the <filename>kernel-modules</filename> + package installs all packages with modules and various other kernel packages + such as <filename>kernel-vmlinux</filename>. + </para> + + <para> + Various other classes are used by the <filename>kernel</filename> + and <filename>module</filename> classes internally including the + <link linkend='ref-classes-kernel-arch'><filename>kernel-arch</filename></link>, + <link linkend='ref-classes-module-base'><filename>module-base</filename></link>, + and + <link linkend='ref-classes-linux-kernel-base'><filename>linux-kernel-base</filename></link> + classes. + </para> +</section> + +<section id='ref-classes-kernel-arch'> + <title><filename>kernel-arch.bbclass</filename></title> + + <para> + The <filename>kernel-arch</filename> class + sets the <filename>ARCH</filename> environment variable for Linux + kernel compilation (including modules). + </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> + + <para> + The <filename>kernel-module-split</filename> class + provides common functionality for splitting Linux kernel modules into + separate packages. + </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> + + <para> + The <filename>kernel-yocto</filename> class + provides common functionality for building from linux-yocto style + kernel source repositories. + </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> + + <para> + The <filename>lib_package</filename> class + supports recipes that build libraries and produce executable + binaries, where those binaries should not be installed by default + along with the library. + Instead, the binaries are added to a separate + <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-bin</filename> + package to make their installation optional. + </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> + + <para> + The <filename>license</filename> class provides license + manifest creation and license exclusion. + This class is enabled by default using the default value for the + <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link> + variable. + </para> +</section> + +<section id='ref-classes-linux-kernel-base'> + <title><filename>linux-kernel-base.bbclass</filename></title> + + <para> + The <filename>linux-kernel-base</filename> class + provides common functionality for recipes that build out of the Linux + kernel source tree. + These builds goes beyond the kernel itself. + For example, the Perf recipe also inherits this class. + </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> + + <para> + The <filename>logging</filename> class provides the standard + shell functions used to log messages for various BitBake severity levels + (i.e. <filename>bbplain</filename>, <filename>bbnote</filename>, + <filename>bbwarn</filename>, <filename>bberror</filename>, + <filename>bbfatal</filename>, and <filename>bbdebug</filename>). + </para> + + <para> + This class is enabled by default since it is inherited by + the <filename>base</filename> class. + </para> +</section> + +<section id='ref-classes-meta'> + <title><filename>meta.bbclass</filename></title> + + <para> + The <filename>meta</filename> class is inherited by recipes + that do not build any output packages themselves, but act as a "meta" + target for building other recipes. + </para> +</section> + +<section id='ref-classes-metadata_scm'> + <title><filename>metadata_scm.bbclass</filename></title> + + <para> + The <filename>metadata_scm</filename> class provides functionality for + querying the branch and revision of a Source Code Manager (SCM) + repository. + </para> + + <para> + The <link linkend='ref-classes-base'><filename>base</filename></link> + class uses this class to print the revisions of each layer before + starting every build. + The <filename>metadata_scm</filename> class is enabled by default + because it is inherited by the <filename>base</filename> class. + </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> + + <para> + The <filename>mime</filename> class generates the proper + post-install and post-remove (postinst/postrm) scriptlets for packages + that install MIME type files. + These scriptlets call <filename>update-mime-database</filename> to add + the MIME types to the shared database. + </para> +</section> + +<section id='ref-classes-mirrors'> + <title><filename>mirrors.bbclass</filename></title> + + <para> + The <filename>mirrors</filename> class sets up some standard + <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> entries + for source code mirrors. + These mirrors provide a fall-back path in case the upstream source + specified in + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + within recipes is unavailable. + </para> + + <para> + This class is enabled by default since it is inherited by the + <link linkend='ref-classes-base'><filename>base</filename></link> class. + </para> +</section> + +<section id='ref-classes-module'> + <title><filename>module.bbclass</filename></title> + + <para> + The <filename>module</filename> class provides support for building + out-of-tree Linux kernel modules. + The class inherits the + <link linkend='ref-classes-module-base'><filename>module-base</filename></link> + and + <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link> + classes, and implements the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + and + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + tasks. + The class provides everything needed to build and package a kernel + module. + </para> + + <para> + For general information on out-of-tree Linux kernel modules, see the + "<ulink url='&YOCTO_DOCS_KERNEL_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>" + section in the Yocto Project Linux Kernel Development Manual. + </para> +</section> + +<section id='ref-classes-module-base'> + <title><filename>module-base.bbclass</filename></title> + + <para> + The <filename>module-base</filename> class provides the base + functionality for building Linux kernel modules. + Typically, a recipe that builds software that includes one or + more kernel modules and has its own means of building + the module inherits this class as opposed to inheriting the + <link linkend='ref-classes-module'><filename>module</filename></link> + class. + </para> +</section> + +<section id='ref-classes-multilib*'> + <title><filename>multilib*.bbclass</filename></title> + + <para> + The <filename>multilib*</filename> classes provide support + for building libraries with different target optimizations or target + architectures and installing them side-by-side in the same image. + </para> + + <para> + For more information on using the Multilib feature, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>" + section in the Yocto Project Development Manual. + </para> +</section> + +<section id='ref-classes-native'> + <title><filename>native.bbclass</filename></title> + + <para> + The <filename>native</filename> class provides common + functionality for recipes that wish to build tools to run on the build + host (i.e. tools that use the compiler or other tools from the + build host). + </para> + + <para> + You can create a recipe that builds tools that run natively on the + host a couple different ways: + <itemizedlist> + <listitem><para>Create a <replaceable>myrecipe</replaceable><filename>-native.bb</filename> + that inherits the <filename>native</filename> class. + If you use this method, you must order the inherit statement + in the recipe after all other inherit statements so that the + <filename>native</filename> class is inherited last. + </para></listitem> + <listitem><para>Create or modify a target recipe that contains + the following: + <literallayout class='monospaced'> + <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native" + </literallayout> + Inside the recipe, use <filename>_class-native</filename> and + <filename>_class-target</filename> overrides to specify any + functionality specific to the respective native or target + case.</para></listitem> + </itemizedlist> + </para> + + <para> + Although applied differently, the <filename>native</filename> class is + used with both methods. + The advantage of the second method is that you do not need to have two + separate recipes (assuming you need both) for native and target. + All common parts of the recipe are automatically shared. + </para> +</section> + +<section id='ref-classes-nativesdk'> + <title><filename>nativesdk.bbclass</filename></title> + + <para> + The <filename>nativesdk</filename> class provides common + functionality for recipes that wish to build tools to run as part of + an SDK (i.e. tools that run on + <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>). + </para> + + <para> + You can create a recipe that builds tools that run on the SDK machine + a couple different ways: + <itemizedlist> + <listitem><para>Create a + <filename>nativesdk-</filename><replaceable>myrecipe</replaceable><filename>.bb</filename> + recipe that inherits the <filename>nativesdk</filename> class. + If you use this method, you must order the inherit statement + in the recipe after all other inherit statements so that the + <filename>nativesdk</filename> class is inherited last. + </para></listitem> + <listitem><para>Create a <filename>nativesdk</filename> variant + of any recipe by adding the following: + <literallayout class='monospaced'> + <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "nativesdk" + </literallayout> + Inside the recipe, use <filename>_class-nativesdk</filename> and + <filename>_class-target</filename> overrides to specify any + functionality specific to the respective SDK machine or target + case.</para></listitem> + </itemizedlist> + </para> + + <para> + Although applied differently, the <filename>nativesdk</filename> class + is used with both methods. + The advantage of the second method is that you do not need to have two + separate recipes (assuming you need both) for the SDK machine and the + target. + All common parts of the recipe are automatically shared. + </para> +</section> + +<section id='ref-classes-nopackages'> + <title><filename>nopackages.bbclass</filename></title> + + <para> + Disables packaging tasks for those recipes and classes where + packaging is not needed. + </para> +</section> + +<section id='ref-classes-npm'> + <title><filename>npm.bbclass</filename></title> + + <para> + Provides support for building Node.js software fetched using the npm + package manager. + <note> + Currently, recipes inheriting this class must use the + <filename>npm://</filename> fetcher to have dependencies fetched + and packaged automatically. + </note> + </para> +</section> + +<section id='ref-classes-oelint'> + <title><filename>oelint.bbclass</filename></title> + + <para> + The <filename>oelint</filename> class is an + obsolete lint checking tool that exists in + <filename>meta/classes</filename> in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </para> + + <para> + A number of classes exist that could be generally useful in + OE-Core but are never actually used within OE-Core itself. + The <filename>oelint</filename> class is one such example. + However, being aware of this class can reduce the proliferation of + different versions of similar classes across multiple layers. + </para> +</section> + +<section id='ref-classes-own-mirrors'> + <title><filename>own-mirrors.bbclass</filename></title> + + <para> + The <filename>own-mirrors</filename> class makes it + easier to set up your own + <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link> + from which to first fetch source before attempting to fetch it from the + upstream specified in + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + within each recipe. + </para> + + <para> + To use this class, inherit it globally and specify + <link linkend='var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></link>. + Here is an example: + <literallayout class='monospaced'> + INHERIT += "own-mirrors" + SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" + </literallayout> + You can specify only a single URL in + <filename>SOURCE_MIRROR_URL</filename>. + </para> +</section> + +<section id='ref-classes-package'> + <title><filename>package.bbclass</filename></title> + + <para> + The <filename>package</filename> class supports generating + packages from a build's output. + The core generic functionality is in + <filename>package.bbclass</filename>. + The code specific to particular package types resides in these + package-specific classes: + <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>, + <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>, + <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>, + and + <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>. + <note><title>Warning</title> + The <filename>package_tar</filename> class is broken and not + supported. + It is recommended that you do not use this class. + </note> + </para> + + <para> + You can control the list of resulting package formats by using the + <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename> + variable defined in your <filename>conf/local.conf</filename> + configuration file, which is located in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + When defining the variable, you can specify one or more package types. + Since images are generated from packages, a packaging class is + needed to enable image generation. + The first class listed in this variable is used for image generation. + </para> + + <para> + If you take the optional step to set up a repository (package feed) + on the development host that can be used by Smart, you can + install packages from the feed while you are running the image + on the target (i.e. runtime installation of packages). + For more information, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>" + section in the Yocto Project Development Manual. + </para> + + <para> + The package-specific class you choose can affect build-time performance + and has space ramifications. + In general, building a package with IPK takes about thirty percent less + time as compared to using RPM to build the same or similar package. + This comparison takes into account a complete build of the package with + all dependencies previously built. + The reason for this discrepancy is because the RPM package manager + creates and processes more + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the + IPK package manager. + Consequently, you might consider setting + <filename>PACKAGE_CLASSES</filename> to "package_ipk" if you are + building smaller systems. + </para> + + <para> + Before making your package manager decision, however, you should + consider some further things about using RPM: + <itemizedlist> + <listitem><para> + RPM starts to provide more abilities than IPK due to + the fact that it processes more Metadata. + For example, this information includes individual file types, + file checksum generation and evaluation on install, sparse file + support, conflict detection and resolution for Multilib systems, + ACID style upgrade, and repackaging abilities for rollbacks. + </para></listitem> + <listitem><para> + For smaller systems, the extra space used for the Berkeley + Database and the amount of metadata when using RPM can affect + your ability to perform on-device upgrades. + </para></listitem> + </itemizedlist> + </para> + + <para> + You can find additional information on the effects of the package + class at these two Yocto Project mailing list links: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'> + https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-package_deb'> + <title><filename>package_deb.bbclass</filename></title> + + <para> + The <filename>package_deb</filename> class + provides support for creating packages that use the Debian + (i.e. <filename>.deb</filename>) file format. + The class ensures the packages are written out in a + <filename>.deb</filename> file format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename> + directory. + </para> + + <para> + This class inherits the + <link linkend='ref-classes-package'><filename>package</filename></link> + class and is enabled through the + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + variable in the <filename>local.conf</filename> file. + </para> +</section> + +<section id='ref-classes-package_ipk'> + <title><filename>package_ipk.bbclass</filename></title> + + <para> + The <filename>package_ipk</filename> class + provides support for creating packages that use the IPK + (i.e. <filename>.ipk</filename>) file format. + The class ensures the packages are written out in a + <filename>.ipk</filename> file format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename> + directory. + </para> + + <para> + This class inherits the + <link linkend='ref-classes-package'><filename>package</filename></link> + class and is enabled through the + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + variable in the <filename>local.conf</filename> file. + </para> +</section> + +<section id='ref-classes-package_rpm'> + <title><filename>package_rpm.bbclass</filename></title> + + <para> + The <filename>package_rpm</filename> class + provides support for creating packages that use the RPM + (i.e. <filename>.rpm</filename>) file format. + The class ensures the packages are written out in a + <filename>.rpm</filename> file format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename> + directory. + </para> + + <para> + This class inherits the + <link linkend='ref-classes-package'><filename>package</filename></link> + class and is enabled through the + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + variable in the <filename>local.conf</filename> file. + </para> +</section> + +<section id='ref-classes-package_tar'> + <title><filename>package_tar.bbclass</filename></title> + + <para> + The <filename>package_tar</filename> class + provides support for creating tarballs. + The class ensures the packages are written out in a + tarball format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename> + directory. + </para> + + <para> + This class inherits the + <link linkend='ref-classes-package'><filename>package</filename></link> + class and is enabled through the + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + variable in the <filename>local.conf</filename> file. + <note> + You cannot specify the <filename>package_tar</filename> class + first using the <filename>PACKAGE_CLASSES</filename> variable. + You must use <filename>.deb</filename>, + <filename>.ipk</filename>, or <filename>.rpm</filename> file + formats for your image or SDK. + </note> + </para> +</section> + +<section id='ref-classes-packagedata'> + <title><filename>packagedata.bbclass</filename></title> + + <para> + The <filename>packagedata</filename> class provides + common functionality for reading <filename>pkgdata</filename> files + found in + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>. + These files contain information about each output package produced by + the OpenEmbedded build system. + </para> + + <para> + This class is enabled by default because it is inherited by the + <link linkend='ref-classes-package'><filename>package</filename></link> + class. + </para> +</section> + +<section id='ref-classes-packagegroup'> + <title><filename>packagegroup.bbclass</filename></title> + + <para> + The <filename>packagegroup</filename> class sets default values + appropriate for package group recipes (e.g. + <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>, + <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>, + <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>, + and so forth). + It is highly recommended that all package group recipes inherit this class. + </para> + + <para> + For information on how to use this class, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>" + section in the Yocto Project Development Manual. + </para> + + <para> + Previously, this class was called the <filename>task</filename> class. + </para> +</section> + +<section id='ref-classes-patch'> + <title><filename>patch.bbclass</filename></title> + + <para> + The <filename>patch</filename> class provides all functionality for + applying patches during the + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + task. + </para> + + <para> + This class is enabled by default because it is inherited by the + <link linkend='ref-classes-base'><filename>base</filename></link> + class. + </para> +</section> + +<section id='ref-classes-perlnative'> + <title><filename>perlnative.bbclass</filename></title> + + <para> + When inherited by a recipe, the <filename>perlnative</filename> class + supports using the native version of Perl built by the build system + rather than using the version provided by the build host. + </para> +</section> + +<section id='ref-classes-pixbufcache'> + <title><filename>pixbufcache.bbclass</filename></title> + + <para> + The <filename>pixbufcache</filename> class generates the proper + post-install and post-remove (postinst/postrm) scriptlets for packages + that install pixbuf loaders, which are used with + <filename>gdk-pixbuf</filename>. + These scriptlets call <filename>update_pixbuf_cache</filename> + to add the pixbuf loaders to the cache. + Since the cache files are architecture-specific, + <filename>update_pixbuf_cache</filename> is run using QEMU if the + postinst scriptlets need to be run on the build host during image + creation. + </para> + + <para> + If the pixbuf loaders being installed are in packages other + than the recipe's main package, set + <link linkend='var-PIXBUF_PACKAGES'><filename>PIXBUF_PACKAGES</filename></link> + to specify the packages containing the loaders. + </para> +</section> + +<section id='ref-classes-pkgconfig'> + <title><filename>pkgconfig.bbclass</filename></title> + + <para> + 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>, the <filename>pkgconfig</filename> + class no longer has to manipulate the files. + </para> +</section> + +<section id='ref-classes-populate-sdk'> + <title><filename>populate_sdk.bbclass</filename></title> + + <para> + The <filename>populate_sdk</filename> class provides support for + SDK-only recipes. + For information on advantages gained when building a cross-development + toolchain using the + <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> + task, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's Guide. + </para> +</section> + +<section id='ref-classes-populate-sdk-*'> + <title><filename>populate_sdk_*.bbclass</filename></title> + + <para> + The <filename>populate_sdk_*</filename> classes support SDK creation + and consist of the following classes: + <itemizedlist> + <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis> + The base class supporting SDK creation under all package + managers (i.e. DEB, RPM, and opkg).</para></listitem> + <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis> + Supports creation of the SDK given the Debian package manager. + </para></listitem> + <listitem><para><emphasis><filename>populate_sdk_rpm</filename>:</emphasis> + Supports creation of the SDK given the RPM package manager. + </para></listitem> + <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis> + 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> + + <para> + The <filename>populate_sdk_base</filename> class inherits the + appropriate <filename>populate_sdk_*</filename> (i.e. + <filename>deb</filename>, <filename>rpm</filename>, and + <filename>ipk</filename>) based on + <link linkend='var-IMAGE_PKGTYPE'><filename>IMAGE_PKGTYPE</filename></link>. + </para> + + <para> + The base class ensures all source and destination directories are + established and then populates the SDK. + After populating the SDK, the <filename>populate_sdk_base</filename> + class constructs two sysroots: + <filename>${</filename><link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>}-nativesdk</filename>, + which contains the cross-compiler and associated tooling, and the + target, which contains a target root filesystem that is configured for + the SDK usage. + These two images reside in + <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>, + which consists of the following: + <literallayout class='monospaced'> + ${SDK_OUTPUT}/${SDK_ARCH}<replaceable>-nativesdk-pkgs</replaceable> + ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/<replaceable>target-pkgs</replaceable> + </literallayout> + </para> + + <para> + Finally, the base populate SDK class creates the toolchain + environment setup script, the tarball of the SDK, and the installer. + </para> + + <para> + The respective <filename>populate_sdk_deb</filename>, + <filename>populate_sdk_rpm</filename>, and + <filename>populate_sdk_ipk</filename> classes each support the + specific type of SDK. + These classes are inherited by and used with the + <filename>populate_sdk_base</filename> class. + </para> + + <para> + For more information on the cross-development toolchain + generation, see the + "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" + section. + For information on advantages gained when building a + cross-development toolchain using the + <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> + task, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's + Guide. + </para> +</section> + +<section id='ref-classes-prexport'> + <title><filename>prexport.bbclass</filename></title> + + <para> + The <filename>prexport</filename> class provides functionality for + exporting + <link linkend='var-PR'><filename>PR</filename></link> values. + <note> + This class is not intended to be used directly. + Rather, it is enabled when using + "<filename>bitbake-prserv-tool export</filename>". + </note> + </para> +</section> + +<section id='ref-classes-primport'> + <title><filename>primport.bbclass</filename></title> + + <para> + The <filename>primport</filename> class provides functionality for + importing + <link linkend='var-PR'><filename>PR</filename></link> values. + <note> + This class is not intended to be used directly. + Rather, it is enabled when using + "<filename>bitbake-prserv-tool import</filename>". + </note> + </para> +</section> + +<section id='ref-classes-prserv'> + <title><filename>prserv.bbclass</filename></title> + + <para> + The <filename>prserv</filename> class provides functionality for + using a + <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink> + in order to automatically manage the incrementing of the + <link linkend='var-PR'><filename>PR</filename></link> variable for + each recipe. + </para> + + <para> + This class is enabled by default because it is inherited by the + <link linkend='ref-classes-package'><filename>package</filename></link> + class. + However, the OpenEmbedded build system will not enable the + functionality of this class unless + <link linkend='var-PRSERV_HOST'><filename>PRSERV_HOST</filename></link> + has been set. + </para> +</section> + +<section id='ref-classes-ptest'> + <title><filename>ptest.bbclass</filename></title> + + <para> + The <filename>ptest</filename> class provides functionality for + packaging and installing runtime tests for recipes that build software + that provides these tests. + </para> + + <para> + This class is intended to be inherited by individual recipes. + However, the class' functionality is largely disabled unless "ptest" + appears in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>" + section in the Yocto Project Development Manual for more information + on ptest. + </para> +</section> + +<section id='ref-classes-ptest-gnome'> + <title><filename>ptest-gnome.bbclass</filename></title> + + <para> + Enables package tests (ptests) specifically for GNOME packages, + which have tests intended to be executed with + <filename>gnome-desktop-testing</filename>. + </para> + + <para> + For information on setting up and running ptests, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>" + section in the Yocto Project Development Manual. + </para> +</section> + +<section id='ref-classes-python-dir'> + <title><filename>python-dir.bbclass</filename></title> + + <para> + The <filename>python-dir</filename> class provides the base version, + location, and site package location for Python. + </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> + + <para> + When inherited by a recipe, the <filename>pythonnative</filename> class + supports using the native version of Python built by the build system + rather than using the version provided by the build host. + </para> +</section> + +<section id='ref-classes-qemu'> + <title><filename>qemu.bbclass</filename></title> + + <para> + The <filename>qemu</filename> class provides functionality for recipes + that either need QEMU or test for the existence of QEMU. + Typically, this class is used to run programs for a target system on + the build host using QEMU's application emulation mode. + </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> + + <para> + The <filename>relocatable</filename> class enables relocation of + binaries when they are installed into the sysroot. + </para> + + <para> + This class makes use of the + <link linkend='ref-classes-chrpath'><filename>chrpath</filename></link> + class and is used by both the + <link linkend='ref-classes-cross'><filename>cross</filename></link> + and + <link linkend='ref-classes-native'><filename>native</filename></link> + classes. + </para> +</section> + +<section id='ref-classes-remove-libtool'> + <title><filename>remove-libtool.bbclass</filename></title> + + <para> + The <filename>remove-libtool</filename> class adds a post function + to the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task to remove all <filename>.la</filename> files installed by + <filename>libtool</filename>. + Removing these files results in them being absent from both the + sysroot and target packages. + </para> + + <para> + If a recipe needs the <filename>.la</filename> files to be installed, + then the recipe can override the removal by setting + <filename>REMOVE_LIBTOOL_LA</filename> to "0" as follows: + <literallayout class='monospaced'> + REMOVE_LIBTOOL_LA = "0" + </literallayout> + <note> + The <filename>remove-libtool</filename> class is not enabled by + default. + </note> + </para> +</section> + +<section id='ref-classes-report-error'> + <title><filename>report-error.bbclass</filename></title> + + <para> + The <filename>report-error</filename> class supports enabling the + <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>, + which allows you to submit build error information to a central + database. + </para> + + <para> + The class collects debug information for recipe, recipe version, task, + machine, distro, build system, target system, host distro, branch, + commit, and log. + From the information, report files using a JSON format are created and + stored in + <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>. + </para> +</section> + +<section id='ref-classes-rm-work'> + <title><filename>rm_work.bbclass</filename></title> + + <para> + The <filename>rm_work</filename> class supports deletion of temporary + workspace, which can ease your hard drive demands during builds. + </para> + + <para> + The OpenEmbedded build system can use a substantial amount of disk + space during the build process. + A portion of this space is the work files under the + <filename>${TMPDIR}/work</filename> directory for each recipe. + Once the build system generates the packages for a recipe, the work + files for that recipe are no longer needed. + However, by default, the build system preserves these files + for inspection and possible debugging purposes. + If you would rather have these files deleted to save disk space + as the build progresses, you can enable <filename>rm_work</filename> + by adding the following to your <filename>local.conf</filename> file, + which is found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + <literallayout class='monospaced'> + INHERIT += "rm_work" + </literallayout> + If you are modifying and building source code out of the work directory + for a recipe, enabling <filename>rm_work</filename> will potentially + result in your changes to the source being lost. + To exclude some recipes from having their work directories deleted by + <filename>rm_work</filename>, you can add the names of the recipe or + recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename> + variable, which can also be set in your <filename>local.conf</filename> + file. + Here is an example: + <literallayout class='monospaced'> + RM_WORK_EXCLUDE += "busybox glibc" + </literallayout> + </para> +</section> + +<section id='ref-classes-rootfs*'> + <title><filename>rootfs*.bbclass</filename></title> + + <para> + The <filename>rootfs*</filename> classes support creating + the root filesystem for an image and consist of the following classes: + <itemizedlist> + <listitem><para> + The <filename>rootfs-postcommands</filename> class, which + defines filesystem post-processing functions for image recipes. + </para></listitem> + <listitem><para> + The <filename>rootfs_deb</filename> class, which supports + creation of root filesystems for images built using + <filename>.deb</filename> packages.</para></listitem> + <listitem><para> + The <filename>rootfs_rpm</filename> class, which supports + creation of root filesystems for images built using + <filename>.rpm</filename> packages.</para></listitem> + <listitem><para> + 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> + + <para> + The root filesystem is created from packages using one of the + <filename>rootfs*.bbclass</filename> files as determined by the + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + variable. + </para> + + <para> + For information on how root filesystem images are created, see the + "<link linkend='image-generation-dev-environment'>Image Generation</link>" + section. + </para> +</section> + +<section id='ref-classes-sanity'> + <title><filename>sanity.bbclass</filename></title> + + <para> + The <filename>sanity</filename> class checks to see if prerequisite + software is present on the host system so that users can be notified + of potential problems that might affect their build. + The class also performs basic user configuration checks from + the <filename>local.conf</filename> configuration file to + prevent common mistakes that cause build failures. + Distribution policy usually determines whether to include this class. + </para> +</section> + +<section id='ref-classes-scons'> + <title><filename>scons.bbclass</filename></title> + + <para> + The <filename>scons</filename> class supports recipes that need to + build software that uses the SCons build system. + You can use the + <link linkend='var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></link> + variable to specify additional configuration options you want to pass + SCons command line. + </para> +</section> + +<section id='ref-classes-sdl'> + <title><filename>sdl.bbclass</filename></title> + + <para> + The <filename>sdl</filename> class supports recipes that need to build + software that uses the Simple DirectMedia Layer (SDL) library. + </para> +</section> + +<section id='ref-classes-setuptools'> + <title><filename>setuptools.bbclass</filename></title> + + <para> + The <filename>setuptools</filename> class supports Python + version 2.x extensions that use build systems based on + <filename>setuptools</filename>. + If your recipe uses these build systems, the recipe needs to + inherit the <filename>setuptools</filename> class. + </para> +</section> + +<section id='ref-classes-setuptools3'> + <title><filename>setuptools3.bbclass</filename></title> + + <para> + The <filename>setuptools3</filename> class supports Python + version 3.x extensions that use build systems based on + <filename>setuptools3</filename>. + If your recipe uses these build systems, the recipe needs to + inherit the <filename>setuptools3</filename> class. + </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> + + <para> + The <filename>sip</filename> class + supports recipes that build or package SIP-based Python bindings. + </para> +</section> + +<section id='ref-classes-siteconfig'> + <title><filename>siteconfig.bbclass</filename></title> + + <para> + The <filename>siteconfig</filename> class + provides functionality for handling site configuration. + The class is used by the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class to accelerate the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task. + </para> +</section> + +<section id='ref-classes-siteinfo'> + <title><filename>siteinfo.bbclass</filename></title> + + <para> + The <filename>siteinfo</filename> class provides information about + the targets that might be needed by other classes or recipes. + </para> + + <para> + As an example, consider Autotools, which can require tests that must + execute on the target hardware. + Since this is not possible in general when cross compiling, site + information is used to provide cached test results so these tests can + be skipped over but still make the correct values available. + The + <filename><link linkend='structure-meta-site'>meta/site directory</link></filename> + contains test results sorted into different categories such as + architecture, endianness, and the <filename>libc</filename> used. + Site information provides a list of files containing data relevant to + the current build in the + <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable + that Autotools automatically picks up. + </para> + + <para> + The class also provides variables like + <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename> + and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename> + that can be used elsewhere in the metadata. + </para> + + <para> + Because the + <link linkend='ref-classes-base'><filename>base</filename></link> class + includes the <filename>siteinfo</filename> class, it is always active. + </para> +</section> + +<section id='ref-classes-spdx'> + <title><filename>spdx.bbclass</filename></title> + + <para> + The <filename>spdx</filename> class integrates real-time license + scanning, generation of SPDX standard output, and verification + of license information during the build. + <note> + This class is currently at the prototype stage in the 1.6 + release. + </note> + </para> +</section> + +<section id='ref-classes-sstate'> + <title><filename>sstate.bbclass</filename></title> + + <para> + The <filename>sstate</filename> class provides support for Shared + State (sstate). + By default, the class is enabled through the + <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link> + variable's default value. + </para> + + <para> + For more information on sstate, see the + "<link linkend='shared-state-cache'>Shared State Cache</link>" + section. + </para> +</section> + +<section id='ref-classes-staging'> + <title><filename>staging.bbclass</filename></title> + + <para> + The <filename>staging</filename> class provides the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task, which stages files into the sysroot to make them available to + other recipes at build time. + The class is enabled by default because it is inherited by the + <link linkend='ref-classes-base'><filename>base</filename></link> + class. + </para> +</section> + +<section id='ref-classes-syslinux'> + <title><filename>syslinux.bbclass</filename></title> + + <para> + The <filename>syslinux</filename> class provides syslinux-specific + functions for building bootable images. + </para> + + <para> + The class supports the following variables: + <itemizedlist> + <listitem><para><link linkend='var-INITRD'><filename>INITRD</filename></link>: + Indicates list of filesystem images to concatenate and use as + an initial RAM disk (initrd). + This variable is optional.</para></listitem> + <listitem><para><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>: + Indicates a filesystem image to include as the root filesystem. + This variable is optional.</para></listitem> + <listitem><para><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>: + Enables creating an automatic menu when set to "1". + </para></listitem> + <listitem><para><link linkend='var-LABELS'><filename>LABELS</filename></link>: + Lists targets for automatic configuration. + </para></listitem> + <listitem><para><link linkend='var-APPEND'><filename>APPEND</filename></link>: + Lists append string overrides for each label. + </para></listitem> + <listitem><para><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>: + Lists additional options to add to the syslinux file. + Semicolon characters separate multiple options. + </para></listitem> + <listitem><para><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>: + Lists a background for the VGA boot menu when you are using the + boot menu.</para></listitem> + <listitem><para><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>: + Set to "console=ttyX" to change kernel boot default console. + </para></listitem> + <listitem><para><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>: + Sets an alternate serial port. + Or, turns off serial when the variable is set with an + empty string.</para></listitem> + <listitem><para><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>: + Sets an alternate "console=tty..." kernel boot argument. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='ref-classes-systemd'> + <title><filename>systemd.bbclass</filename></title> + + <para> + The <filename>systemd</filename> class provides support for recipes + that install systemd unit files. + </para> + + <para> + The functionality for this class is disabled unless you have "systemd" + in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + </para> + + <para> + Under this class, the recipe or Makefile (i.e. whatever the recipe is + calling during the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task) installs unit files into + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>. + If the unit files being installed go into packages other than the + main package, you need to set + <link linkend='var-SYSTEMD_PACKAGES'><filename>SYSTEMD_PACKAGES</filename></link> + in your recipe to identify the packages in which the files will be + installed. + </para> + + <para> + You should set + <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link> + to the name of the service file. + You should also use a package name override to indicate the package + to which the value applies. + If the value applies to the recipe's main package, use + <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>. + Here is an example from the connman recipe: + <literallayout class='monospaced'> + SYSTEMD_SERVICE_${PN} = "connman.service" + </literallayout> + Services are set up to start on boot automatically unless + you have set + <link linkend='var-SYSTEMD_AUTO_ENABLE'><filename>SYSTEMD_AUTO_ENABLE</filename></link> + to "disable". + </para> + + <para> + For more information on <filename>systemd</filename>, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager'>Selecting an Initialization Manager</ulink>" + section in the Yocto Project Development Manual. + </para> +</section> + +<section id='ref-classes-terminal'> + <title><filename>terminal.bbclass</filename></title> + + <para> + The <filename>terminal</filename> class provides support for starting + a terminal session. + The + <link linkend='var-OE_TERMINAL'><filename>OE_TERMINAL</filename></link> + variable controls which terminal emulator is used for the session. + </para> + + <para> + Other classes use the <filename>terminal</filename> class anywhere a + separate terminal session needs to be started. + For example, the + <link linkend='ref-classes-patch'><filename>patch</filename></link> + class assuming + <link linkend='var-PATCHRESOLVE'><filename>PATCHRESOLVE</filename></link> + is set to "user", the + <link linkend='ref-classes-cml1'><filename>cml1</filename></link> + class, and the + <link linkend='ref-classes-devshell'><filename>devshell</filename></link> + class all use the <filename>terminal</filename> class. + </para> +</section> + +<section id='ref-classes-testimage*'> + <title><filename>testimage*.bbclass</filename></title> + + <para> + 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> + The tests are commands that run on the target system over + <filename>ssh</filename>. + 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 in the Yocto Project Development Manual. + </para> +</section> + +<section id='ref-classes-testsdk'> + <title><filename>testsdk.bbclass</filename></title> + + <para> + This class supports running automated tests against + software development kits (SDKs). + The <filename>testsdk</filename> class runs tests on an SDK when + called using the following: + <literallayout class='monospaced'> + $ bitbake -c testsdk image + </literallayout> + </para> +</section> + +<section id='ref-classes-texinfo'> + <title><filename>texinfo.bbclass</filename></title> + + <para> + This class should be inherited by recipes whose upstream packages + invoke the <filename>texinfo</filename> utilities at build-time. + Native and cross recipes are made to use the dummy scripts provided + by <filename>texinfo-dummy-native</filename>, for improved performance. + Target architecture recipes use the genuine + Texinfo utilities. + By default, they use the Texinfo utilities on the host system. + <note> + If you want to use the Texinfo recipe shipped with the build + system, you can remove "texinfo-native" from + <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link> + and makeinfo from + <link linkend='var-SANITY_REQUIRED_UTILITIES'><filename>SANITY_REQUIRED_UTILITIES</filename></link>. + </note> + </para> +</section> + +<section id='ref-classes-tinderclient'> + <title><filename>tinderclient.bbclass</filename></title> + + <para> + The <filename>tinderclient</filename> class submits build results to + an external Tinderbox instance. + <note> + This class is currently unmaintained. + </note> + </para> +</section> + +<section id='ref-classes-toaster'> + <title><filename>toaster.bbclass</filename></title> + + <para> + The <filename>toaster</filename> class collects information about + packages and images and sends them as events that the BitBake + user interface can receive. + The class is enabled when the Toaster user interface is running. + </para> + + <para> + This class is not intended to be used directly. + </para> +</section> + +<section id='ref-classes-toolchain-scripts'> + <title><filename>toolchain-scripts.bbclass</filename></title> + + <para> + The <filename>toolchain-scripts</filename> class provides the scripts + used for setting up the environment for installed SDKs. + </para> +</section> + +<section id='ref-classes-typecheck'> + <title><filename>typecheck.bbclass</filename></title> + + <para> + The <filename>typecheck</filename> class provides support for + validating the values of variables set at the configuration level + against their defined types. + The OpenEmbedded build system allows you to define the type of a + variable using the "type" varflag. + Here is an example: + <literallayout class='monospaced'> + IMAGE_FEATURES[type] = "list" + </literallayout> + </para> +</section> + +<section id='ref-classes-uboot-config'> + <title><filename>uboot-config.bbclass</filename></title> + + <para> + The <filename>uboot-config</filename> class provides support for + U-Boot configuration for a machine. + Specify the machine in your recipe as follows: + <literallayout class='monospaced'> + UBOOT_CONFIG ??= <default> + UBOOT_CONFIG[foo] = "config,images" + </literallayout> + You can also specify the machine using this method: + <literallayout class='monospaced'> + UBOOT_MACHINE = "config" + </literallayout> + See the + <link linkend='var-UBOOT_CONFIG'><filename>UBOOT_CONFIG</filename></link> + and + <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link> + variables for additional information. + </para> +</section> + +<section id='ref-classes-uninative'> + <title><filename>uninative.bbclass</filename></title> + + <para> + Attempts to isolate the build system from the host + distribution's C library in order to make re-use of native shared state + artifacts across different host distributions practical. + With this class enabled, a tarball containing a pre-built C library + is downloaded at the start of the build. + In the Poky reference distribution this is enabled by default + through + <filename>meta/conf/distro/include/yocto-uninative.inc</filename>. + Other distributions that do not derive from poky can also + "<filename>require conf/distro/include/yocto-uninative.inc</filename>" + to use this. + Alternatively if you prefer, you can build the uninative-tarball recipe + yourself, publish the resulting tarball (e.g. via HTTP) and set + <filename>UNINATIVE_URL</filename> and + <filename>UNINATIVE_CHECKSUM</filename> appropriately. + For an example, see the + <filename>meta/conf/distro/include/yocto-uninative.inc</filename>. + </para> +</section> + +<section id='ref-classes-update-alternatives'> + <title><filename>update-alternatives.bbclass</filename></title> + + <para> + The <filename>update-alternatives</filename> class helps the + alternatives system when multiple sources provide the same command. + This situation occurs when several programs that have the same or + similar function are installed with the same name. + For example, the <filename>ar</filename> command is available from the + <filename>busybox</filename>, <filename>binutils</filename> and + <filename>elfutils</filename> packages. + The <filename>update-alternatives</filename> class handles + renaming the binaries so that multiple packages can be installed + without conflicts. + The <filename>ar</filename> command still works regardless of which + packages are installed or subsequently removed. + The class renames the conflicting binary in each package and symlinks + the highest priority binary during installation or removal of packages. + </para> + + <para> + To use this class, you need to define a number of variables: + <itemizedlist> + <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link> + </para></listitem> + <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link> + </para></listitem> + <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link> + </para></listitem> + <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link> + </para></listitem> + </itemizedlist> + These variables list alternative commands needed by a package, + provide pathnames for links, default links for targets, and + so forth. + For details on how to use this class, see the comments in the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>. + </para> + + <note> + You can use the <filename>update-alternatives</filename> command + directly in your recipes. + However, this class simplifies things in most cases. + </note> +</section> + +<section id='ref-classes-update-rc.d'> + <title><filename>update-rc.d.bbclass</filename></title> + + <para> + The <filename>update-rc.d</filename> class uses + <filename>update-rc.d</filename> to safely install an + initialization script on behalf of the package. + The OpenEmbedded build system takes care of details such as making + sure the script is stopped before a package is removed and started when + the package is installed. + </para> + + <para> + Three variables control this class: + <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>, + <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and + <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>. + See the variable links for details. + </para> +</section> + +<section id='ref-classes-useradd'> + <title><filename>useradd*.bbclass</filename></title> + + <para> + 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 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 these classes. + </para> + + <para> + 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>, + and + <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link> + variables. + </para> + + <para> + The <filename>useradd-staticids</filename> class supports the addition + of users or groups that have static user identification + (<filename>uid</filename>) and group identification + (<filename>gid</filename>) values. + </para> + + <para> + The default behavior of the OpenEmbedded build system for assigning + <filename>uid</filename> and <filename>gid</filename> values when + packages add users and groups during package install time is to + add them dynamically. + This works fine for programs that do not care what the values of the + resulting users and groups become. + In these cases, the order of the installation determines the final + <filename>uid</filename> and <filename>gid</filename> values. + However, if non-deterministic + <filename>uid</filename> and <filename>gid</filename> values are a + problem, you can override the default, dynamic application of these + values by setting static values. + When you set static values, the OpenEmbedded build system looks in + <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for + <filename>files/passwd</filename> and <filename>files/group</filename> + files for the values. + </para> + + <para> + To use static <filename>uid</filename> and <filename>gid</filename> + values, you need to set some variables. + See the + <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>, + <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>, + <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>, + and + <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link> + variables. + You can also see the + <link linkend='ref-classes-useradd'><filename>useradd</filename></link> + class for additional information. + </para> + + <note><title>Notes</title> + 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, + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + might contain incorrect <filename>uid</filename> and + <filename>gid</filename> values. + Deleting the <filename>TMPDIR</filename> directory + will correct this condition. + </note> +</section> + +<section id='ref-classes-utility-tasks'> + <title><filename>utility-tasks.bbclass</filename></title> + + <para> + The <filename>utility-tasks</filename> class provides support for + various "utility" type tasks that are applicable to all recipes, + such as + <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and + <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>. + </para> + + <para> + This class is enabled by default because it is inherited by + the + <link linkend='ref-classes-base'><filename>base</filename></link> + class. + </para> +</section> + +<section id='ref-classes-utils'> + <title><filename>utils.bbclass</filename></title> + + <para> + The <filename>utils</filename> class provides some useful Python + functions that are typically used in inline Python expressions + (e.g. <filename>${@...}</filename>). + One example use is for <filename>bb.utils.contains()</filename>. + </para> + + <para> + This class is enabled by default because it is inherited by the + <link linkend='ref-classes-base'><filename>base</filename></link> + class. + </para> +</section> + +<section id='ref-classes-vala'> + <title><filename>vala.bbclass</filename></title> + + <para> + The <filename>vala</filename> class supports recipes that need to + build software written using the Vala programming language. + </para> +</section> + +<section id='ref-classes-waf'> + <title><filename>waf.bbclass</filename></title> + + <para> + The <filename>waf</filename> class supports recipes that need to build + software that uses the Waf build system. + You can use the + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> + variable to specify additional configuration options to be passed on + the Waf command line. + </para> +</section> + +<!-- Undocumented classes are: + image-empty.bbclass (possibly being dropped) + migrate_localcount.bbclass (still need a description) +--> + + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
