diff options
Diffstat (limited to 'documentation/poky-ref-manual/ref-classes.xml')
| -rw-r--r-- | documentation/poky-ref-manual/ref-classes.xml | 435 |
1 files changed, 0 insertions, 435 deletions
diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml deleted file mode 100644 index 8eb94c268..000000000 --- a/documentation/poky-ref-manual/ref-classes.xml +++ /dev/null @@ -1,435 +0,0 @@ -<!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 ---> |