Add Poky handbook

git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3865 311d38ba-8fff-0310-9ca6-ca027cbcb966

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