From ae9f8623a9f882c1db82a45c6d782dee60f88721 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 5 Dec 2013 13:35:21 -0600 Subject: [PATCH] ref-manual: Edits to icecc class and re-order of "I" classes. (From yocto-docs rev: 643ccc4ac495e0dc88de20012d4843d2a402b507) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-classes.xml | 824 ++++++++++++----------- 1 file changed, 422 insertions(+), 402 deletions(-) diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index da47d51fd6..f36c80d6f3 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml @@ -824,9 +824,8 @@ <filename>icecc.bbclass</filename> - The Icecream distributed compile support (icecc) - class stages directories with symlinks from - gcc and g++ to + The icecc class stages directories with symlinks + from gcc and g++ to icecc, for both native and cross compilers. Depending on each configure or compile, the OpenEmbedded build system adds the directories at the head of the PATH list @@ -892,6 +891,61 @@ +
+ 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. + + +
+ +
+ <filename>image_types.bbclass</filename> + + + The image types (image_types) class defines all of + the standard image output types that you can enable through the + IMAGE_FSTYPES + variable. + You can use this class as a reference on how to add support for custom + image output types. + + + + By default, this class is enabled through the + IMAGE_CLASSES + variable in + image.bbclass. + If you define your own image types using a custom BitBake class and + then use IMAGE_CLASSES to enable it, the custom + class must either inherit image_types or + image_types must also appear in + IMAGE_CLASSES. + +
+ +
+ <filename>image_types_uboot.bbclass</filename> + + + The U-Boot image types (image_types_uboot) class + defines additional image types specifically for the U-Boot bootloader. + +
+
<filename>image-live.bbclass</filename> @@ -904,18 +958,6 @@
-
- <filename>image-vmdk.bbclass</filename> - - - The Virtual Machine Disk image (image-vmdk) class - supports building VMware VMDK images. - Normally, you do not use this class directly. - Instead, you add "vmdk" to - IMAGE_FSTYPES. - -
-
<filename>image-mklibs.bbclass</filename> @@ -979,37 +1021,378 @@
-
- <filename>image_types.bbclass</filename> +
+ <filename>image-vmdk.bbclass</filename> - The image types (image_types) class defines all of - the standard image output types that you can enable through the - IMAGE_FSTYPES - variable. - You can use this class as a reference on how to add support for custom - image output types. - - - - By default, this class is enabled through the - IMAGE_CLASSES - variable in - image.bbclass. - If you define your own image types using a custom BitBake class and - then use IMAGE_CLASSES to enable it, the custom - class must either inherit image_types or - image_types must also appear in - IMAGE_CLASSES. + The Virtual Machine Disk image (image-vmdk) class + supports building VMware VMDK images. + Normally, you do not use this class directly. + Instead, you add "vmdk" to + IMAGE_FSTYPES.
-
- <filename>image_types_uboot.bbclass</filename> +
+<filename>insane.bbclass</filename> - The U-Boot image types (image_types_uboot) class - defines additional image types specifically for the U-Boot bootloader. + 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. + + +
@@ -2112,369 +2495,6 @@
-
-<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>