From 882e9cd2affb773eec8b1d387ab4e3b5cbdc0994 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Tue, 26 Feb 2008 11:31:34 +0000 Subject: Add Poky handbook git-svn-id: https://svn.o-hand.com/repos/poky/trunk@3865 311d38ba-8fff-0310-9ca6-ca027cbcb966 --- handbook/ref-classes.xml | 460 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 460 insertions(+) create mode 100644 handbook/ref-classes.xml (limited to 'handbook/ref-classes.xml') 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 @@ + + + +Reference: Classes + + + Class files are used to abstract common functionality and share it amongst multiple + .bb files. Any metadata usually found in a + .bb file can also be placed in a class + file. Class files are identified by the extension + .bbclass and are usually placed + in a classes/ directory beneath the + meta/ directory or the build/ directory in the same way as .conf files in the conf directory. Class files are searched for + in BBPATH in the same was as .conf files too. + + + + 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. + + +
+ The base class - <filename>base.bbclass</filename> + + + The base class is special in that every .bb + 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 autotools.bbclass or + package.bbclass. The class contains some commonly + some commonly used functions such as oe_libinstall + and oe_runmake. The end of the class file has a + list of standard mirrors for software projects for use by the fetcher code. + +
+ +
+ Autotooled Packages - <filename>autotools.bbclass</filename> + + + 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 simple autotools + example section and then simply "inherit autotools". This class + can also work with software that emulates autotools. + + + + Its useful to have some idea of the tasks this class defines work and + what they do behind the scenes. + + + + + + '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 + configure through the EXTRA_OECONF variable. + + + + + 'do_compile' runs make with arguments specifying + the compiler and linker. Additional arguments can be passed through + the EXTRA_OEMAKE + variable. + + + + + 'do_install' runs make install passing a DESTDIR + option taking its value from the standard DESTDIR variable. + + + + + + By default the class does not stage headers and libraries so + the recipe author needs to add their own do_stage() + task. For typical recipes the following example code will usually be + enough: + +do_stage() { +autotools_stage_all +} + +
+ +
+ Alternatives - <filename>update-alternatives.bbclass</filename> + + + Several programs can fulfill the same or similar function and + they can be installed with the same name. For example the ar + 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 + ar 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: + + + + + + ALTERNATIVE_NAME + + + Name of binary which will be replaced (ar in this example) + + + + + ALTERNATIVE_LINK + + + Path to resulting binary ("/bin/ar" in this example) + + + + + ALTERNATIVE_PATH + + + Path to real binary ("/usr/bin/ar.binutils" in this example) + + + + + ALTERNATIVE_PRIORITY + + + Priority of binary, the version with the most features should have the highest priority + + + + +
+ +
+ Initscripts - <filename>update-rc.d.bbclass</filename> + + + 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, + INITSCRIPT_PACKAGES, + INITSCRIPT_NAME and + INITSCRIPT_PARAMS. See the + links for details. + +
+ +
+ Binary config scripts - <filename>binconfig.bbclass</filename> + + + 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. + + + + During staging Bitbake installs such scripts into the staging/ directory. It also changes all + paths to point into the staging/ + directory so all builds which use the script will use the correct + directories for the cross compiling layout. + +
+ +
+ Debian renaming - <filename>debian.bbclass</filename> + + + This class renames packages so that they follow the Debian naming + policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes + 'libc6-dev'. + +
+ +
+ Pkg-config - <filename>pkgconfig.bbclass</filename> + + + Pkg-config brought standardisation and this class aims to make its + integration smooth for all libraries which make use of it. + + + + During staging Bitbake installs pkg-config data into the staging/ directory. By making use of + sysroot functionality within pkgconfig this class no longer has to + manipulate the files. + +
+ +
+ Distribution of sources - <filename>src_distribute_local.bbclass</filename> + + + Many software licenses require providing the sources for compiled + binaries. To simplify this process two classes were created: + src_distribute.bbclass and + src_distribute_local.bbclass. + + + + Result of their work are tmp/deploy/source/ + subdirs with sources sorted by LICENSE + field. If recipe lists few licenses (or has entries like "Bitstream Vera") source archive is put in each + license dir. + + + + Src_distribute_local class has three modes of operating: + + + + copy - copies the files to the distribute dir + symlink - symlinks the files to the distribute dir + move+symlink - moves the files into distribute dir, and symlinks them back + +
+ +
+ Perl modules - <filename>cpan.bbclass</filename> + + + 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. + + + + Modules which use old Makefile.PL based build system require + using of cpan.bbclass in their recipes. + + + + Modules which use Build.PL based build system require + using of cpan_build.bbclass in their recipes. + + +
+ +
+ Python extensions - <filename>distutils.bbclass</filename> + + + 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. + + + + Extensions which use autotools based build system require using + of autotools and distutils-base bbclasses in their recipes. + + + + Extensions which use distutils build system require using + of distutils.bbclass in their recipes. + + +
+ +
+ Developer Shell - <filename>devshell.bbclass</filename> + + + This class adds the devshell task. Its usually up to distribution policy + to include this class (Poky does). See the developing with 'devshell' section + for more information about using devshell. + + +
+ +
+ Packaging - <filename>package*.bbclass</filename> + + + The packaging classes add support for generating packages from the output + from builds. The core generic functionality is in + package.bbclass, code specific to particular package + types is contained in various sub classes such as + package_deb.bbclass and package_ipk.bbclass. + Most users will + want one or more of these classes and this is controlled by the + PACKAGE_CLASSES + 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. + + +
+ +
+ Building kernels - <filename>kernel.bbclass</filename> + + + 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 STAGING_KERNEL_DIR + directory to allow building of out-of-tree modules using module.bbclass. + + + The means that each kerel module built is packaged separately and inter-modules dependencies are + created by parsing the modinfo 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. + + + + Various other classes are used by the kernel and module classes internally including + kernel-arch.bbclass, module_strip.bbclass, + module-base.bbclass and linux-kernel-base.bbclass. + +
+ +
+ Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename> + + + Those classes add support for creating images in many formats. First the + rootfs is created from packages by one of the rootfs_*.bbclass + files (depending on package format used) and then image is created. + + The IMAGE_FSTYPES + variable controls which types of image to generate. + + The list of packages to install into the image is controlled by the + IMAGE_INSTALL + variable. + +
+ +
+ Host System sanity checks - <filename>sanity.bbclass</filename> + + + 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). + +
+ +
+ Generated output quality assurance checks - <filename>insane.bbclass</filename> + + + 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). + +
+ +
+ Autotools configuration data cache - <filename>siteinfo.bbclass</filename> + + + 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 meta/site directory + 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 CONFIG_SITE + variable which autotools will automatically pick up. + + + The class also provides variables like SITEINFO_ENDIANESS + and SITEINFO_BITS + which can be used elsewhere in the metadata. + + + This class is included from base.bbclass and is hence always active. + +
+ +
+ Other Classes + + + Only the most useful/important classes are covered here but there are + others, see the meta/classes directory for the rest. + +
+ + + + + + -- cgit 1.2.3-korg