462 lines
18 KiB
XML
462 lines
18 KiB
XML
<!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">sysroots/</filename> directory. It also changes all
|
|
paths to point into the <filename class="directory">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 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 - 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> 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 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>
|
|
The means that each kerel module built is packaged separately and inter-module dependencies are
|
|
created by parsing the <command>modinfo</command> 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" 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 does).
|
|
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
|
|
-->
|