diff options
author | Quentin Schulz <foss@0leil.net> | 2021-08-11 22:06:01 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-08-14 12:04:23 +0100 |
commit | 3d93ddf9e8867ca3f331fc9d3f4eb658a2b7810f (patch) | |
tree | 58769f99fa5ac2af2bbff9fe2fc829ee7132023d /documentation/dev-manual/common-tasks.rst | |
parent | ed6482821c1cc04d3cd35f6b30631a4d09b594d1 (diff) | |
download | poky-3d93ddf9e8867ca3f331fc9d3f4eb658a2b7810f.tar.gz |
docs: fix new override syntax migration
Fix bits missed by the migration script.
(From yocto-docs rev: 452e0c5067476fd2ce81f09e6c73da84ced4bbd0)
Signed-off-by: Quentin Schulz <foss@0leil.net>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/common-tasks.rst')
-rw-r--r-- | documentation/dev-manual/common-tasks.rst | 80 |
1 files changed, 40 insertions, 40 deletions
diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index 7dcb8769d8..34e978dde1 100644 --- a/documentation/dev-manual/common-tasks.rst +++ b/documentation/dev-manual/common-tasks.rst | |||
@@ -207,13 +207,13 @@ following list: | |||
207 | To make sure your changes apply only when building machine "one", | 207 | To make sure your changes apply only when building machine "one", |
208 | use a machine override with the :term:`DEPENDS` statement:: | 208 | use a machine override with the :term:`DEPENDS` statement:: |
209 | 209 | ||
210 | DEPENDS_one = "foo" | 210 | DEPENDS:one = "foo" |
211 | 211 | ||
212 | You should follow the same strategy when using ``_append`` | 212 | You should follow the same strategy when using ``:append`` |
213 | and ``_prepend`` operations:: | 213 | and ``:prepend`` operations:: |
214 | 214 | ||
215 | DEPENDS:append_one = " foo" | 215 | DEPENDS:append:one = " foo" |
216 | DEPENDS:prepend_one = "foo " | 216 | DEPENDS:prepend:one = "foo " |
217 | 217 | ||
218 | As an actual example, here's a | 218 | As an actual example, here's a |
219 | snippet from the generic kernel include file ``linux-yocto.inc``, | 219 | snippet from the generic kernel include file ``linux-yocto.inc``, |
@@ -236,8 +236,8 @@ following list: | |||
236 | 236 | ||
237 | .. note:: | 237 | .. note:: |
238 | 238 | ||
239 | Avoiding "+=" and "=+" and using machine-specific ``_append`` | 239 | Avoiding "+=" and "=+" and using machine-specific ``:append`` |
240 | and ``_prepend`` operations is recommended as well. | 240 | and ``:prepend`` operations is recommended as well. |
241 | 241 | ||
242 | - *Place Machine-Specific Files in Machine-Specific Locations:* When | 242 | - *Place Machine-Specific Files in Machine-Specific Locations:* When |
243 | you have a base recipe, such as ``base-files.bb``, that contains a | 243 | you have a base recipe, such as ``base-files.bb``, that contains a |
@@ -537,7 +537,7 @@ important as it ensures that items in the list remain colon-separated. | |||
537 | .. note:: | 537 | .. note:: |
538 | 538 | ||
539 | BitBake automatically defines the :term:`THISDIR` variable. You should | 539 | BitBake automatically defines the :term:`THISDIR` variable. You should |
540 | never set this variable yourself. Using "_prepend" as part of the | 540 | never set this variable yourself. Using ":prepend" as part of the |
541 | :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other | 541 | :term:`FILESEXTRAPATHS` ensures your path will be searched prior to other |
542 | paths in the final list. | 542 | paths in the final list. |
543 | 543 | ||
@@ -830,23 +830,23 @@ variable changes are in effect for every build and consequently affect | |||
830 | all images, which might not be what you require. | 830 | all images, which might not be what you require. |
831 | 831 | ||
832 | To add a package to your image using the local configuration file, use | 832 | To add a package to your image using the local configuration file, use |
833 | the :term:`IMAGE_INSTALL` variable with the ``_append`` operator:: | 833 | the :term:`IMAGE_INSTALL` variable with the ``:append`` operator:: |
834 | 834 | ||
835 | IMAGE_INSTALL:append = " strace" | 835 | IMAGE_INSTALL:append = " strace" |
836 | 836 | ||
837 | Use of the syntax is important - | 837 | Use of the syntax is important - |
838 | specifically, the space between the quote and the package name, which is | 838 | specifically, the space between the quote and the package name, which is |
839 | ``strace`` in this example. This space is required since the ``_append`` | 839 | ``strace`` in this example. This space is required since the ``:append`` |
840 | operator does not add the space. | 840 | operator does not add the space. |
841 | 841 | ||
842 | Furthermore, you must use ``_append`` instead of the ``+=`` operator if | 842 | Furthermore, you must use ``:append`` instead of the ``+=`` operator if |
843 | you want to avoid ordering issues. The reason for this is because doing | 843 | you want to avoid ordering issues. The reason for this is because doing |
844 | so unconditionally appends to the variable and avoids ordering problems | 844 | so unconditionally appends to the variable and avoids ordering problems |
845 | due to the variable being set in image recipes and ``.bbclass`` files | 845 | due to the variable being set in image recipes and ``.bbclass`` files |
846 | with operators like ``?=``. Using ``_append`` ensures the operation | 846 | with operators like ``?=``. Using ``:append`` ensures the operation |
847 | takes effect. | 847 | takes effect. |
848 | 848 | ||
849 | As shown in its simplest use, ``IMAGE_INSTALL_append`` affects all | 849 | As shown in its simplest use, ``IMAGE_INSTALL:append`` affects all |
850 | images. It is possible to extend the syntax so that the variable applies | 850 | images. It is possible to extend the syntax so that the variable applies |
851 | to a specific image only. Here is an example:: | 851 | to a specific image only. Here is an example:: |
852 | 852 | ||
@@ -1544,8 +1544,8 @@ package for a recipe has the same name as the recipe, and the recipe's | |||
1544 | name can be found through the | 1544 | name can be found through the |
1545 | ``${``\ :term:`PN`\ ``}`` variable, then | 1545 | ``${``\ :term:`PN`\ ``}`` variable, then |
1546 | you specify the dependencies for the main package by setting | 1546 | you specify the dependencies for the main package by setting |
1547 | ``RDEPENDS_${PN}``. If the package were named ``${PN}-tools``, then you | 1547 | ``RDEPENDS:${PN}``. If the package were named ``${PN}-tools``, then you |
1548 | would set ``RDEPENDS_${PN}-tools``, and so forth. | 1548 | would set ``RDEPENDS:${PN}-tools``, and so forth. |
1549 | 1549 | ||
1550 | Some runtime dependencies will be set automatically at packaging time. | 1550 | Some runtime dependencies will be set automatically at packaging time. |
1551 | These dependencies include any shared library dependencies (i.e. if a | 1551 | These dependencies include any shared library dependencies (i.e. if a |
@@ -1796,7 +1796,7 @@ the software being built: | |||
1796 | sure the install portion of the build completes with no issues. | 1796 | sure the install portion of the build completes with no issues. |
1797 | However, if you wish to install additional files not already being | 1797 | However, if you wish to install additional files not already being |
1798 | installed by ``make install``, you should do this using a | 1798 | installed by ``make install``, you should do this using a |
1799 | ``do_install_append`` function using the install command as described | 1799 | ``do_install:append`` function using the install command as described |
1800 | in the "Manual" bulleted item later in this list. | 1800 | in the "Manual" bulleted item later in this list. |
1801 | 1801 | ||
1802 | - *Other (using* ``make install``\ *)*: You need to define a ``do_install`` | 1802 | - *Other (using* ``make install``\ *)*: You need to define a ``do_install`` |
@@ -1865,9 +1865,9 @@ additional definitions in your recipe. | |||
1865 | 1865 | ||
1866 | If you are adding services and the service initialization script or the | 1866 | If you are adding services and the service initialization script or the |
1867 | service file itself is not installed, you must provide for that | 1867 | service file itself is not installed, you must provide for that |
1868 | installation in your recipe using a ``do_install_append`` function. If | 1868 | installation in your recipe using a ``do_install:append`` function. If |
1869 | your recipe already has a ``do_install`` function, update the function | 1869 | your recipe already has a ``do_install`` function, update the function |
1870 | near its end rather than adding an additional ``do_install_append`` | 1870 | near its end rather than adding an additional ``do_install:append`` |
1871 | function. | 1871 | function. |
1872 | 1872 | ||
1873 | When you create the installation for your services, you need to | 1873 | When you create the installation for your services, you need to |
@@ -1938,7 +1938,7 @@ take. The following list describes the process: | |||
1938 | discover problems, you can set | 1938 | discover problems, you can set |
1939 | :term:`PACKAGES`, | 1939 | :term:`PACKAGES`, |
1940 | :term:`FILES`, | 1940 | :term:`FILES`, |
1941 | ``do_install(_append)``, and so forth as needed. | 1941 | ``do_install(:append)``, and so forth as needed. |
1942 | 1942 | ||
1943 | - *Splitting an Application into Multiple Packages*: If you need to | 1943 | - *Splitting an Application into Multiple Packages*: If you need to |
1944 | split an application into several packages, see the | 1944 | split an application into several packages, see the |
@@ -2137,7 +2137,7 @@ Post-Installation Scripts | |||
2137 | Post-installation scripts run immediately after installing a package on | 2137 | Post-installation scripts run immediately after installing a package on |
2138 | the target or during image creation when a package is included in an | 2138 | the target or during image creation when a package is included in an |
2139 | image. To add a post-installation script to a package, add a | 2139 | image. To add a post-installation script to a package, add a |
2140 | ``pkg_postinst_``\ `PACKAGENAME`\ ``()`` function to the recipe file | 2140 | ``pkg_postinst:``\ `PACKAGENAME`\ ``()`` function to the recipe file |
2141 | (``.bb``) and replace `PACKAGENAME` with the name of the package you want | 2141 | (``.bb``) and replace `PACKAGENAME` with the name of the package you want |
2142 | to attach to the ``postinst`` script. To apply the post-installation | 2142 | to attach to the ``postinst`` script. To apply the post-installation |
2143 | script to the main package for the recipe, which is usually what is | 2143 | script to the main package for the recipe, which is usually what is |
@@ -2147,7 +2147,7 @@ PACKAGENAME. | |||
2147 | 2147 | ||
2148 | A post-installation function has the following structure:: | 2148 | A post-installation function has the following structure:: |
2149 | 2149 | ||
2150 | pkg_postinst_PACKAGENAME() { | 2150 | pkg_postinst:PACKAGENAME() { |
2151 | # Commands to carry out | 2151 | # Commands to carry out |
2152 | } | 2152 | } |
2153 | 2153 | ||
@@ -2367,7 +2367,7 @@ In the previous example, we want to ship the ``sxpm`` and ``cxpm`` | |||
2367 | binaries in separate packages. Since ``bindir`` would be packaged into | 2367 | binaries in separate packages. Since ``bindir`` would be packaged into |
2368 | the main :term:`PN` package by default, we prepend the :term:`PACKAGES` variable | 2368 | the main :term:`PN` package by default, we prepend the :term:`PACKAGES` variable |
2369 | so additional package names are added to the start of list. This results | 2369 | so additional package names are added to the start of list. This results |
2370 | in the extra ``FILES_*`` variables then containing information that | 2370 | in the extra ``FILES:*`` variables then containing information that |
2371 | define which files and directories go into which packages. Files | 2371 | define which files and directories go into which packages. Files |
2372 | included by earlier packages are skipped by latter packages. Thus, the | 2372 | included by earlier packages are skipped by latter packages. Thus, the |
2373 | main :term:`PN` package does not include the above listed files. | 2373 | main :term:`PN` package does not include the above listed files. |
@@ -2398,7 +2398,7 @@ configure and compile steps as well as sets things up to grab packages | |||
2398 | from the appropriate area. In particular, this class sets ``noexec`` on | 2398 | from the appropriate area. In particular, this class sets ``noexec`` on |
2399 | both the :ref:`ref-tasks-configure` | 2399 | both the :ref:`ref-tasks-configure` |
2400 | and :ref:`ref-tasks-compile` tasks, | 2400 | and :ref:`ref-tasks-compile` tasks, |
2401 | sets ``FILES_${PN}`` to "/" so that it picks up all files, and sets up a | 2401 | sets ``FILES:${PN}`` to "/" so that it picks up all files, and sets up a |
2402 | :ref:`ref-tasks-install` task, which | 2402 | :ref:`ref-tasks-install` task, which |
2403 | effectively copies all files from ``${S}`` to ``${D}``. The | 2403 | effectively copies all files from ``${S}`` to ``${D}``. The |
2404 | ``bin_package`` class works well when the files extracted into ``${S}`` | 2404 | ``bin_package`` class works well when the files extracted into ``${S}`` |
@@ -2459,7 +2459,7 @@ doing the following: | |||
2459 | 2459 | ||
2460 | - Ensure that you set up :term:`FILES` | 2460 | - Ensure that you set up :term:`FILES` |
2461 | (usually | 2461 | (usually |
2462 | ``FILES_${``\ :term:`PN`\ ``}``) to | 2462 | ``FILES:${``\ :term:`PN`\ ``}``) to |
2463 | point to the files you have installed, which of course depends on | 2463 | point to the files you have installed, which of course depends on |
2464 | where you have installed them and whether those files are in | 2464 | where you have installed them and whether those files are in |
2465 | different locations than the defaults. | 2465 | different locations than the defaults. |
@@ -2631,7 +2631,7 @@ in the BitBake User Manual. | |||
2631 | 2631 | ||
2632 | VAR =+ "Starts" | 2632 | VAR =+ "Starts" |
2633 | 2633 | ||
2634 | - *Appending (_append):* Use the ``_append`` operator to append values | 2634 | - *Appending (:append):* Use the ``:append`` operator to append values |
2635 | to existing variables. This operator does not add any additional | 2635 | to existing variables. This operator does not add any additional |
2636 | space. Also, the operator is applied after all the ``+=``, and ``=+`` | 2636 | space. Also, the operator is applied after all the ``+=``, and ``=+`` |
2637 | operators have been applied and after all ``=`` assignments have | 2637 | operators have been applied and after all ``=`` assignments have |
@@ -2644,12 +2644,12 @@ in the BitBake User Manual. | |||
2644 | SRC_URI:append = " file://fix-makefile.patch" | 2644 | SRC_URI:append = " file://fix-makefile.patch" |
2645 | 2645 | ||
2646 | You can also use | 2646 | You can also use |
2647 | the ``_append`` operator with overrides, which results in the actions | 2647 | the ``:append`` operator with overrides, which results in the actions |
2648 | only being performed for the specified target or machine:: | 2648 | only being performed for the specified target or machine:: |
2649 | 2649 | ||
2650 | SRC_URI:append:sh4 = " file://fix-makefile.patch" | 2650 | SRC_URI:append:sh4 = " file://fix-makefile.patch" |
2651 | 2651 | ||
2652 | - *Prepending (_prepend):* Use the ``_prepend`` operator to prepend | 2652 | - *Prepending (:prepend):* Use the ``:prepend`` operator to prepend |
2653 | values to existing variables. This operator does not add any | 2653 | values to existing variables. This operator does not add any |
2654 | additional space. Also, the operator is applied after all the ``+=``, | 2654 | additional space. Also, the operator is applied after all the ``+=``, |
2655 | and ``=+`` operators have been applied and after all ``=`` | 2655 | and ``=+`` operators have been applied and after all ``=`` |
@@ -2662,7 +2662,7 @@ in the BitBake User Manual. | |||
2662 | CFLAGS:prepend = "-I${S}/myincludes " | 2662 | CFLAGS:prepend = "-I${S}/myincludes " |
2663 | 2663 | ||
2664 | You can also use the | 2664 | You can also use the |
2665 | ``_prepend`` operator with overrides, which results in the actions | 2665 | ``:prepend`` operator with overrides, which results in the actions |
2666 | only being performed for the specified target or machine:: | 2666 | only being performed for the specified target or machine:: |
2667 | 2667 | ||
2668 | CFLAGS:prepend:sh4 = "-I${S}/myincludes " | 2668 | CFLAGS:prepend:sh4 = "-I${S}/myincludes " |
@@ -4538,7 +4538,7 @@ that can help you speed up the build: | |||
4538 | exceptions:: | 4538 | exceptions:: |
4539 | 4539 | ||
4540 | STATICLIBCONF = "--disable-static" | 4540 | STATICLIBCONF = "--disable-static" |
4541 | STATICLIBCONF_sqlite3-native = "" | 4541 | STATICLIBCONF:sqlite3-native = "" |
4542 | EXTRA_OECONF += "${STATICLIBCONF}" | 4542 | EXTRA_OECONF += "${STATICLIBCONF}" |
4543 | 4543 | ||
4544 | .. note:: | 4544 | .. note:: |
@@ -4578,7 +4578,7 @@ can control which static library files (``*.a`` files) get included in | |||
4578 | the built library. | 4578 | the built library. |
4579 | 4579 | ||
4580 | The :term:`PACKAGES` and | 4580 | The :term:`PACKAGES` and |
4581 | :term:`FILES_* <FILES>` variables in the | 4581 | :term:`FILES:* <FILES>` variables in the |
4582 | ``meta/conf/bitbake.conf`` configuration file define how files installed | 4582 | ``meta/conf/bitbake.conf`` configuration file define how files installed |
4583 | by the ``do_install`` task are packaged. By default, the :term:`PACKAGES` | 4583 | by the ``do_install`` task are packaged. By default, the :term:`PACKAGES` |
4584 | variable includes ``${PN}-staticdev``, which represents all static | 4584 | variable includes ``${PN}-staticdev``, which represents all static |
@@ -6510,8 +6510,8 @@ function in your recipe. The ``do_split_packages`` function searches for | |||
6510 | a pattern of files or directories under a specified path and creates a | 6510 | a pattern of files or directories under a specified path and creates a |
6511 | package for each one it finds by appending to the | 6511 | package for each one it finds by appending to the |
6512 | :term:`PACKAGES` variable and | 6512 | :term:`PACKAGES` variable and |
6513 | setting the appropriate values for ``FILES_packagename``, | 6513 | setting the appropriate values for ``FILES:packagename``, |
6514 | ``RDEPENDS_packagename``, ``DESCRIPTION_packagename``, and so forth. | 6514 | ``RDEPENDS:packagename``, ``DESCRIPTION:packagename``, and so forth. |
6515 | Here is an example from the ``lighttpd`` recipe:: | 6515 | Here is an example from the ``lighttpd`` recipe:: |
6516 | 6516 | ||
6517 | python populate_packages:prepend () { | 6517 | python populate_packages:prepend () { |
@@ -7389,11 +7389,11 @@ The variable can be used in multiple ways, including using suffixes to | |||
7389 | set it for a specific package type and/or package. Note that the order | 7389 | set it for a specific package type and/or package. Note that the order |
7390 | of precedence is the same as this list: | 7390 | of precedence is the same as this list: |
7391 | 7391 | ||
7392 | - ``PACKAGE_ADD_METADATA_<PKGTYPE>_<PN>`` | 7392 | - ``PACKAGE_ADD_METADATA_<PKGTYPE>:<PN>`` |
7393 | 7393 | ||
7394 | - ``PACKAGE_ADD_METADATA_<PKGTYPE>`` | 7394 | - ``PACKAGE_ADD_METADATA_<PKGTYPE>`` |
7395 | 7395 | ||
7396 | - ``PACKAGE_ADD_METADATA_<PN>`` | 7396 | - ``PACKAGE_ADD_METADATA:<PN>`` |
7397 | 7397 | ||
7398 | - :term:`PACKAGE_ADD_METADATA` | 7398 | - :term:`PACKAGE_ADD_METADATA` |
7399 | 7399 | ||
@@ -7664,11 +7664,11 @@ configuration file contains the line:: | |||
7664 | This line pulls in the | 7664 | This line pulls in the |
7665 | listed include file that contains numerous lines of exactly that form:: | 7665 | listed include file that contains numerous lines of exactly that form:: |
7666 | 7666 | ||
7667 | #SRCREV_pn-opkg-native ?= "${AUTOREV}" | 7667 | #SRCREV:pn-opkg-native ?= "${AUTOREV}" |
7668 | #SRCREV_pn-opkg-sdk ?= "${AUTOREV}" | 7668 | #SRCREV:pn-opkg-sdk ?= "${AUTOREV}" |
7669 | #SRCREV_pn-opkg ?= "${AUTOREV}" | 7669 | #SRCREV:pn-opkg ?= "${AUTOREV}" |
7670 | #SRCREV_pn-opkg-utils-native ?= "${AUTOREV}" | 7670 | #SRCREV:pn-opkg-utils-native ?= "${AUTOREV}" |
7671 | #SRCREV_pn-opkg-utils ?= "${AUTOREV}" | 7671 | #SRCREV:pn-opkg-utils ?= "${AUTOREV}" |
7672 | SRCREV:pn-gconf-dbus ?= "${AUTOREV}" | 7672 | SRCREV:pn-gconf-dbus ?= "${AUTOREV}" |
7673 | SRCREV:pn-matchbox-common ?= "${AUTOREV}" | 7673 | SRCREV:pn-matchbox-common ?= "${AUTOREV}" |
7674 | SRCREV:pn-matchbox-config-gtk ?= "${AUTOREV}" | 7674 | SRCREV:pn-matchbox-config-gtk ?= "${AUTOREV}" |
@@ -8941,7 +8941,7 @@ In addition to variable values, the output of the ``bitbake -e`` and | |||
8941 | - After the variable values, all functions appear in the output. For | 8941 | - After the variable values, all functions appear in the output. For |
8942 | shell functions, variables referenced within the function body are | 8942 | shell functions, variables referenced within the function body are |
8943 | expanded. If a function has been modified using overrides or using | 8943 | expanded. If a function has been modified using overrides or using |
8944 | override-style operators like ``_append`` and ``_prepend``, then the | 8944 | override-style operators like ``:append`` and ``:prepend``, then the |
8945 | final assembled function body appears in the output. | 8945 | final assembled function body appears in the output. |
8946 | 8946 | ||
8947 | Viewing Package Information with ``oe-pkgdata-util`` | 8947 | Viewing Package Information with ``oe-pkgdata-util`` |