diff options
Diffstat (limited to 'documentation/ref-manual/ref-classes.xml')
| -rw-r--r-- | documentation/ref-manual/ref-classes.xml | 3885 |
1 files changed, 0 insertions, 3885 deletions
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml deleted file mode 100644 index 5403f20b6f..0000000000 --- a/documentation/ref-manual/ref-classes.xml +++ /dev/null @@ -1,3885 +0,0 @@ -<!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 <link linkend='metadata'>Metadata</link> 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 - <link linkend='source-directory'>Source Directory</link>. - 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 Source Directory. - 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 Tasks 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 Tasks Manual. - </para> - - <para> - By default, the <filename>autotools*</filename> classes - use out-of-tree builds (i.e. - <filename>autotools.bbclass</filename> building with - <filename>B != S</filename>). - </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> - or - <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> - variables. - </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. - </para> - - <para> - The class also contains some commonly used functions such as - <filename>oe_runmake</filename>, which runs - <filename>make</filename> with the arguments specified in - <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link> - variable as well as the arguments passed directly to - <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-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 - "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" - section in the Yocto Project Development Tasks Manual. - </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 C/C++ Compiler Cache - 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 - <ulink url='https://cmake.org/overview/'>CMake</ulink> 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 - using 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 - "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" - section in the Yocto Project Overview and Concepts Manual 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 - "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" - section in the Yocto Project Overview and Concepts Manual 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 Tasks Manual for more information about - using <filename>devshell</filename>. - </para> -</section> - -<section id='ref-classes-devupstream'> - <title><filename>devupstream.bbclass</filename></title> - - <para> - The <filename>devupstream</filename> class uses - <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> - to add a variant of the recipe that fetches from an alternative URI - (e.g. Git) instead of a tarball. - Following is an example: - <literallayout class='monospaced'> - BBCLASSEXTEND = "devupstream:target" - SRC_URI_class-devupstream = "git://git.example.com/example" - SRCREV_class-devupstream = "abcd1234" - </literallayout> - Adding the above statements to your recipe creates a variant that has - <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link> - set to "-1". - Consequently, you need to select the variant of the recipe to use it. - Any development-specific adjustments can be done by using the - <filename>class-devupstream</filename> override. - Here is an example: - <literallayout class='monospaced'> - DEPENDS_append_class-devupstream = " gperf-native" - - do_configure_prepend_class-devupstream() { - touch ${S}/README - } - </literallayout> - The class currently only supports creating a development variant of - the target recipe, not <filename>native</filename> or - <filename>nativesdk</filename> variants. - </para> - - <para> - The <filename>BBCLASSEXTEND</filename> syntax - (i.e. <filename>devupstream:target</filename>) provides support for - <filename>native</filename> and <filename>nativesdk</filename> - variants. - Consequently, this functionality can be added in a future release. - </para> - - <para> - Support for other version control systems such as Subversion is - limited due to BitBake's automatic fetch dependencies (e.g. - <filename>subversion-native</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-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> -</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 - <link linkend='source-directory'>Source Directory</link>. - 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 Tasks 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-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-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 Tasks Manual. - For information on how images are created, see the - "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>" - section in the Yocto Project Overview and Concpets 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, the - <link linkend='ref-classes-image'><filename>image</filename></link> - class automatically enables the <filename>image_types</filename> class. - The <filename>image</filename> class uses the - <filename>IMGCLASSES</filename> variable as follows: - <literallayout class='monospaced'> - IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" - IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" - IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" - IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" - IMGCLASSES += "image_types_wic" - IMGCLASSES += "rootfs-postcommands" - IMGCLASSES += "image-postinst-intercepts" - inherit ${IMGCLASSES} - </literallayout> - </para> - - <para> - The <filename>image_types</filename> class also handles conversion and - compression of images. - <note> - To build a VMware VMDK image, you need to add "wic.vmdk" to - <filename>IMAGE_FSTYPES</filename>. - This would also be similar for Virtual Box Virtual Disk Image - ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. - </note> - </para> -</section> - -<section id='ref-classes-image-live'> - <title><filename>image-live.bbclass</filename></title> - - <para> - This class controls building "live" (i.e. HDDIMG and ISO) images. - Live images contain syslinux for legacy booting, as well as the - bootloader specified by - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - if - <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> - contains "efi". - </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>. - </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-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 id='insane-host-user-contaminated'> - <emphasis><filename>host-user-contaminated:</filename></emphasis> - Checks that no package produced by the recipe contains any - files outside of <filename>/home</filename> with a user or - group ID that matches the user running BitBake. - A match usually indicates that the files are being installed - with an incorrect UID/GID, since target IDs are independent - from host IDs. - For additional information, see the section describing the - <link linkend='ref-tasks-install'><filename>do_install</filename></link> - task. - </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>invalid-chars:</filename></emphasis> - Checks that the recipe metadata variables - <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>, - <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>, - <link linkend='var-LICENSE'><filename>LICENSE</filename></link>, - and - <link linkend='var-SECTION'><filename>SECTION</filename></link> - do not contain non-UTF-8 characters. - Some package managers do not support such characters. - </para></listitem> - <listitem><para><emphasis><filename>invalid-packageconfig:</filename></emphasis> - Checks that no undefined features are being added to - <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>. - For example, any name "foo" for which the following form - does not exist: - <literallayout class='monospaced'> - PACKAGECONFIG[foo] = "..." - </literallayout> - </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> -<!-- -This check was removed for YP 2.3 release - - <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>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> - The <filename>kernel</filename> class contains logic that allows - you to embed an initial RAM filesystem (initramfs) image when - you build the kernel image. - For information on how to build an initramfs, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>" - section in the Yocto Project Development Tasks Manual. - </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-devicetree'> - <title><filename>kernel-devicetree.bbclass</filename></title> - - <para> - The <filename>kernel-devicetree</filename> class, which is inherited by - the - <link linkend='ref-classes-kernel'><filename>kernel</filename></link> - class, supports device tree generation. - </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_DEV_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 Tasks 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 build tools to run on the - <link linkend='hardware-build-system-term'>build host</link> - (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> - recipe 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. - <note><title>Warning</title> - When creating a recipe this way, the recipe name must - follow this naming convention: - <literallayout class='monospaced'> - <replaceable>myrecipe</replaceable>-native.bb - </literallayout> - Not using this naming convention can lead to subtle - problems caused by existing code that depends on that - naming convention. - </note> - </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> - <note><title>Warning</title> - When creating a recipe, you must follow this naming convention: - <literallayout class='monospaced'> - nativesdk-<replaceable>myrecipe</replaceable>.bb - </literallayout> - Not doing so can lead to subtle problems because code exists - that depends on the naming convention. - </note> - </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 - <ulink url='https://en.wikipedia.org/wiki/Npm_(software)'>node package manager (NPM)</ulink>. - <note> - Currently, recipes inheriting this class must use the - <filename>npm://</filename> fetcher to have dependencies fetched - and packaged automatically. - </note> - For information on how to create NPM packages, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-node-package-manager-npm-packages'>Creating Node Package Manager (NPM) Packages</ulink>" - section in the Yocto Project Development Tasks Manual. - </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 - <link linkend='source-directory'>Source Directory</link>. - </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 - <link linkend='build-directory'>Build Directory</link>. - 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 DNF, 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 Tasks 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 - <link linkend='metadata'>Metadata</link> 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 Tasks 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 Application Development and the - Extensible Software Development Kit (eSDK) manual. - </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 - "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>" - section in the Yocto Project Overview and Concepts Manual. - 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 Application Development and the - Extensible Software Development Kit (eSDK) manual. - </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 Tasks 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 Tasks 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 - <link linkend='build-directory'>Build Directory</link>. - <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 - "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>" - section in the Yocto Project Overview and Concepts Manual. - </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> -</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 - "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>" - section in the Yocto Project Overview and Concepts Manual. - </para> -</section> - -<section id='ref-classes-staging'> - <title><filename>staging.bbclass</filename></title> - - <para> - The <filename>staging</filename> class installs files into individual - recipe work directories for sysroots. - The class contains the following key tasks: - <itemizedlist> - <listitem><para> - The - <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> - task, which is responsible for handing the files that end up - in the recipe sysroots. - </para></listitem> - <listitem><para> - The - <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> - task (a "partner" task to the - <filename>populate_sysroot</filename> task), which installs - the files into the individual recipe work directories (i.e. - <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). - </para></listitem> - </itemizedlist> - </para> - - <para> - The code in the <filename>staging</filename> class is complex and - basically works in two stages: - <itemizedlist> - <listitem><para> - <emphasis>Stage One:</emphasis> - The first stage addresses recipes that have files they want - to share with other recipes that have dependencies on the - originating recipe. - Normally these dependencies are installed through the - <link linkend='ref-tasks-install'><filename>do_install</filename></link> - task into - <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>. - The <filename>do_populate_sysroot</filename> task copies - a subset of these files into - <filename>${SYSROOT_DESTDIR}</filename>. - This subset of files is controlled by the - <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>, - <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>, - and - <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link> - variables. - <note> - Additionally, a recipe can customize the files further by - declaring a processing function in the - <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link> - variable. - </note> - </para> - - <para> - A shared state (sstate) object is built from these files - and the files are placed into a subdirectory of - <link linkend='structure-build-tmp-sysroots-components'><filename>tmp/sysroots-components/</filename></link>. - The files are scanned for hardcoded paths to the original - installation location. - If the location is found in text files, the hardcoded - locations are replaced by tokens and a list of the files - needing such replacements is created. - These adjustments are referred to as "FIXMEs". - The list of files that are scanned for paths is controlled by - the - <link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link> - variable. - </para></listitem> - <listitem><para> - <emphasis>Stage Two:</emphasis> - The second stage addresses recipes that want to use something - from another recipe and declare a dependency on that recipe - through the - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> - variable. - The recipe will have a - <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> - task and when - this task executes, it creates the - <filename>recipe-sysroot</filename> and - <filename>recipe-sysroot-native</filename> in the recipe - work directory (i.e. - <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). - The OpenEmbedded build system creates hard links to copies of the - relevant files from <filename>sysroots-components</filename> - into the recipe work directory. - <note> - If hard links are not possible, the build system uses - actual copies. - </note> - The build system then addresses any "FIXMEs" to paths as - defined from the list created in the first stage. - </para> - - <para> - Finally, any files in <filename>${bindir}</filename> - within the sysroot that have the prefix - "<filename>postinst-</filename>" are executed. - <note> - Although such sysroot post installation scripts are not - recommended for general use, the files do allow some issues - such as user creation and module indexes to be addressed. - </note> - </para> - - <para> - Because recipes can have other dependencies outside of - <filename>DEPENDS</filename> (e.g. - <filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>), - the sysroot creation function - <filename>extend_recipe_sysroot</filename> is also added as - a pre-function for those tasks whose dependencies are not - through <filename>DEPENDS</filename> but operate similarly. - </para> - - <para> - When installing dependencies into the sysroot, the code - traverses the dependency graph and processes dependencies - in exactly the same way as the dependencies would or would not - be when installed from sstate. - This processing means, for example, a native tool would have - its native dependencies added but a target library would not - have its dependencies traversed or installed. - The same sstate dependency code is used so that - builds should be identical regardless of whether sstate - was used or not. - For a closer look, see the - <filename>setscene_depvalid()</filename> function in the - <link linkend='ref-classes-sstate'><filename>sstate</filename></link> - class. - </para> - - <para> - The build system is careful to maintain manifests of the files - it installs so that any given dependency can be installed as - needed. - The sstate hash of the installed item is also stored so that - if it changes, the build system can reinstall it. - </para></listitem> - </itemizedlist> - </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 Tasks Manual. - </para> -</section> - -<section id='ref-classes-systemd-boot'> - <title><filename>systemd-boot.bbclass</filename></title> - - <para> - The <filename>systemd-boot</filename> class provides functions specific - to the systemd-boot bootloader for building bootable images. - This is an internal class and is not intended to be used directly. - <note> - The <filename>systemd-boot</filename> class is a result from - merging the <filename>gummiboot</filename> class used in previous - Yocto Project releases with the <filename>systemd</filename> - project. - </note> - Set the - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - variable to "systemd-boot" to use this class. - Doing so creates a standalone EFI bootloader that is not dependent - on systemd. - </para> - - <para> - For information on more variables used and supported in this class, - see the - <link linkend='var-SYSTEMD_BOOT_CFG'><filename>SYSTEMD_BOOT_CFG</filename></link>, - <link linkend='var-SYSTEMD_BOOT_ENTRIES'><filename>SYSTEMD_BOOT_ENTRIES</filename></link>, - and - <link linkend='var-SYSTEMD_BOOT_TIMEOUT'><filename>SYSTEMD_BOOT_TIMEOUT</filename></link> - variables. - </para> - - <para> - You can also see the - <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink> - for more information. - </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. - <note><title>Tip</title> - Best practices include using - <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link> - rather than - <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to - inherit the <filename>testimage</filename> class for automated - image testing. - </note> - </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-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</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 Tasks 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> - <note><title>Tip</title> - Best practices include using - <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link> - rather than - <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to - inherit the <filename>testsdk</filename> class for automated - SDK testing. - </note> - </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> - - <para> - The <filename>uninative</filename> class is also used unconditionally - by the extensible SDK. - When building the extensible SDK, - <filename>uninative-tarball</filename> is built and the resulting - tarball is included within the SDK. - </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> - file. - </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 <link linkend='source-directory'>Source Directory</link> - 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> - or - <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> - variables 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 ---> |