diff options
author | Quentin Schulz <foss@0leil.net> | 2020-10-05 20:37:23 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-01-04 10:55:01 +0000 |
commit | e8feec005be8b25b7e7d865e1d9cdbe57b49409a (patch) | |
tree | 1cc1c8ac5034b2a8219e2161265d5575db02b3a2 /documentation/ref-manual/ref-classes.rst | |
parent | 017be0a95668577ff8bf2c5462ed50318ed785db (diff) | |
download | poky-e8feec005be8b25b7e7d865e1d9cdbe57b49409a.tar.gz |
docs: ref-manual: indentation, links and highlights fixes
Reviewed-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
(From yocto-docs rev: 27f6527882d22f20641882018ca5b8a7a30092ae)
Signed-off-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
(cherry picked from commit f5688a74cd9d100dee270edb9a33c02015cfabda)
Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-classes.rst')
-rw-r--r-- | documentation/ref-manual/ref-classes.rst | 143 |
1 files changed, 45 insertions, 98 deletions
diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst index 69bae0eceb..564005b161 100644 --- a/documentation/ref-manual/ref-classes.rst +++ b/documentation/ref-manual/ref-classes.rst | |||
@@ -47,7 +47,7 @@ splitting out of debug symbols during packaging). | |||
47 | even if the recipes do not produce architecture-specific output. | 47 | even if the recipes do not produce architecture-specific output. |
48 | 48 | ||
49 | Configuring such recipes for all architectures causes the | 49 | Configuring such recipes for all architectures causes the |
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 ``MACHINE`` is built even when the recipe never changes. |
@@ -164,24 +164,18 @@ example use for this class. | |||
164 | 164 | ||
165 | For RPMs and other packages that do not contain a subdirectory, you | 165 | For RPMs and other packages that do not contain a subdirectory, you |
166 | should specify an appropriate fetcher parameter to point to the | 166 | should specify an appropriate fetcher parameter to point to the |
167 | subdirectory. For example, if BitBake is using the Git fetcher ( | 167 | subdirectory. For example, if BitBake is using the Git fetcher (``git://``), |
168 | git:// | 168 | the "subpath" parameter limits the checkout to a specific subpath |
169 | ), 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 |
170 | of the tree. Here is an example where | 170 | are extracted into the subdirectory expected by the default value of |
171 | ${BP} | 171 | ``S``: |
172 | is used so that the files are extracted into the subdirectory | ||
173 | expected by the default value of | ||
174 | S | ||
175 | : | ||
176 | :: | 172 | :: |
177 | 173 | ||
178 | SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" | 174 | SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" |
179 | 175 | ||
180 | 176 | ||
181 | See the " | 177 | See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for |
182 | Fetchers | 178 | more information on supported BitBake Fetchers. |
183 | " section in the BitBake User Manual for more information on | ||
184 | supported BitBake Fetchers. | ||
185 | 179 | ||
186 | .. _ref-classes-binconfig: | 180 | .. _ref-classes-binconfig: |
187 | 181 | ||
@@ -736,11 +730,8 @@ introspection. This functionality is only enabled if the | |||
736 | .. note:: | 730 | .. note:: |
737 | 731 | ||
738 | This functionality is backfilled by default and, if not applicable, | 732 | This functionality is backfilled by default and, if not applicable, |
739 | should be disabled through | 733 | should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or |
740 | DISTRO_FEATURES_BACKFILL_CONSIDERED | 734 | ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively. |
741 | or | ||
742 | MACHINE_FEATURES_BACKFILL_CONSIDERED | ||
743 | , respectively. | ||
744 | 735 | ||
745 | .. _ref-classes-grub-efi: | 736 | .. _ref-classes-grub-efi: |
746 | 737 | ||
@@ -969,9 +960,8 @@ The ``image_types`` class also handles conversion and compression of images. | |||
969 | .. note:: | 960 | .. note:: |
970 | 961 | ||
971 | To build a VMware VMDK image, you need to add "wic.vmdk" to | 962 | To build a VMware VMDK image, you need to add "wic.vmdk" to |
972 | IMAGE_FSTYPES | 963 | ``IMAGE_FSTYPES``. This would also be similar for Virtual Box Virtual Disk |
973 | . This would also be similar for Virtual Box Virtual Disk Image | 964 | Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. |
974 | ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. | ||
975 | 965 | ||
976 | .. _ref-classes-image-live: | 966 | .. _ref-classes-image-live: |
977 | 967 | ||
@@ -1032,9 +1022,8 @@ You can configure the sanity checks so that specific test failures | |||
1032 | either raise a warning or an error message. Typically, failures for new | 1022 | either raise a warning or an error message. Typically, failures for new |
1033 | tests generate a warning. Subsequent failures for the same test would | 1023 | tests generate a warning. Subsequent failures for the same test would |
1034 | then generate an error message once the metadata is in a known and good | 1024 | then generate an error message once the metadata is in a known and good |
1035 | condition. See the "`QA Error and Warning Messages <#ref-qa-checks>`__" | 1025 | condition. See the ":doc:`ref-qa-checks`" Chapter for a list of all the warning |
1036 | Chapter for a list of all the warning and error messages you might | 1026 | and error messages you might encounter using a default configuration. |
1037 | encounter using a default configuration. | ||
1038 | 1027 | ||
1039 | Use the :term:`WARN_QA` and | 1028 | Use the :term:`WARN_QA` and |
1040 | :term:`ERROR_QA` variables to control the behavior of | 1029 | :term:`ERROR_QA` variables to control the behavior of |
@@ -1275,9 +1264,9 @@ The following list shows the tests you can list with the ``WARN_QA`` and | |||
1275 | 1264 | ||
1276 | - ``textrel:`` Checks for ELF binaries that contain relocations in | 1265 | - ``textrel:`` Checks for ELF binaries that contain relocations in |
1277 | their ``.text`` sections, which can result in a performance impact at | 1266 | their ``.text`` sections, which can result in a performance impact at |
1278 | runtime. See the explanation for the | 1267 | runtime. See the explanation for the ``ELF binary`` message in |
1279 | ```ELF binary`` <#qa-issue-textrel>`__ message for more information | 1268 | ":doc:`ref-qa-checks`" for more information regarding runtime performance |
1280 | regarding runtime performance issues. | 1269 | issues. |
1281 | 1270 | ||
1282 | - ``unlisted-pkg-lics:`` Checks that all declared licenses applying | 1271 | - ``unlisted-pkg-lics:`` Checks that all declared licenses applying |
1283 | for a package are also declared on the recipe level (i.e. any license | 1272 | for a package are also declared on the recipe level (i.e. any license |
@@ -1627,8 +1616,8 @@ section in the Yocto Project Development Tasks Manual. | |||
1627 | ================== | 1616 | ================== |
1628 | 1617 | ||
1629 | The ``native`` class provides common functionality for recipes that | 1618 | The ``native`` class provides common functionality for recipes that |
1630 | build tools to run on the `build host <#hardware-build-system-term>`__ | 1619 | build tools to run on the :term:`Build Host` (i.e. tools that use the compiler |
1631 | (i.e. tools that use the compiler or other tools from the build host). | 1620 | or other tools from the build host). |
1632 | 1621 | ||
1633 | You can create a recipe that builds tools that run natively on the host | 1622 | You can create a recipe that builds tools that run natively on the host |
1634 | a couple different ways: | 1623 | a couple different ways: |
@@ -1726,8 +1715,7 @@ package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. | |||
1726 | 1715 | ||
1727 | .. note:: | 1716 | .. note:: |
1728 | 1717 | ||
1729 | Currently, recipes inheriting this class must use the | 1718 | Currently, recipes inheriting this class must use the ``npm://`` |
1730 | npm:// | ||
1731 | fetcher to have dependencies fetched and packaged automatically. | 1719 | fetcher to have dependencies fetched and packaged automatically. |
1732 | 1720 | ||
1733 | For information on how to create NPM packages, see the | 1721 | For information on how to create NPM packages, see the |
@@ -1831,9 +1819,9 @@ consider some further things about using RPM: | |||
1831 | You can find additional information on the effects of the package class | 1819 | You can find additional information on the effects of the package class |
1832 | at these two Yocto Project mailing list links: | 1820 | at these two Yocto Project mailing list links: |
1833 | 1821 | ||
1834 | - https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html | 1822 | - :yocto_lists:`/pipermail/poky/2011-May/006362.html` |
1835 | 1823 | ||
1836 | - https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html | 1824 | - :yocto_lists:`/pipermail/poky/2011-May/006363.html` |
1837 | 1825 | ||
1838 | .. _ref-classes-package_deb: | 1826 | .. _ref-classes-package_deb: |
1839 | 1827 | ||
@@ -1892,16 +1880,8 @@ variable in the ``local.conf`` file. | |||
1892 | 1880 | ||
1893 | .. note:: | 1881 | .. note:: |
1894 | 1882 | ||
1895 | You cannot specify the | 1883 | You cannot specify the ``package_tar`` class first using the |
1896 | package_tar | 1884 | ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm`` |
1897 | class first using the | ||
1898 | PACKAGE_CLASSES | ||
1899 | variable. You must use | ||
1900 | .deb | ||
1901 | , | ||
1902 | .ipk | ||
1903 | , or | ||
1904 | .rpm | ||
1905 | file formats for your image or SDK. | 1885 | file formats for your image or SDK. |
1906 | 1886 | ||
1907 | .. _ref-classes-packagedata: | 1887 | .. _ref-classes-packagedata: |
@@ -2066,9 +2046,7 @@ The ``prexport`` class provides functionality for exporting | |||
2066 | .. note:: | 2046 | .. note:: |
2067 | 2047 | ||
2068 | This class is not intended to be used directly. Rather, it is enabled | 2048 | This class is not intended to be used directly. Rather, it is enabled |
2069 | when using " | 2049 | when using "``bitbake-prserv-tool export``". |
2070 | bitbake-prserv-tool export | ||
2071 | ". | ||
2072 | 2050 | ||
2073 | .. _ref-classes-primport: | 2051 | .. _ref-classes-primport: |
2074 | 2052 | ||
@@ -2081,9 +2059,7 @@ The ``primport`` class provides functionality for importing | |||
2081 | .. note:: | 2059 | .. note:: |
2082 | 2060 | ||
2083 | This class is not intended to be used directly. Rather, it is enabled | 2061 | This class is not intended to be used directly. Rather, it is enabled |
2084 | when using " | 2062 | when using "``bitbake-prserv-tool import``". |
2085 | bitbake-prserv-tool import | ||
2086 | ". | ||
2087 | 2063 | ||
2088 | .. _ref-classes-prserv: | 2064 | .. _ref-classes-prserv: |
2089 | 2065 | ||
@@ -2202,9 +2178,7 @@ override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: | |||
2202 | 2178 | ||
2203 | .. note:: | 2179 | .. note:: |
2204 | 2180 | ||
2205 | The | 2181 | The ``remove-libtool`` class is not enabled by default. |
2206 | remove-libtool | ||
2207 | class is not enabled by default. | ||
2208 | 2182 | ||
2209 | .. _ref-classes-report-error: | 2183 | .. _ref-classes-report-error: |
2210 | 2184 | ||
@@ -2440,13 +2414,12 @@ stages: | |||
2440 | .. note:: | 2414 | .. note:: |
2441 | 2415 | ||
2442 | Additionally, a recipe can customize the files further by | 2416 | Additionally, a recipe can customize the files further by |
2443 | declaring a processing function in the | 2417 | declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS`` |
2444 | SYSROOT_PREPROCESS_FUNCS | ||
2445 | variable. | 2418 | variable. |
2446 | 2419 | ||
2447 | A shared state (sstate) object is built from these files and the | 2420 | A shared state (sstate) object is built from these files and the |
2448 | files are placed into a subdirectory of | 2421 | files are placed into a subdirectory of |
2449 | ```tmp/sysroots-components/`` <#structure-build-tmp-sysroots-components>`__. | 2422 | :ref:`structure-build-tmp-sysroots-components`. |
2450 | The files are scanned for hardcoded paths to the original | 2423 | The files are scanned for hardcoded paths to the original |
2451 | installation location. If the location is found in text files, the | 2424 | installation location. If the location is found in text files, the |
2452 | hardcoded locations are replaced by tokens and a list of the files | 2425 | hardcoded locations are replaced by tokens and a list of the files |
@@ -2595,13 +2568,8 @@ internal class and is not intended to be used directly. | |||
2595 | 2568 | ||
2596 | .. note:: | 2569 | .. note:: |
2597 | 2570 | ||
2598 | The | 2571 | The ``systemd-boot`` class is a result from merging the ``gummiboot`` class |
2599 | systemd-boot | 2572 | used in previous Yocto Project releases with the ``systemd`` project. |
2600 | class is a result from merging the | ||
2601 | gummiboot | ||
2602 | class used in previous Yocto Project releases with the | ||
2603 | systemd | ||
2604 | project. | ||
2605 | 2573 | ||
2606 | Set the :term:`EFI_PROVIDER` variable to | 2574 | Set the :term:`EFI_PROVIDER` variable to |
2607 | "systemd-boot" to use this class. Doing so creates a standalone EFI | 2575 | "systemd-boot" to use this class. Doing so creates a standalone EFI |
@@ -2645,13 +2613,9 @@ steps to set up the environment. | |||
2645 | 2613 | ||
2646 | .. note:: | 2614 | .. note:: |
2647 | 2615 | ||
2648 | Best practices include using | 2616 | Best practices include using :term:`IMAGE_CLASSES` rather than |
2649 | IMAGE_CLASSES | 2617 | :term:`INHERIT` to inherit the ``testimage`` class for automated image |
2650 | rather than | 2618 | testing. |
2651 | INHERIT | ||
2652 | to inherit the | ||
2653 | testimage | ||
2654 | class for automated image testing. | ||
2655 | 2619 | ||
2656 | The tests are commands that run on the target system over ``ssh``. Each | 2620 | The tests are commands that run on the target system over ``ssh``. Each |
2657 | test is written in Python and makes use of the ``unittest`` module. | 2621 | test is written in Python and makes use of the ``unittest`` module. |
@@ -2684,13 +2648,9 @@ using the following: | |||
2684 | 2648 | ||
2685 | .. note:: | 2649 | .. note:: |
2686 | 2650 | ||
2687 | Best practices include using | 2651 | Best practices include using :term:`IMAGE_CLASSES` rather than |
2688 | IMAGE_CLASSES | 2652 | :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK |
2689 | rather than | 2653 | testing. |
2690 | INHERIT | ||
2691 | to inherit the | ||
2692 | testsdk | ||
2693 | class for automated SDK testing. | ||
2694 | 2654 | ||
2695 | .. _ref-classes-texinfo: | 2655 | .. _ref-classes-texinfo: |
2696 | 2656 | ||
@@ -2707,11 +2667,8 @@ host system. | |||
2707 | .. note:: | 2667 | .. note:: |
2708 | 2668 | ||
2709 | If you want to use the Texinfo recipe shipped with the build system, | 2669 | If you want to use the Texinfo recipe shipped with the build system, |
2710 | you can remove "texinfo-native" from | 2670 | you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo |
2711 | ASSUME_PROVIDED | 2671 | from :term:`SANITY_REQUIRED_UTILITIES`. |
2712 | and makeinfo from | ||
2713 | SANITY_REQUIRED_UTILITIES | ||
2714 | . | ||
2715 | 2672 | ||
2716 | .. _ref-classes-tinderclient: | 2673 | .. _ref-classes-tinderclient: |
2717 | 2674 | ||
@@ -2834,10 +2791,8 @@ file. | |||
2834 | 2791 | ||
2835 | .. note:: | 2792 | .. note:: |
2836 | 2793 | ||
2837 | You can use the | 2794 | You can use the ``update-alternatives`` command directly in your recipes. |
2838 | update-alternatives | 2795 | However, this class simplifies things in most cases. |
2839 | command directly in your recipes. However, this class simplifies | ||
2840 | things in most cases. | ||
2841 | 2796 | ||
2842 | .. _ref-classes-update-rc.d: | 2797 | .. _ref-classes-update-rc.d: |
2843 | 2798 | ||
@@ -2903,18 +2858,10 @@ additional information. | |||
2903 | 2858 | ||
2904 | .. note:: | 2859 | .. note:: |
2905 | 2860 | ||
2906 | You do not use the | 2861 | You do not use the ``useradd-staticids`` class directly. You either enable |
2907 | useradd-staticids | 2862 | or disable the class by setting the ``USERADDEXTENSION`` variable. If you |
2908 | class directly. You either enable or disable the class by setting the | 2863 | enable or disable the class in a configured system, :term:`TMPDIR` might |
2909 | USERADDEXTENSION | 2864 | contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR`` |
2910 | variable. If you enable or disable the class in a configured system, | ||
2911 | TMPDIR | ||
2912 | might contain incorrect | ||
2913 | uid | ||
2914 | and | ||
2915 | gid | ||
2916 | values. Deleting the | ||
2917 | TMPDIR | ||
2918 | directory will correct this condition. | 2865 | directory will correct this condition. |
2919 | 2866 | ||
2920 | .. _ref-classes-utility-tasks: | 2867 | .. _ref-classes-utility-tasks: |