diff options
Diffstat (limited to 'handbook/ref-classes.xml')
| -rw-r--r-- | handbook/ref-classes.xml | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/handbook/ref-classes.xml b/handbook/ref-classes.xml new file mode 100644 index 0000000000..1cef9012c1 --- /dev/null +++ b/handbook/ref-classes.xml @@ -0,0 +1,460 @@ +<!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 class="extension">.bb</filename> files. Any metadata usually found in a + <filename class="extension">.bb</filename> file can also be placed in a class + file. Class files are identified by the extension + <filename class="extension">.bbclass</filename> and are usually placed + in a <filename class="directory">classes/</filename> directory beneath the + <filename class="directory">meta/</filename> directory or the <filename + class="directory">build/</filename> directory in the same way as <filename + class="extension">.conf</filename> files in the <filename + class="directory">conf</filename> directory. Class files are searched for + in BBPATH in the same was as <filename class="extension">.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 class="extension">.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 contains some commonly + some commonly used functions such as <function>oe_libinstall</function> + and <function>oe_runmake</function>. The end of the class file has a + list of standard mirrors for software projects for use by the fetcher code. + </para> +</section> + +<section id='ref-classes-autotools'> + <title>Autotooled Packages - <filename>autotools.bbclass</filename></title> + + <para> + Autotools (autoconf, automake, libtool) brings standardisation and this + class aims to define a set of tasks (configure, compile etc.) that will + work for all autotooled packages. It should usualy 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> + Its useful to have some idea of the tasks this class defines work and + what they do behind the scenes. + </para> + + <itemizedlist> + <listitem> + <para> + 'do_configure' regenearates the configure script and + then launches it with a standard set of arguments used during + cross-compilation. Additional parameters can be passed to + <command>configure</command> through the <glossterm><link + linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm> variable. + </para> + </listitem> + <listitem> + <para> + 'do_compile' runs <command>make</command> with arguments specifying + the compiler and linker. Additional arguments can be passed through + the <glossterm><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link> + </glossterm> variable. + </para> + </listitem> + <listitem> + <para> + 'do_install' runs <command>make install</command> passing a DESTDIR + option taking its value from the standard <glossterm><link + linkend='var-DESTDIR'>DESTDIR</link></glossterm> variable. + </para> + </listitem> + </itemizedlist> + + <para> + By default the class does not stage headers and libraries so + the recipe author needs to add their own <function>do_stage()</function> + task. For typical recipes the following example code will usually be + enough: + <programlisting> +do_stage() { +autotools_stage_all +}</programlisting> + </para> +</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 + they can be installed with the same name. For example the <command>ar</command> + command is available from the "busybox", "binutils" and "elfutils" packages. + This class handles the renaming of the binaries so multiple packages + can be installed which would otherwise conflict and yet the + <command>ar</command> command still works regardless of which are installed + or subsequently removed. It renames the conflicting binary in each package + and symlinks the highest priority binary during installation or removal + of packages. + + Four variables control this class: + </para> + + + <variablelist> + <varlistentry> + <term>ALTERNATIVE_NAME</term> + <listitem> + <para> + Name of binary which will be replaced (<command>ar</command> in this example) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ALTERNATIVE_LINK</term> + <listitem> + <para> + Path to resulting binary ("/bin/ar" in this example) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ALTERNATIVE_PATH</term> + <listitem> + <para> + Path to real binary ("/usr/bin/ar.binutils" in this example) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>ALTERNATIVE_PRIORITY</term> + <listitem> + <para> + Priority of binary, the version with the most features should have the highest priority + </para> + </listitem> + </varlistentry> + </variablelist> +</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 became 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">staging/</filename> directory. It also changes all + paths to point into the <filename class="directory">staging/</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">staging/</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 class="directory">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 - 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> + Extensions which use autotools based build system require using + of autotools and distutils-base bbclasses in their recipes. + </para> + + <para> + Extensions which use distutils build system require using + 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 the output + from builds. 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> and <filename>package_ipk.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 handle 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> + The means that each kerel module built is packaged separately and inter-modules dependencies are + created by parsing the <command>modinfo</command> output. If all modules are + required then installing "kernel-modules" package will install all + packages with modules and various other kernel packages such as "kernel-vmlinux" are also generated. + </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 try and identify + and notify the user of problems which will affect their build. It also + performs basic checks of the users configuration from local.conf to + prevent common mistakes and resulting build failures. Its usually up to + distribution policy 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 + this makes, checking for common problems which break builds/packages/images, + see the bbclass file for more information. Its usually up to distribution + policy to include this class (Poky doesn't at the time of writing but plans + to soon). + </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 class="directory">meta/classes</filename> directory for the rest. + </para> +</section> + +<!-- Undocumented classes are: + base_srpm.bbclass + bootimg.bbclass + ccache.inc + ccdv.bbclass + cml1.bbclass + cross.bbclass + flow-lossage.bbclass + gconf.bbclass + gettext.bbclass + gnome.bbclass + gtk-icon-cache.bbclass + icecc.bbclass + lib_package.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 + xfce.bbclass + xlibs.bbclass +--> + + +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> |