diff options
Diffstat (limited to 'documentation/ref-manual/classes.rst')
-rw-r--r-- | documentation/ref-manual/classes.rst | 74 |
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 | ||
55 | By default, all recipes inherit the :ref:`base <ref-classes-base>` and | 55 | By 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 |
258 | enable the class. However, if you want to disable the class, simply | 258 | enable the class. However, if you want to disable the class, simply |
259 | remove "buildstats" from the ``USER_CLASSES`` list. | 259 | remove "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 | |||
433 | add the task at the appropriate place, which is usually after | 433 | add 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 |
436 | staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. | 436 | staging 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 | |||
474 | currently only supports creating a development variant of the target | 474 | currently only supports creating a development variant of the target |
475 | recipe, not ``native`` or ``nativesdk`` variants. | 475 | recipe, not ``native`` or ``nativesdk`` variants. |
476 | 476 | ||
477 | The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides | 477 | The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides |
478 | support for ``native`` and ``nativesdk`` variants. Consequently, this | 478 | support for ``native`` and ``nativesdk`` variants. Consequently, this |
479 | functionality can be added in a future release. | 479 | functionality 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 |
522 | ultimately define ``S`` and ``B``. | 522 | ultimately define :term:`S` and :term:`B`. |
523 | 523 | ||
524 | By default, this class expects the source code to support recipe builds | 524 | By default, this class expects the source code to support recipe builds |
525 | that use the :term:`B` variable to point to the directory in | 525 | that use the :term:`B` variable to point to the directory in |
526 | which the OpenEmbedded build system places the generated objects built | 526 | which the OpenEmbedded build system places the generated objects built |
527 | from the recipes. By default, the ``B`` directory is set to the | 527 | from the recipes. By default, the :term:`B` directory is set to the |
528 | following, which is separate from the source directory (``S``):: | 528 | following, 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. | |||
838 | Inheriting the ``icecc`` class changes all sstate signatures. | 838 | Inheriting the ``icecc`` class changes all sstate signatures. |
839 | Consequently, if a development team has a dedicated build system that | 839 | Consequently, if a development team has a dedicated build system that |
840 | populates :term:`SSTATE_MIRRORS` and they want to | 840 | populates :term:`SSTATE_MIRRORS` and they want to |
841 | reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build | 841 | reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build |
842 | system need to either inherit the ``icecc`` class or nobody should. | 842 | system need to either inherit the ``icecc`` class or nobody should. |
843 | 843 | ||
844 | At the distribution level, you can inherit the ``icecc`` class to be | 844 | At 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 |
867 | then one or more image files are created. | 867 | then 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 | ||
875 | For information on customizing images, see the | 875 | For 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 | |||
994 | are meant to detect real or potential problems in the packaged | 994 | are meant to detect real or potential problems in the packaged |
995 | output. So exercise caution when disabling these checks. | 995 | output. So exercise caution when disabling these checks. |
996 | 996 | ||
997 | Here are the tests you can list with the ``WARN_QA`` and | 997 | Here 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 | ||
1727 | You can specify only a single URL | 1727 | You can specify only a single URL |
1728 | in ``SOURCE_MIRROR_URL``. | 1728 | in :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 | ||
1751 | You can control the list of resulting package formats by using the | 1751 | You 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`` |
1753 | configuration file, which is located in the :term:`Build Directory`. | 1753 | configuration file, which is located in the :term:`Build Directory`. |
1754 | When defining the variable, you can | 1754 | When defining the variable, you can |
1755 | specify one or more package types. Since images are generated from | 1755 | specify 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 | |||
1770 | complete build of the package with all dependencies previously built. | 1770 | complete build of the package with all dependencies previously built. |
1771 | The reason for this discrepancy is because the RPM package manager | 1771 | The reason for this discrepancy is because the RPM package manager |
1772 | creates and processes more :term:`Metadata` than the IPK package | 1772 | creates and processes more :term:`Metadata` than the IPK package |
1773 | manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to | 1773 | manager. 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 | ||
1776 | Before making your package manager decision, however, you should | 1776 | Before 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 | ||
1876 | The ``packagegroup`` class sets default values appropriate for package | 1876 | The ``packagegroup`` class sets default values appropriate for package |
1877 | group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and | 1877 | group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and |
1878 | so forth). It is highly recommended that all package group recipes | 1878 | so forth). It is highly recommended that all package group recipes |
1879 | inherit this class. | 1879 | inherit this class. |
1880 | 1880 | ||
@@ -2193,7 +2193,7 @@ modifying and building source code out of the work directory for a | |||
2193 | recipe, enabling ``rm_work`` will potentially result in your changes to | 2193 | recipe, enabling ``rm_work`` will potentially result in your changes to |
2194 | the source being lost. To exclude some recipes from having their work | 2194 | the source being lost. To exclude some recipes from having their work |
2195 | directories deleted by ``rm_work``, you can add the names of the recipe | 2195 | directories deleted by ``rm_work``, you can add the names of the recipe |
2196 | or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which | 2196 | or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which |
2197 | can also be set in your ``local.conf`` file. Here is an example:: | 2197 | can 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 | |||
2308 | values available. The ``meta/site directory`` contains test results | 2308 | values available. The ``meta/site directory`` contains test results |
2309 | sorted into different categories such as architecture, endianness, and | 2309 | sorted into different categories such as architecture, endianness, and |
2310 | the ``libc`` used. Site information provides a list of files containing | 2310 | the ``libc`` used. Site information provides a list of files containing |
2311 | data relevant to the current build in the ``CONFIG_SITE`` variable that | 2311 | data relevant to the current build in the :term:`CONFIG_SITE` variable that |
2312 | Autotools automatically picks up. | 2312 | Autotools automatically picks up. |
2313 | 2313 | ||
2314 | The class also provides variables like ``SITEINFO_ENDIANNESS`` and | 2314 | The 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 | |||
2735 | system takes care of details such as making sure the script is stopped | 2735 | system takes care of details such as making sure the script is stopped |
2736 | before a package is removed and started when the package is installed. | 2736 | before a package is removed and started when the package is installed. |
2737 | 2737 | ||
2738 | Three variables control this class: ``INITSCRIPT_PACKAGES``, | 2738 | Three 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 |
2740 | for details. | 2740 | for 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: |