From ed0a240e1632682ec4c33341f3e24ad71773cdfc Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 11 Dec 2012 12:07:58 -0600 Subject: documentation: Rename of poky-ref-manual folder to ref-manual. Changing the folder that holds the YP Reference Manual to be "ref-manual". This will help with confustion over the manual's intended purpose. (From yocto-docs rev: 1106442964b5080cb0b6b3bd3af32e9407c0f7c1) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-classes.xml | 720 +++++++++++++++++++++++++++++++ 1 file changed, 720 insertions(+) create mode 100644 documentation/ref-manual/ref-classes.xml (limited to 'documentation/ref-manual/ref-classes.xml') diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml new file mode 100644 index 0000000000..2caea272a4 --- /dev/null +++ b/documentation/ref-manual/ref-classes.xml @@ -0,0 +1,720 @@ + %poky; ] > + + +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 found in the + Source Directory. + 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 might need to set variables 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. + 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 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. + +
+ +
+ Autotooled Packages - <filename>autotools.bbclass</filename> + + + Autotools (autoconf, automake, + and 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 + and then simply inherit autotools. + This class can also work with software that emulates Autotools. + For more information, see the + "Autotooled Package" + section in the Yocto Project Development Manual. + + + + 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. + + + +
+ +
+ 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. + 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. + + + 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. + + + + + Currently, the OpenEmbedded build system supports only one binary per package. + +
+ +
+ Initscripts - <filename>update-rc.d.bbclass</filename> + + + This class uses update-rc.d to safely install an + initialization script on behalf of the package. + The OpenEmbedded build system 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. + +
+ +
+ Binary config scripts - <filename>binconfig.bbclass</filename> + + + 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. + + + + 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. + +
+ +
+ Debian renaming - <filename>debian.bbclass</filename> + + + This class renames packages so that they follow the Debian naming + policy (i.e. eglibc becomes libc6 + and eglibc-devel becomes libc6-dev. + +
+ +
+ Pkg-config - <filename>pkgconfig.bbclass</filename> + + + 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 pkg-config, + this class no longer has to manipulate the files. + +
+ +
+ Distribution of sources - <filename>src_distribute_local.bbclass</filename> + + + 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. + + + + 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. + + + + 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. + + +
+ +
+ Perl modules - <filename>cpan.bbclass</filename> + + + 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 depending on which method the module authors used. + + + + Modules that use old Makefile.PL-based build system require + cpan.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. + 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 that use an Autotools-based build system require Autotools and + distutils-based .bbclasse files 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. + Distribution policy dictates whether to include this class. + See the + "Using a Development Shell" section + in the Yocto Project Development Manual for more information about using devshell. + +
+ +
+ Package Groups - <filename>packagegroup.bbclass</filename> + + + This class sets default values appropriate for package group recipes (such as + PACKAGES, + PACKAGE_ARCH, + ALLOW_EMPTY, + and so forth. + It is highly recommended that all package group recipes inherit this class. + + + For information on how to use this class, see the + "Customizing Images Using Custom Package Tasks" + section in the Yocto Project Development Manual. + + + Previously, this class was named task.bbclass. + +
+ + +
+ Packaging - <filename>package*.bbclass</filename> + + + 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 defined in the local.conf configuration file, + which is located in the conf folder of the + Source Directory. + When defining the variable, you can specify one or more package types. + Since images are generated from packages, a packaging class is + needed to enable image generation. + The first class listed in this variable is used for image generation. + + + + The package class you choose can affect build-time performance and has space + ramifications. + In general, building a package with RPM takes about thirty percent more time as + compared to using IPK to build the same or similar package. + This comparison takes into account a complete build of the package with all + dependencies previously built. + The reason for this discrepancy is because the RPM package manager creates and + processes more metadata than the IPK package manager. + Consequently, you might consider setting PACKAGE_CLASSES + to "package_ipk" if you are building smaller systems. + + + + Keep in mind, however, that RPM starts to provide more abilities than IPK due to + the fact that it processes more metadata. + For example, this information includes individual file types, file checksum generation + and evaluation on install, sparse file support, conflict detection and resolution + for multilib systems, ACID style upgrade, and repackaging abilities for rollbacks. + + + + Another consideration for packages built using the RPM package manager is space. + For smaller systems, the extra space used for the Berkley Database and the amount + of metadata can affect your ability to do on-device upgrades. + + + + You can find additional information on the effects of the package class at these + two Yocto Project mailing list links: + + + https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html + + https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html + + +
+ +
+ Building kernels - <filename>kernel.bbclass</filename> + + + 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 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. + +
+ +
+ Creating images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename> + + + 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 the types of images to generate. + + + + The IMAGE_INSTALL + variable controls the list of packages to install into the image. + +
+ +
+ Host System sanity checks - <filename>sanity.bbclass</filename> + + + 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 determines whether to include this class. + +
+ +
+ Generated output quality assurance checks - <filename>insane.bbclass</filename> + + + This class adds a step to the package generation process that sanity checks the + packages generated by the OpenEmbedded build system. + A range of checks are performed that check the build's output + for common problems that show up during runtime. + Distribution policy usually dictates whether to include this class. + + + + You can configure the sanity checks so that specific test failures either raise a warning or + an error message. + Typically, failures for new tests generate a warning. + Subsequent failures for the same test would then generate an error message + once the metadata is in a known and good condition. + You use the WARN_QA variable to specify tests for which you + want to generate a warning message on failure. + You use the ERROR_QA variable to specify tests for which you + want to generate an error message on failure. + + + + The following list shows the tests you can list with the WARN_QA + and ERROR_QA variables: + + ldflags: + Ensures that the binaries were linked with the + LDFLAGS options provided by the build system. + If this test fails, check that the LDFLAGS variable + is being passed to the linker command. + useless-rpaths: + Checks for dynamic library load paths (rpaths) in the binaries that + by default on a standard system are searched by the linker (e.g. + /lib and /usr/lib). + While these paths will not cause any breakage, they do waste space and + are unnecessary. + rpaths: + Checks for rpaths in the binaries that contain build system paths such + as TMPDIR. + If this test fails, bad -rpath options are being + passed to the linker commands and your binaries have potential security + issues. + dev-so: + Checks that the .so symbolic links are in the + -dev package and not in any of the other packages. + In general, these symlinks are only useful for development purposes. + Thus, the -dev package is the correct location for + them. + Some very rare cases do exist for dynamically loaded modules where + these symlinks are needed instead in the main package. + + debug-files: + Checks for .debug directories in anything but the + -dbg package. + The debug files should all be in the -dbg package. + Thus, anything packaged elsewhere is incorrect packaging. + arch: + Checks the Executable and Linkable Format (ELF) type, bit size and endianness + of any binaries to ensure it matches the target architecture. + This test fails if any binaries don't match the type since there would be an + incompatibility. + Sometimes software, like bootloaders, might need to bypass this check. + + debug-deps: + Checks that -dbg packages only depend on other + -dbg packages and not on any other types of packages, + which would cause a packaging bug. + dev-deps: + Checks that -dev packages only depend on other + -dev packages and not on any other types of packages, + which would be a packaging bug. + pkgconfig: + Checks .pc files for any + TMPDIR/WORKDIR paths. + Any .pc file containing these paths is incorrect + since pkg-config itself adds the correct sysroot prefix + when the files are accessed. + la: + Checks .la files for any TMPDIR + paths. + Any .la file continaing these paths is incorrect since + libtool adds the correct sysroot prefix when using the + files automatically itself. + desktop: + Runs the desktop-file-validate program against any + .desktop files to validate their contents against + the specification for .desktop files. + + +
+ +
+ Autotools configuration data cache - <filename>siteinfo.bbclass</filename> + + + 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 + still make the correct values available. + The meta/site directory + contains test results sorted into different categories such as architecture, endianness, 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_ENDIANNESS + and SITEINFO_BITS + that can be used elsewhere in the metadata. + + + + Because this class is included from base.bbclass, it is always active. + +
+ +
+ Adding Users - <filename>useradd.bbclass</filename> + + + If you have packages that install files that are owned by custom users or groups, + you can use this class to specify those packages and associate the users and groups + with those packages. + The meta-skeleton/recipes-skeleton/useradd/useradd-example.bb + recipe in the Source Directory + provides a simple exmample that shows how to add three + users and groups to two packages. + See the useradd-example.bb for more information on how to + use this class. + +
+ +
+ Using External Source - <filename>externalsrc.bbclass</filename> + + + You can use this class to build software from source code that is external to the + OpenEmbedded build system. + In other words, your source code resides in an external tree outside of the Yocto Project. + Building software from an external source tree means that the normal fetch, unpack, and + patch process is not used. + + + + To use the class, you need to define the + S variable to point to the directory that contains the source files. + You also need to have your recipe inherit the externalsrc.bbclass class. + + + + This class expects the source code to support recipe builds that use the + B variable to point to the directory in + which the OpenEmbedded build system places the generated objects built from the recipes. + By default, the B directory is set to the following, which is separate from the + Source Directory (S): + + ${WORKDIR}/${BPN}/{PV}/ + + See the glossary entries for the + WORKDIR, + BPN, + PV, + S, and + B for more information. + + + + You can build object files in the external tree by setting the + B variable equal to "${S}". + However, this practice does not work well if you use the source for more than one variant + (i.e., "natives" such as quilt-native, + or "crosses" such as gcc-cross). + So, be sure there are no "native", "cross", or "multilib" variants of the recipe. + + + + If you do want to build different variants of a recipe, you can use the + BBCLASSEXTEND variable. + When you do, the B variable must support the + recipe's ability to build variants in different working directories. + Most autotools-based recipes support separating these directories. + The OpenEmbedded build system defaults to using separate directories for gcc + and some kernel recipes. + Alternatively, you can make sure that separate recipes exist that each + use the BBCLASSEXTEND variable to build each variant. + The separate recipes can inherit a single target recipe. + + + + For information on how to use this class, see the + "Building + Software from an External Source" section in the Yocto Project Development Manual. + +
+ +
+ Other Classes + + + Thus far, this chapter has discussed only the most useful and important + classes. + However, other classes exist within the meta/classes directory + in the Source Directory. + You can examine the .bbclass files directly for more + information. + +
+ + + + + + -- cgit v1.2.3-54-g00ecf