<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <appendix id='ref-classes'> <title>Reference: Classes</title> <para> Class files are used to abstract common functionality and share it amongst multiple <filename>.bb</filename> files. Any metadata usually found in a <filename>.bb</filename> file 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 or the directory pointed by BUILDDIR (e.g. <filename>build/</filename>)in the same way as <filename>.conf</filename> files in the <filename class="directory">conf</filename> directory. Class files are searched for in BBPATH in the same was as <filename>.conf</filename> files too. </para> <para> In most cases inheriting the class is enough to enable its features, although for some classes you may need to set variables and/or override some of the default behaviour. </para> <section id='ref-classes-base'> <title>The base class - <filename>base.bbclass</filename></title> <para> The base class is special in that every <filename>.bb</filename> file inherits it automatically. It contains definitions of standard basic tasks such as fetching, unpacking, configuring (empty by default), compiling (runs any Makefile present), installing (empty by default) and packaging (empty by default). These are often overridden or extended by other classes such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>. The class also contains some commonly used functions such as <filename>oe_runmake</filename>. </para> </section> <section id='ref-classes-autotools'> <title>Autotooled Packages - <filename>autotools.bbclass</filename></title> <para> Autotools (autoconf, automake, libtool) bring standardization. This class defines a set of tasks (configure, compile etc.) that work for all autotooled packages. It should usually be enough to define a few standard variables as documented in the <link linkend='usingpoky-extend-addpkg-autotools'>simple autotools example</link> section and then simply "inherit autotools". This class can also work with software that emulates autotools. </para> <para> It's useful to have some idea of how the tasks defined by this class work and what they do behind the scenes. </para> <itemizedlist> <listitem> <para> <filename>do_configure</filename> ‐ regenerates the configure script (using autoreconf) 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 <glossterm><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm> variable. </para> </listitem> <listitem> <para> <filename>do_compile</filename> ‐ runs <filename>make</filename> with arguments that specify the compiler and linker. You can pass additional arguments through the <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link> </glossterm> variable. </para> </listitem> <listitem> <para> <filename>do_install</filename> ‐ runs <filename>make install</filename> and passes a <filename>DESTDIR</filename> option, which takes its value from the standard <glossterm><link linkend='var-DESTDIR'>DESTDIR</link></glossterm> variable. </para> </listitem> </itemizedlist> </section> <section id='ref-classes-update-alternatives'> <title>Alternatives - <filename>update-alternatives.bbclass</filename></title> <para> Several programs can fulfill the same or similar function and be installed with the same name. For example, the <filename>ar</filename> command is available from the "busybox", "binutils" and "elfutils" packages. The <filename>update-alternatives.bbclass</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> Four variables control this class: </para> <itemizedlist> <listitem><para><filename>ALTERNATIVE_NAME</filename> ‐ The name of the binary that is replaced (<filename>ar</filename> in this example).</para></listitem> <listitem><para><filename>ALTERNATIVE_LINK</filename> ‐ The path to the resulting binary (<filename>/bin/ar</filename> in this example).</para></listitem> <listitem><para><filename>ALTERNATIVE_PATH</filename> ‐ The path to the real binary (<filename>/usr/bin/ar.binutils</filename> in this example).</para></listitem> <listitem><para><filename>ALTERNATIVE_PRIORITY</filename> ‐ The priority of the binary. The version with the most features should have the highest priority.</para></listitem> </itemizedlist> <para> Currently, only one binary per package is supported. </para> </section> <section id='ref-classes-update-rc.d'> <title>Initscripts - <filename>update-rc.d.bbclass</filename></title> <para> This class uses update-rc.d to safely install an initscript on behalf of the package. Details such as making sure the initscript is stopped before a package is removed and started when the package is installed are taken care of. Three variables control this class, <link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link>, <link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link> and <link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link>. See the links for details. </para> </section> <section id='ref-classes-binconfig'> <title>Binary config scripts - <filename>binconfig.bbclass</filename></title> <para> Before pkg-config had become widespread, libraries shipped shell scripts to give information about the libraries and include paths needed to build software (usually named 'LIBNAME-config'). This class assists any recipe using such scripts. </para> <para> During staging Bitbake installs such scripts into the <filename class="directory">sysroots/</filename> directory. It also changes all paths to point into the <filename>sysroots/</filename> directory so all builds which use the script will use the correct directories for the cross compiling layout. </para> </section> <section id='ref-classes-debian'> <title>Debian renaming - <filename>debian.bbclass</filename></title> <para> This class renames packages so that they follow the Debian naming policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes 'libc6-dev'. </para> </section> <section id='ref-classes-pkgconfig'> <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title> <para> Pkg-config brought standardisation and this class aims to make its integration smooth for all libraries which make use of it. </para> <para> During staging Bitbake installs pkg-config data into the <filename class="directory">sysroots/</filename> directory. By making use of sysroot functionality within pkgconfig this class no longer has to manipulate the files. </para> </section> <section id='ref-classes-src-distribute'> <title>Distribution of sources - <filename>src_distribute_local.bbclass</filename></title> <para> Many software licenses require providing the sources for compiled binaries. To simplify this process two classes were created: <filename>src_distribute.bbclass</filename> and <filename>src_distribute_local.bbclass</filename>. </para> <para> Result of their work are <filename>tmp/deploy/source/</filename> subdirs with sources sorted by <glossterm><link linkend='var-LICENSE'>LICENSE</link> </glossterm> field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each license dir. </para> <para> Src_distribute_local class has three modes of operating: </para> <itemizedlist> <listitem><para>copy - copies the files to the distribute dir</para></listitem> <listitem><para>symlink - symlinks the files to the distribute dir</para></listitem> <listitem><para>move+symlink - moves the files into distribute dir, and symlinks them back</para></listitem> </itemizedlist> </section> <section id='ref-classes-perl'> <title>Perl modules - <filename>cpan.bbclass</filename></title> <para> Recipes for Perl modules are simple - usually needs only pointing to source archive and inheriting of proper bbclass. Building is split into two methods dependly on method used by module authors. </para> <para> Modules which use old Makefile.PL based build system require using of <filename>cpan.bbclass</filename> in their recipes. </para> <para> Modules which use Build.PL based build system require using of <filename>cpan_build.bbclass</filename> in their recipes. </para> </section> <section id='ref-classes-distutils'> <title>Python extensions - <filename>distutils.bbclass</filename></title> <para> Recipes for Python extensions are simple - they usually only require pointing to the source archive and inheriting the proper bbclasses. Building is split into two methods depending on the build method used by the module authors. </para> <para> Extensions which use autotools based build system require use of autotools and distutils-base bbclasses in their recipes. </para> <para> Extensions which use distutils build system require use of <filename>distutils.bbclass</filename> in their recipes. </para> </section> <section id='ref-classes-devshell'> <title>Developer Shell - <filename>devshell.bbclass</filename></title> <para> This class adds the devshell task. Its usually up to distribution policy to include this class (Poky does). See the <link linkend='platdev-appdev-devshell'>developing with 'devshell' section</link> for more information about using devshell. </para> </section> <section id='ref-classes-package'> <title>Packaging - <filename>package*.bbclass</filename></title> <para> The packaging classes add support for generating packages from a builds output. The core generic functionality is in <filename>package.bbclass</filename>, code specific to particular package types is contained in various sub classes such as <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename> and <filename>package_rpm.bbclass</filename>. Most users will want one or more of these classes and this is controlled by the <glossterm> <link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></glossterm> variable. The first class listed in this variable will be used for image generation. Since images are generated from packages a packaging class is needed to enable image generation. </para> </section> <section id='ref-classes-kernel'> <title>Building kernels - <filename>kernel.bbclass</filename></title> <para> This class handles building of Linux kernels and the class contains code to know how to build both 2.4 and 2.6 kernel trees. All needed headers are staged into <glossterm><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></glossterm> directory to allow building of out-of-tree modules using <filename>module.bbclass</filename>. </para> <para> This means that each kernel module built is packaged separately and inter-module dependencies are created by parsing the <filename>modinfo</filename> output. If all modules are required then installing the "kernel-modules" package will install all packages with modules and various other kernel packages such as "kernel-vmlinux". </para> <para> Various other classes are used by the kernel and module classes internally including <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>, <filename>module-base.bbclass</filename> and <filename>linux-kernel-base.bbclass</filename>. </para> </section> <section id='ref-classes-image'> <title>Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title> <para> Those classes add support for creating images in many formats. First the rootfs is created from packages by one of the <filename>rootfs_*.bbclass</filename> files (depending on package format used) and then image is created. The <glossterm><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></glossterm> variable controls which types of image to generate. The list of packages to install into the image is controlled by the <glossterm><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></glossterm> variable. </para> </section> <section id='ref-classes-sanity'> <title>Host System sanity checks - <filename>sanity.bbclass</filename></title> <para> This class checks prerequisite software is present to notify the users of potential problems that will affect their build. It also performs basic checks of the user configuration from local.conf to prevent common mistakes resulting in build failures. It's usually up to distribution policy whether to include this class (Poky does). </para> </section> <section id='ref-classes-insane'> <title>Generated output quality assurance checks - <filename>insane.bbclass</filename></title> <para> This class adds a step to package generation which sanity checks the packages generated by Poky. There are an ever increasing range of checks it performs, checking for common problems which break builds/packages/images, see the bbclass file for more information. It's usually up to distribution policy whether to include this class (Poky does). </para> </section> <section id='ref-classes-siteinfo'> <title>Autotools configuration data cache - <filename>siteinfo.bbclass</filename></title> <para> Autotools can require tests which have to execute on the target hardware. Since this isn't possible in general when cross compiling, siteinfo is used to provide cached test results so these tests can be skipped over but the correct values used. The <link linkend='structure-meta-site'>meta/site directory</link> contains test results sorted into different categories like architecture, endianess and the libc used. Siteinfo provides a list of files containing data relevant to the current build in the <glossterm><link linkend='var-CONFIG_SITE'>CONFIG_SITE </link></glossterm> variable which autotools will automatically pick up. </para> <para> The class also provides variables like <glossterm><link linkend='var-SITEINFO_ENDIANESS'>SITEINFO_ENDIANESS</link></glossterm> and <glossterm><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link> </glossterm> which can be used elsewhere in the metadata. </para> <para> This class is included from <filename>base.bbclass</filename> and is hence always active. </para> </section> <section id='ref-classes-others'> <title>Other Classes</title> <para> Only the most useful/important classes are covered here but there are others, see the <filename>meta/classes</filename> directory for the rest. </para> </section> <!-- Undocumented classes are: base_srpm.bbclass bootimg.bbclass ccache.inc ccdv.bbclass cmake.bbclass cml1.bbclass cross.bbclass flow-lossage.bbclass gconf.bbclass gettext.bbclass gnome.bbclass gtk-icon-cache.bbclass icecc.bbclass lib_package.bbclass mirrors.bbclass mozilla.bbclass multimachine.bbclass native.bbclass oelint.bbclass patch.bbclass patcher.bbclass pkg_distribute.bbclass pkg_metainfo.bbclass poky.bbclass rm_work.bbclass rpm_core.bbclass scons.bbclass sdk.bbclass sdl.bbclass sip.bbclass sourcepkg.bbclass srec.bbclass syslinux.bbclass tinderclient.bbclass tmake.bbclass utils.bbclass xfce.bbclass xlibs.bbclass --> </appendix> <!-- vim: expandtab tw=80 ts=4 -->