summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/classes.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/classes.rst')
-rw-r--r--documentation/ref-manual/classes.rst74
1 files changed, 37 insertions, 37 deletions
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 2314added7..09878c480f 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -50,7 +50,7 @@ splitting out of debug symbols during packaging).
50 ``do_package_write_*`` tasks to 50 ``do_package_write_*`` tasks to
51 have different signatures for the machines with different tunings. 51 have different signatures for the machines with different tunings.
52 Additionally, unnecessary rebuilds occur every time an image for a 52 Additionally, unnecessary rebuilds occur every time an image for a
53 different ``MACHINE`` is built even when the recipe never changes. 53 different :term:`MACHINE` is built even when the recipe never changes.
54 54
55By default, all recipes inherit the :ref:`base <ref-classes-base>` and 55By default, all recipes inherit the :ref:`base <ref-classes-base>` and
56:ref:`package <ref-classes-package>` classes, which enable 56:ref:`package <ref-classes-package>` classes, which enable
@@ -110,7 +110,7 @@ It's useful to have some idea of how the tasks defined by the
110- :ref:`ref-tasks-configure` - Regenerates the 110- :ref:`ref-tasks-configure` - Regenerates the
111 configure script (using ``autoreconf``) and then launches it with a 111 configure script (using ``autoreconf``) and then launches it with a
112 standard set of arguments used during cross-compilation. You can pass 112 standard set of arguments used during cross-compilation. You can pass
113 additional parameters to ``configure`` through the ``EXTRA_OECONF`` 113 additional parameters to ``configure`` through the :term:`EXTRA_OECONF`
114 or :term:`PACKAGECONFIG_CONFARGS` 114 or :term:`PACKAGECONFIG_CONFARGS`
115 variables. 115 variables.
116 116
@@ -168,7 +168,7 @@ example use for this class.
168 the "subpath" parameter limits the checkout to a specific subpath 168 the "subpath" parameter limits the checkout to a specific subpath
169 of the tree. Here is an example where ``${BP}`` is used so that the files 169 of the tree. Here is an example where ``${BP}`` is used so that the files
170 are extracted into the subdirectory expected by the default value of 170 are extracted into the subdirectory expected by the default value of
171 ``S``:: 171 :term:`S`::
172 172
173 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" 173 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
174 174
@@ -256,7 +256,7 @@ Collecting build statistics is enabled by default through the
256:term:`USER_CLASSES` variable from your 256:term:`USER_CLASSES` variable from your
257``local.conf`` file. Consequently, you do not have to do anything to 257``local.conf`` file. Consequently, you do not have to do anything to
258enable the class. However, if you want to disable the class, simply 258enable the class. However, if you want to disable the class, simply
259remove "buildstats" from the ``USER_CLASSES`` list. 259remove "buildstats" from the :term:`USER_CLASSES` list.
260 260
261.. _ref-classes-buildstats-summary: 261.. _ref-classes-buildstats-summary:
262 262
@@ -433,7 +433,7 @@ deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
433add the task at the appropriate place, which is usually after 433add the task at the appropriate place, which is usually after
434:ref:`ref-tasks-compile` or 434:ref:`ref-tasks-compile` or
435:ref:`ref-tasks-install`. The class then takes care of 435:ref:`ref-tasks-install`. The class then takes care of
436staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. 436staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
437 437
438.. _ref-classes-devshell: 438.. _ref-classes-devshell:
439 439
@@ -474,7 +474,7 @@ The class
474currently only supports creating a development variant of the target 474currently only supports creating a development variant of the target
475recipe, not ``native`` or ``nativesdk`` variants. 475recipe, not ``native`` or ``nativesdk`` variants.
476 476
477The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides 477The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides
478support for ``native`` and ``nativesdk`` variants. Consequently, this 478support for ``native`` and ``nativesdk`` variants. Consequently, this
479functionality can be added in a future release. 479functionality can be added in a future release.
480 480
@@ -519,13 +519,13 @@ and to build it, respectively. When your recipe inherits the
519``externalsrc`` class, you use the 519``externalsrc`` class, you use the
520:term:`EXTERNALSRC` and 520:term:`EXTERNALSRC` and
521:term:`EXTERNALSRC_BUILD` variables to 521:term:`EXTERNALSRC_BUILD` variables to
522ultimately define ``S`` and ``B``. 522ultimately define :term:`S` and :term:`B`.
523 523
524By default, this class expects the source code to support recipe builds 524By default, this class expects the source code to support recipe builds
525that use the :term:`B` variable to point to the directory in 525that use the :term:`B` variable to point to the directory in
526which the OpenEmbedded build system places the generated objects built 526which the OpenEmbedded build system places the generated objects built
527from the recipes. By default, the ``B`` directory is set to the 527from the recipes. By default, the :term:`B` directory is set to the
528following, which is separate from the source directory (``S``):: 528following, which is separate from the source directory (:term:`S`)::
529 529
530 ${WORKDIR}/${BPN}/{PV}/ 530 ${WORKDIR}/${BPN}/{PV}/
531 531
@@ -689,8 +689,8 @@ introspection. This functionality is only enabled if the
689.. note:: 689.. note::
690 690
691 This functionality is backfilled by default and, if not applicable, 691 This functionality is backfilled by default and, if not applicable,
692 should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or 692 should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
693 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively. 693 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
694 694
695.. _ref-classes-grub-efi: 695.. _ref-classes-grub-efi:
696 696
@@ -838,7 +838,7 @@ using an empty :term:`PARALLEL_MAKE` variable.
838Inheriting the ``icecc`` class changes all sstate signatures. 838Inheriting the ``icecc`` class changes all sstate signatures.
839Consequently, if a development team has a dedicated build system that 839Consequently, if a development team has a dedicated build system that
840populates :term:`SSTATE_MIRRORS` and they want to 840populates :term:`SSTATE_MIRRORS` and they want to
841reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build 841reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
842system need to either inherit the ``icecc`` class or nobody should. 842system need to either inherit the ``icecc`` class or nobody should.
843 843
844At the distribution level, you can inherit the ``icecc`` class to be 844At the distribution level, you can inherit the ``icecc`` class to be
@@ -866,10 +866,10 @@ First, the root filesystem is created from packages using one of the
866``rootfs*.bbclass`` files (depending on the package format used) and 866``rootfs*.bbclass`` files (depending on the package format used) and
867then one or more image files are created. 867then one or more image files are created.
868 868
869- The ``IMAGE_FSTYPES`` variable controls the types of images to 869- The :term:`IMAGE_FSTYPES` variable controls the types of images to
870 generate. 870 generate.
871 871
872- The ``IMAGE_INSTALL`` variable controls the list of packages to 872- The :term:`IMAGE_INSTALL` variable controls the list of packages to
873 install into the image. 873 install into the image.
874 874
875For information on customizing images, see the 875For information on customizing images, see the
@@ -916,7 +916,7 @@ The ``image_types`` class also handles conversion and compression of images.
916.. note:: 916.. note::
917 917
918 To build a VMware VMDK image, you need to add "wic.vmdk" to 918 To build a VMware VMDK image, you need to add "wic.vmdk" to
919 ``IMAGE_FSTYPES``. This would also be similar for Virtual Box Virtual Disk 919 :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk
920 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. 920 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
921 921
922.. _ref-classes-image-live: 922.. _ref-classes-image-live:
@@ -994,7 +994,7 @@ Please keep in mind that the QA checks
994are meant to detect real or potential problems in the packaged 994are meant to detect real or potential problems in the packaged
995output. So exercise caution when disabling these checks. 995output. So exercise caution when disabling these checks.
996 996
997Here are the tests you can list with the ``WARN_QA`` and 997Here are the tests you can list with the :term:`WARN_QA` and
998``ERROR_QA`` variables: 998``ERROR_QA`` variables:
999 999
1000- ``already-stripped:`` Checks that produced binaries have not 1000- ``already-stripped:`` Checks that produced binaries have not
@@ -1127,13 +1127,13 @@ Here are the tests you can list with the ``WARN_QA`` and
1127 1127
1128 PACKAGECONFIG[foo] = "..." 1128 PACKAGECONFIG[foo] = "..."
1129 1129
1130- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` 1130- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
1131 file containing these paths is incorrect since ``libtool`` adds the 1131 file containing these paths is incorrect since ``libtool`` adds the
1132 correct sysroot prefix when using the files automatically itself. 1132 correct sysroot prefix when using the files automatically itself.
1133 1133
1134- ``ldflags:`` Ensures that the binaries were linked with the 1134- ``ldflags:`` Ensures that the binaries were linked with the
1135 :term:`LDFLAGS` options provided by the build system. 1135 :term:`LDFLAGS` options provided by the build system.
1136 If this test fails, check that the ``LDFLAGS`` variable is being 1136 If this test fails, check that the :term:`LDFLAGS` variable is being
1137 passed to the linker command. 1137 passed to the linker command.
1138 1138
1139- ``libdir:`` Checks for libraries being installed into incorrect 1139- ``libdir:`` Checks for libraries being installed into incorrect
@@ -1173,7 +1173,7 @@ Here are the tests you can list with the ``WARN_QA`` and
1173 invalid characters (i.e. characters other than 0-9, a-z, ., +, and 1173 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1174 -). 1174 -).
1175 1175
1176- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is 1176- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
1177 undefined during :ref:`ref-tasks-package`. 1177 undefined during :ref:`ref-tasks-package`.
1178 1178
1179- ``pkgvarcheck:`` Checks through the variables 1179- ``pkgvarcheck:`` Checks through the variables
@@ -1193,8 +1193,8 @@ Here are the tests you can list with the ``WARN_QA`` and
1193- ``pn-overrides:`` Checks that a recipe does not have a name 1193- ``pn-overrides:`` Checks that a recipe does not have a name
1194 (:term:`PN`) value that appears in 1194 (:term:`PN`) value that appears in
1195 :term:`OVERRIDES`. If a recipe is named such that 1195 :term:`OVERRIDES`. If a recipe is named such that
1196 its ``PN`` value matches something already in ``OVERRIDES`` (e.g. 1196 its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
1197 ``PN`` happens to be the same as :term:`MACHINE` or 1197 :term:`PN` happens to be the same as :term:`MACHINE` or
1198 :term:`DISTRO`), it can have unexpected consequences. 1198 :term:`DISTRO`), it can have unexpected consequences.
1199 For example, assignments such as ``FILES_${PN} = "xyz"`` effectively 1199 For example, assignments such as ``FILES_${PN} = "xyz"`` effectively
1200 turn into ``FILES = "xyz"``. 1200 turn into ``FILES = "xyz"``.
@@ -1725,7 +1725,7 @@ To use this class, inherit it globally and specify
1725 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" 1725 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1726 1726
1727You can specify only a single URL 1727You can specify only a single URL
1728in ``SOURCE_MIRROR_URL``. 1728in :term:`SOURCE_MIRROR_URL`.
1729 1729
1730.. _ref-classes-package: 1730.. _ref-classes-package:
1731 1731
@@ -1749,7 +1749,7 @@ package-specific classes:
1749 use this class. 1749 use this class.
1750 1750
1751You can control the list of resulting package formats by using the 1751You can control the list of resulting package formats by using the
1752``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` 1752:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
1753configuration file, which is located in the :term:`Build Directory`. 1753configuration file, which is located in the :term:`Build Directory`.
1754When defining the variable, you can 1754When defining the variable, you can
1755specify one or more package types. Since images are generated from 1755specify one or more package types. Since images are generated from
@@ -1770,7 +1770,7 @@ the same or similar package. This comparison takes into account a
1770complete build of the package with all dependencies previously built. 1770complete build of the package with all dependencies previously built.
1771The reason for this discrepancy is because the RPM package manager 1771The reason for this discrepancy is because the RPM package manager
1772creates and processes more :term:`Metadata` than the IPK package 1772creates and processes more :term:`Metadata` than the IPK package
1773manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to 1773manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to
1774"package_ipk" if you are building smaller systems. 1774"package_ipk" if you are building smaller systems.
1775 1775
1776Before making your package manager decision, however, you should 1776Before making your package manager decision, however, you should
@@ -1852,7 +1852,7 @@ variable in the ``local.conf`` file.
1852.. note:: 1852.. note::
1853 1853
1854 You cannot specify the ``package_tar`` class first using the 1854 You cannot specify the ``package_tar`` class first using the
1855 ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm`` 1855 :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
1856 file formats for your image or SDK. 1856 file formats for your image or SDK.
1857 1857
1858.. _ref-classes-packagedata: 1858.. _ref-classes-packagedata:
@@ -1874,7 +1874,7 @@ This class is enabled by default because it is inherited by the
1874======================== 1874========================
1875 1875
1876The ``packagegroup`` class sets default values appropriate for package 1876The ``packagegroup`` class sets default values appropriate for package
1877group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and 1877group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and
1878so forth). It is highly recommended that all package group recipes 1878so forth). It is highly recommended that all package group recipes
1879inherit this class. 1879inherit this class.
1880 1880
@@ -2193,7 +2193,7 @@ modifying and building source code out of the work directory for a
2193recipe, enabling ``rm_work`` will potentially result in your changes to 2193recipe, enabling ``rm_work`` will potentially result in your changes to
2194the source being lost. To exclude some recipes from having their work 2194the source being lost. To exclude some recipes from having their work
2195directories deleted by ``rm_work``, you can add the names of the recipe 2195directories deleted by ``rm_work``, you can add the names of the recipe
2196or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which 2196or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which
2197can also be set in your ``local.conf`` file. Here is an example:: 2197can also be set in your ``local.conf`` file. Here is an example::
2198 2198
2199 RM_WORK_EXCLUDE += "busybox glibc" 2199 RM_WORK_EXCLUDE += "busybox glibc"
@@ -2308,11 +2308,11 @@ results so these tests can be skipped over but still make the correct
2308values available. The ``meta/site directory`` contains test results 2308values available. The ``meta/site directory`` contains test results
2309sorted into different categories such as architecture, endianness, and 2309sorted into different categories such as architecture, endianness, and
2310the ``libc`` used. Site information provides a list of files containing 2310the ``libc`` used. Site information provides a list of files containing
2311data relevant to the current build in the ``CONFIG_SITE`` variable that 2311data relevant to the current build in the :term:`CONFIG_SITE` variable that
2312Autotools automatically picks up. 2312Autotools automatically picks up.
2313 2313
2314The class also provides variables like ``SITEINFO_ENDIANNESS`` and 2314The class also provides variables like :term:`SITEINFO_ENDIANNESS` and
2315``SITEINFO_BITS`` that can be used elsewhere in the metadata. 2315:term:`SITEINFO_BITS` that can be used elsewhere in the metadata.
2316 2316
2317.. _ref-classes-sstate: 2317.. _ref-classes-sstate:
2318 2318
@@ -2363,7 +2363,7 @@ stages:
2363 .. note:: 2363 .. note::
2364 2364
2365 Additionally, a recipe can customize the files further by 2365 Additionally, a recipe can customize the files further by
2366 declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS`` 2366 declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS`
2367 variable. 2367 variable.
2368 2368
2369 A shared state (sstate) object is built from these files and the 2369 A shared state (sstate) object is built from these files and the
@@ -2405,11 +2405,11 @@ stages:
2405 recommended for general use, the files do allow some issues such 2405 recommended for general use, the files do allow some issues such
2406 as user creation and module indexes to be addressed. 2406 as user creation and module indexes to be addressed.
2407 2407
2408 Because recipes can have other dependencies outside of ``DEPENDS`` 2408 Because recipes can have other dependencies outside of :term:`DEPENDS`
2409 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), 2409 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
2410 the sysroot creation function ``extend_recipe_sysroot`` is also added 2410 the sysroot creation function ``extend_recipe_sysroot`` is also added
2411 as a pre-function for those tasks whose dependencies are not through 2411 as a pre-function for those tasks whose dependencies are not through
2412 ``DEPENDS`` but operate similarly. 2412 :term:`DEPENDS` but operate similarly.
2413 2413
2414 When installing dependencies into the sysroot, the code traverses the 2414 When installing dependencies into the sysroot, the code traverses the
2415 dependency graph and processes dependencies in exactly the same way 2415 dependency graph and processes dependencies in exactly the same way
@@ -2735,8 +2735,8 @@ initialization script on behalf of the package. The OpenEmbedded build
2735system takes care of details such as making sure the script is stopped 2735system takes care of details such as making sure the script is stopped
2736before a package is removed and started when the package is installed. 2736before a package is removed and started when the package is installed.
2737 2737
2738Three variables control this class: ``INITSCRIPT_PACKAGES``, 2738Three variables control this class: :term:`INITSCRIPT_PACKAGES`,
2739``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links 2739:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links
2740for details. 2740for details.
2741 2741
2742.. _ref-classes-useradd: 2742.. _ref-classes-useradd:
@@ -2790,9 +2790,9 @@ additional information.
2790.. note:: 2790.. note::
2791 2791
2792 You do not use the ``useradd-staticids`` class directly. You either enable 2792 You do not use the ``useradd-staticids`` class directly. You either enable
2793 or disable the class by setting the ``USERADDEXTENSION`` variable. If you 2793 or disable the class by setting the :term:`USERADDEXTENSION` variable. If you
2794 enable or disable the class in a configured system, :term:`TMPDIR` might 2794 enable or disable the class in a configured system, :term:`TMPDIR` might
2795 contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR`` 2795 contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR`
2796 directory will correct this condition. 2796 directory will correct this condition.
2797 2797
2798.. _ref-classes-utility-tasks: 2798.. _ref-classes-utility-tasks: