From 95ef8d7a2ea01aa18a19788f175e089e3126d3d4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 19 Aug 2011 12:01:54 -0700 Subject: [PATCH] documentation/poky-ref-manual/ref-classes.xml: Scrubbed for Poky I changed the "Poky" references to "the Yocto Project" and performed general edits where necessary. (From yocto-docs rev: a7ef3e7d5c792bde5231b9302e614cb7b5db81b7) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/ref-classes.xml | 376 +++++++++--------- 1 file changed, 191 insertions(+), 185 deletions(-) diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml index 8eb94c268b..d054df1204 100644 --- a/documentation/poky-ref-manual/ref-classes.xml +++ b/documentation/poky-ref-manual/ref-classes.xml @@ -6,21 +6,21 @@ 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 + .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 directory pointed - by BUILDDIR (e.g. build/)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. + meta*/ directory found in the Yocto Project file's area + Class files can also be pointed to by BUILDDIR (e.g. build/)in the same way as + .conf files in the conf directory. + Class files are searched for in BBPATH + using the same method by which .conf files are searched. 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 + for some classes you might need to set variables or override some of the default behaviour. @@ -29,13 +29,14 @@ The base class is special in that every .bb - file inherits it automatically. It contains definitions of standard basic + file inherits it automatically. + This class contains definitions for 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 also contains some commonly - used functions such as oe_runmake. + (runs any Makefile present), installing (empty by default) and packaging + (empty by default). + These classes are often overridden or extended by other classes + such as autotools.bbclass or package.bbclass. + The class also contains some commonly used functions such as oe_runmake. @@ -43,84 +44,71 @@ Autotooled Packages - <filename>autotools.bbclass</filename> - Autotools (autoconf, automake, libtool) bring standardization. + Autotools (autoconf, automake, + and libtool) bring standardization. This class defines a set of tasks (configure, compile etc.) that - work for all autotooled packages. + work for all Autotooled packages. It should usually 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. + Autotooled Package section + and then simply inherit autotools. + This class can also work with software that emulates Autotools. It's useful to have some idea of how the tasks defined by this class work and what they do behind the scenes. + + do_configure ‐ 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 configure through the + EXTRA_OECONF variable. + + do_compile ‐ runs make with + arguments that specify the compiler and linker. + You can pass additional arguments through + the EXTRA_OEMAKE variable. + + do_install ‐ runs make install + and passes a DESTDIR option, which takes its value from the standard + DESTDIR variable. + + - - - - - do_configure ‐ 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 - configure through the - EXTRA_OECONF variable. - - - - - do_compile ‐ runs make with - arguments that specify the compiler and linker. - You can pass additional arguments through - the EXTRA_OEMAKE - variable. - - - - - do_install ‐ runs make install - and passes a DESTDIR - option, which takes its value from the standard - DESTDIR variable. - - - -
Alternatives - <filename>update-alternatives.bbclass</filename> - Several programs can fulfill the same or similar function and - be installed with the same name. - For example, the ar - command is available from the "busybox", "binutils" and "elfutils" packages. + Several programs can fulfill the same or similar function and be installed with the same name. + For example, the ar command is available from the + busybox, binutils and + elfutils packages. The update-alternatives.bbclass class handles renaming the binaries so that multiple packages can be installed without conflicts. The ar 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. + The class 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 ‐ The name of the + binary that is replaced (ar in this example). + ALTERNATIVE_LINK ‐ The path to + the resulting binary (/bin/ar in this example). + ALTERNATIVE_PATH ‐ The path to the + real binary (/usr/bin/ar.binutils in this example). + ALTERNATIVE_PRIORITY ‐ The priority of + the binary. + The version with the most features should have the highest priority. + - - ALTERNATIVE_NAME ‐ The name of the - binary that is replaced (ar in this example). - ALTERNATIVE_LINK ‐ The path to - the resulting binary (/bin/ar in this example). - ALTERNATIVE_PATH ‐ The path to the - real binary (/usr/bin/ar.binutils in this example). - ALTERNATIVE_PRIORITY ‐ The priority of - the binary. - The version with the most features should have the highest priority. - + - Currently, only one binary per package is supported. + Currently, the Yocto Project supports only one binary per package.
@@ -128,14 +116,15 @@ 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. + This class uses update-rc.d to safely install an + initialization script on behalf of the package. + The Yocto Project takes care of details such as making sure the script is stopped before + a package is removed and started when the package is installed. + Three variables control this class: + INITSCRIPT_PACKAGES, + INITSCRIPT_NAME and + INITSCRIPT_PARAMS. + See the variable links for details. @@ -143,17 +132,17 @@ Binary config scripts - <filename>binconfig.bbclass</filename> - Before pkg-config had become widespread, libraries shipped shell + 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. + to build software (usually named LIBNAME-config). + This class assists any recipe using such scripts. - During staging Bitbake installs such scripts into the sysroots/ directory. It also changes all - paths to point into the sysroots/ - directory so all builds which use the script will use the correct + During staging, Bitbake installs such scripts into the + sysroots/ directory. + BitBake also changes all paths to point into the sysroots/ + directory so all builds that use the script will use the correct directories for the cross compiling layout. @@ -163,8 +152,8 @@ This class renames packages so that they follow the Debian naming - policy, i.e. 'glibc' becomes 'libc6' and 'glibc-devel' becomes - 'libc6-dev'. + policy (i.e. glibc becomes libc6 + and glibc-devel becomes libc6-dev. @@ -172,15 +161,15 @@ 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. + pkg-config brought standardization and this class aims to make its + integration smooth for all libraries that make use of it. - During staging Bitbake installs pkg-config data into the sysroots/ directory. By making use of - sysroot functionality within pkgconfig this class no longer has to - manipulate the files. + During staging, Bitbake installs pkg-config data into the + sysroots/ directory. + By making use of sysroot functionality within pkg-config, + this class no longer has to manipulate the files. @@ -188,126 +177,131 @@ 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: + Many software licenses require that source files be provided along with the 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. + The results of these classes are tmp/deploy/source/ + subdirs with sources sorted by + LICENSE field. + If recipes list few licenses (or have entries like "Bitstream Vera"), + the source archive is placed in each license directory. - Src_distribute_local class has three modes of operating: + This class operates using three modes: + + copy: Copies the files to the + distribute directory. + symlink: Symlinks the files to the + distribute directory. + move+symlink: Moves the files into + the distribute directory and then symlinks them back. + - - - 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. + Recipes for Perl modules are simple. + These recipes usually only need to point to the source's archive and then inherit the + proper .bbclass file. + Building is split into two methods dependling on which method the module authors used. - Modules which use old Makefile.PL based build system require - using of cpan.bbclass in their recipes. + Modules that use old Makefile.PL-based build system require + cpan.bbclass in their recipes. - Modules which use Build.PL based build system require - using of cpan_build.bbclass in their recipes. + Modules that use Build.PL-based build system require + using cpan_build.bbclass in their recipes. -
Python extensions - <filename>distutils.bbclass</filename> - 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. + Recipes for Python extensions are simple. + These recipes usually only need to point to the source's archive and then inherit + the proper .bbclass file. + Building is split into two methods dependling on which method the module authors used. - Extensions which use autotools based build system require use - of autotools and distutils-base bbclasses in their recipes. + Extensions that use an Autotools-based build system require Autotools and + distutils-based .bbclasse files in their recipes. - Extensions which use distutils build system require use - of distutils.bbclass in their recipes. + Extensions that use distutils-based build systems require + 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 + This class adds the devshell task. + Distribution policy dictates whether to include this class as the Yocto Project does. + See the Development Within a Development Shell section for more information about using devshell. -
Packaging - <filename>package*.bbclass</filename> - The packaging classes add support for generating packages from a builds - output. 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, package_ipk.bbclass - and package_rpm.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 + The packaging classes add support for generating packages from a build's + output. + The core generic functionality is in package.bbclass. + The code specific + to particular package types is contained in various sub-classes such as + package_deb.bbclass, package_ipk.bbclass, + and package_rpm.bbclass. + Most users will want one or more of these classes. + You can control the list of resulting package formats by using the + PACKAGE_CLASSES + variable. + The first class listed in this variable is 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 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 STAGING_KERNEL_DIR - directory to allow building of out-of-tree modules using module.bbclass. + This class handles building Linux kernels. + The class contains code to build all kernel trees. + All needed headers are staged into the + STAGING_KERNEL_DIR + directory to allow out-of-tree module builds using module.bbclass. + - This means that each kernel module built is packaged separately and inter-module dependencies are - created by parsing the modinfo 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". + This means that each built kernel module is packaged separately and inter-module + dependencies are created by parsing the modinfo output. + If all modules are required, then installing the kernel-modules + package installs all packages with modules and various other kernel packages + such as kernel-vmlinux. 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. + module-base.bbclass, and linux-kernel-base.bbclass.
@@ -315,18 +309,20 @@ 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. + These classes add support for creating images in several formats. + First, the root filesystem is created from packages using + one of the rootfs_*.bbclass + files (depending on the package format used) and then the 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. + + The IMAGE_FSTYPES + variable controls the types of images to generate. + + + + The IMAGE_INSTALL + variable controls the list of packages to install into the image. @@ -334,11 +330,12 @@ Host System sanity checks - <filename>sanity.bbclass</filename> - 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). + This class checks to see if prerequisite software is present so that + users can be notified of potential problems that might affect their build. + The class also performs basic user configuration checks from + the local.conf configuration file to + prevent common mistakes that cause build failures. + Distribution policy usually whether to include this class as the Yocto Project does. @@ -346,11 +343,11 @@ 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 - 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). + This class adds a step to the package generation process that sanity checks the + packages generated by the Yocto Project. + An ever-increasing range of checks are performed that check for + common problems that break builds. + Distribution policy usually dictates whether to include this class as the Yocto Project does. @@ -358,23 +355,28 @@ 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 + Autotools can require tests that must execute on the target hardware. + Since this is not possible in general when cross compiling, site information 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. + still make the correct values available. + The meta/site directory + contains test results sorted into different categories such as architecture, endianess, and + the libc used. + Site information provides a list of files containing data relevant to + the current build in the + CONFIG_SITE variable + that Autotools automatically picks up. + - The class also provides variables like SITEINFO_ENDIANESS - and SITEINFO_BITS - which can be used elsewhere in the metadata. + The class also provides variables like + SITEINFO_ENDIANESS + and SITEINFO_BITS + that can be used elsewhere in the metadata. + - This class is included from base.bbclass and is hence always active. + Because this class is included from base.bbclass, it is always active. @@ -382,8 +384,12 @@ Other Classes - Only the most useful/important classes are covered here but there are - others, see the meta/classes directory for the rest. + Thus far, this appendix has discussed only the most useful and important + classes. + However, other classes exist within the meta/classes directory + in the Yocto Project file's directory structure. + You can examine the .bbclass files directly for more + information.