From 14b00ff23a912494edc7f146e668c40ca82b8508 Mon Sep 17 00:00:00 2001 From: Adrian Dudau Date: Thu, 12 Dec 2013 13:46:05 +0100 Subject: initial commit of Enea Linux 3.1 Migrated from the internal git server on the dora-enea branch Signed-off-by: Adrian Dudau --- documentation/ref-manual/ref-classes.xml | 1104 ++++++++++++++++++++++++++++++ 1 file changed, 1104 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 0000000..27edfde --- /dev/null +++ b/documentation/ref-manual/ref-classes.xml @@ -0,0 +1,1104 @@ + %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 behavior. + + + + This chapter discusses only the most useful and important classes. + Other classes do exist within the meta/classes + directory in the + Source Directory. + You can reference the .bbclass files directly + for more information. + + +
+ 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 in + ${D} + as DESTDIR. + + + +
+ +
+ Alternatives - <filename>update-alternatives.bbclass</filename> + + + This class helps the alternatives system when multiple sources provide + the same command. + This situation occurs when several programs that have the same or + similar function are 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. + + + + To use this class, you need to define a number of variables: + + ALTERNATIVE + + ALTERNATIVE_LINK_NAME + + ALTERNATIVE_TARGET + + ALTERNATIVE_PRIORITY + + + These variables list alternative commands needed by a package, + provide pathnames for links, default links for targets, and + so forth. + For details on how to use this class, see the comments in the + update-alternatives.bbclass. + + + + You can use the update-alternatives command + directly in your recipes. + However, this class simplifies things in most cases. + +
+ +
+ 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. + +
+ +
+ <filename>binconfig.bbclass</filename> + + + This class helps to correct paths in shell scripts. + + + + 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, the OpenEmbedded build system installs such scripts + into the sysroots/ directory. + Inheriting this class results in all paths in these scripts being + changed to point into the sysroots/ directory so + that all builds that use the script use the correct directories + for the cross compiling layout. + See the + BINCONFIG_GLOB + variable for more information. + +
+ +
+ 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 provides a standard way to get + header and library information. + This class aims to smooth integration of + pkg-config into libraries that use 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. + +
+ +
+ Archiving Sources - <filename>archive*.bbclass</filename> + + + Many software licenses require that source code and other materials be + released with the binaries. + To help with that task, the following classes are provided: + + archive-original-sources.bbclass + archive-patched-sources.bbclass + archive-configured-sources.bbclass + archiver.bbclass + + + + + For more details on the source archiver, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" + section in the Yocto Project Development Manual. + +
+ +
+ 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 depending 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 (e.g. + 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 Groups" + 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. + + + + If you take the optional step to set up a repository (package feed) + on the development host that can be used by Smart, you can + install packages from the feed while you are running the image + on the target (i.e. runtime installation of packages). + For more information, see the + "Using Runtime Package Management" + section in the Yocto Project Development Manual. + + + + The package class you choose can affect build-time performance and has space + ramifications. + In general, building a package with IPK takes about thirty percent less + time as compared to using RPM 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. + + + + Before making your decision on package manager, however, you should + consider some further things about using RPM: + + + 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. + + + For smaller systems, the extra space used for the Berkley + Database and the amount of metadata when using RPM can affect + your ability to perform 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 on the host system + 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. + +
+ +
+<filename>insane.bbclass</filename> + + + This class adds a step to the package generation process so that + output quality assurance checks are 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. + + + + Use the + WARN_QA and + ERROR_QA + variables to control the behavior of + these checks at the global level (i.e. in your custom distro + configuration). + However, to skip one or more checks in recipes, you should use + INSANE_SKIP. + For example, to skip the check for symbolic link + .so files in the main package of a recipe, + add the following to the recipe. + You need to realize that the package name override, in this example + ${PN}, must be used: + + INSANE_SKIP_${PN} += "dev-so" + + Please keep in mind that the QA checks exist in order to detect real + or potential problems in the packaged output. + So exercise caution when disabling these checks. + + + + 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 they match 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. + textrel: + Checks for ELF binaries that contain relocations in their + .text sections, which can result in a + performance impact at runtime. + pkgvarcheck: + Checks through the variables + RDEPENDS, + RRECOMMENDS, + RSUGGESTS, + RCONFLICTS, + RPROVIDES, + RREPLACES, + FILES, + ALLOW_EMPTY, + pkg_preinst, + pkg_postinst, + pkg_prerm + and pkg_postrm, and reports if there are + variable sets that are not package-specific. + Using these variables without a package suffix is bad practice, + and might unnecessarily complicate dependencies of other packages + within the same recipe or have other unintended consequences. + + xorg-driver-abi: + Checks that all packages containing Xorg drivers have ABI + dependencies. + The xserver-xorg recipe provides driver + ABI names. + All drivers should depend on the ABI versions that they have + been built against. + Driver recipes that include + xorg-driver-input.inc + or xorg-driver-video.inc will + automatically get these versions. + Consequently, you should only need to explicitly add + dependencies to binary driver recipes. + + libexec: + Checks if a package contains files in + /usr/libexec. + This check is not performed if the + libexecdir variable has been set + explicitly to /usr/libexec. + + staticdev: + Checks for static library files (*.a) in + non-staticdev packages. + + la: + Checks .la files for any TMPDIR + paths. + Any .la file containing 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. + already-stripped: + Checks that produced binaries have not already been + stripped prior to the build system extracting debug symbols. + It is common for upstream software projects to default to + stripping debug symbols for output binaries. + In order for debugging to work on the target using + -dbg packages, this stripping must be + disabled. + + split-strip: + Reports that splitting or stripping debug symbols from binaries + has failed. + + arch: + Checks to ensure the architecture, bit size, and endianness + of all output binaries matches that of the target. + This test can detect when the wrong compiler or compiler options + have been used. + + installed-vs-shipped: + Reports when files have been installed within + do_install but have not been included in + any package by way of the + FILES + variable. + Files that do not appear in any package cannot be present in + an image later on in the build process. + Ideally, all installed files should be packaged or not + installed at all. + These files can be deleted at the end of + do_install if the files are not + needed in any package. + + dep-cmp: + Checks for invalid version comparison statements in runtime + dependency relationships between packages (i.e. in + RDEPENDS, + RRECOMMENDS, + RSUGGESTS, + RPROVIDES, + RREPLACES, + and + RCONFLICTS + variable values). + Any invalid comparisons might trigger failures or undesirable + behavior when passed to the package manager. + + files-invalid: + Checks for + FILES + variable values that contain "//", which is invalid. + + incompatible-license: + Report when packages are excluded from being created due to + being marked with a license that is in + INCOMPATIBLE_LICENSE. + + compile-host-path: + Checks the do_compile log for indications + that paths to locations on the build host were used. + Using such paths might result in host contamination of the + build output. + + install-host-path: + Checks the do_install log for indications + that paths to locations on the build host were used. + Using such paths might result in host contamination of the + build output. + + libdir: + Checks for libraries being installed into incorrect + (possibly hardcoded) installation paths. + For example, this test will catch recipes that install + /lib/bar.so when + ${base_libdir} is "lib32". + Another example is when recipes install + /usr/lib64/foo.so when + ${libdir} is "/usr/lib". + + packages-list: + Checks for the same package being listed multiple times through + the PACKAGES + variable value. + Installing the package in this manner can cause errors during + packaging. + + perm-config: + Reports lines in fs-perms.txt that have + an invalid format. + + perm-line: + Reports lines in fs-perms.txt that have + an invalid format. + + perm-link: + Reports lines in fs-perms.txt that + specify 'link' where the specified target already exists. + + pkgname: + Checks that all packages in + PACKAGES + have names that do not contain invalid characters (i.e. + characters other than 0-9, a-z, ., +, and -). + + pn-overrides: + Checks that a recipe does not have a name + (PN) value + that appears in + OVERRIDES. + If a recipe is named such that its PN + value matches something already in + OVERRIDES (e.g. PN + happens to be the same as + MACHINE + or + DISTRO), + it can have unexpected consequences. + For example, assignments such as + FILES_${PN} = "xyz" effectively turn into + FILES = "xyz". + + unsafe-references-in-binaries: + Reports when a binary installed in + ${base_libdir}, + ${base_bindir}, or + ${base_sbindir}, depends on another + binary installed under ${exec_prefix}. + This dependency is a concern if you want the system to remain + basically operable if /usr is mounted + separately and is not mounted. + + Defaults for binaries installed in + ${base_libdir}, + ${base_bindir}, and + ${base_sbindir} are + /lib, /bin, and + /sbin, respectively. + The default for a binary installed + under ${exec_prefix} is + /usr. + + + unsafe-references-in-scripts: + Reports when a script file installed in + ${base_libdir}, + ${base_bindir}, or + ${base_sbindir}, depends on files + installed under ${exec_prefix}. + This dependency is a concern if you want the system to remain + basically operable if /usr is mounted + separately and is not mounted. + + Defaults for binaries installed in + ${base_libdir}, + ${base_bindir}, and + ${base_sbindir} are + /lib, /bin, and + /sbin, respectively. + The default for a binary installed + under ${exec_prefix} is + /usr. + + + var-undefined: + Reports when variables fundamental to packaging (i.e. + WORKDIR, + DEPLOY_DIR, + D, + PN, and + PKGD) are + undefined during do_package. + + pkgv-undefined: + Checks to see if the PKGV variable + is undefined during do_package. + + buildpaths: + Checks for paths to locations on the build host inside the + output files. + Currently, this test triggers too many false positives and + thus is not normally enabled. + + perms: + Currently, this check is unused but reserved. + + version-going-backwards: + If Build History is enabled, reports when a package + being written out has a lower version than the previously + written package under the same name. + If you are placing output packages into a feed and + upgrading packages on a target system using that feed, the + version of a package going backwards can result in the target + system not correctly upgrading to the "new" version of the + package. + + If you are not using runtime package management on your + target system, then you do not need to worry about + this situation. + + + + +
+ +
+ Removing Work Files During the Build - <filename>rm_work.bbclass</filename> + + + The OpenEmbedded build system can use a substantial amount of disk + space during the build process. + A portion of this space is the work files under the + ${TMPDIR}/work directory for each recipe. + Once the build system generates the packages for a recipe, the work + files for that recipe are no longer needed. + However, by default, the build system preserves these files + for inspection and possible debugging purposes. + If you would rather have these files deleted to save disk space + as the build progresses, you can enable rm_work + by adding the following to your local.conf file, + which is found in the + Build Directory. + + INHERIT += "rm_work" + + If you are modifying and building source code out of the work directory + for a recipe, enabling rm_work will potentially + result in your changes to the source being lost. + To exclude some recipes from having their work directories deleted by + rm_work, you can add the names of the recipe or + recipes you are working on to the RM_WORK_EXCLUDE + variable, which can also be set in your local.conf + file. + Here is an example: + + RM_WORK_EXCLUDE += "busybox eglibc" + + +
+ + +
+ 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 example 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. + +
+ +
+ <filename>externalsrc.bbclass</filename> + + + You can use this class to build software from source code that is + external to the OpenEmbedded build system. + Building software from an external source tree means that the build + system's normal fetch, unpack, and patch process is not used. + + + + By default, the OpenEmbedded build system uses the + S and + B variables to + locate unpacked recipe source code and to build it, respectively. + When your recipe inherits externalsrc.bbclass, + you use the + EXTERNALSRC + and + EXTERNALSRC_BUILD + variables to ultimately define S and + B. + + + + By default, 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, + + + + For more information on + externalsrc.bbclass, see the comments in + meta/classes/externalsrc.bbclass in the + Source Directory. + For information on how to use externalsrc.bbclass, + see the + "Building Software from an External Source" + section in the Yocto Project Development Manual. + +
+ +
+ <filename>testimage.bbclass</filename> + + + You can use this class to enable running a series of automated tests + for images. + The class handles loading the tests and starting the image. + + Currently, there is only support for running these tests + under QEMU. + + + + + To use the class, you need to perform steps to set up the + environment. + The tests are commands that run on the target system over + ssh. + they are written in Python and make use of the + unittest module. + + + + For information on how to enable, run, and create new tests, see the + "Performing Automated Runtime Testing" + section. + +
+ +
+ 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