mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-02-20 08:29:42 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add Poky handbook

Browse Source 
git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3865 311d38ba-8fff-0310-9ca6-ca027cbcb966
This commit is contained in:
Richard Purdie
2008-02-26 11:31:34 +00:00
parent 7197110f46
commit 882e9cd2af
52 changed files with 10973 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

460
handbook/ref-classes.xml Normal file
View File

@@ -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
-->