summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorQuentin Schulz <foss@0leil.net>2021-08-11 22:06:01 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2021-08-14 12:04:23 +0100
commit3d93ddf9e8867ca3f331fc9d3f4eb658a2b7810f (patch)
tree58769f99fa5ac2af2bbff9fe2fc829ee7132023d /documentation/dev-manual
parented6482821c1cc04d3cd35f6b30631a4d09b594d1 (diff)
downloadpoky-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')
-rw-r--r--documentation/dev-manual/common-tasks.rst80
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
830all images, which might not be what you require. 830all images, which might not be what you require.
831 831
832To add a package to your image using the local configuration file, use 832To add a package to your image using the local configuration file, use
833the :term:`IMAGE_INSTALL` variable with the ``_append`` operator:: 833the :term:`IMAGE_INSTALL` variable with the ``:append`` operator::
834 834
835 IMAGE_INSTALL:append = " strace" 835 IMAGE_INSTALL:append = " strace"
836 836
837Use of the syntax is important - 837Use of the syntax is important -
838specifically, the space between the quote and the package name, which is 838specifically, 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``
840operator does not add the space. 840operator does not add the space.
841 841
842Furthermore, you must use ``_append`` instead of the ``+=`` operator if 842Furthermore, you must use ``:append`` instead of the ``+=`` operator if
843you want to avoid ordering issues. The reason for this is because doing 843you want to avoid ordering issues. The reason for this is because doing
844so unconditionally appends to the variable and avoids ordering problems 844so unconditionally appends to the variable and avoids ordering problems
845due to the variable being set in image recipes and ``.bbclass`` files 845due to the variable being set in image recipes and ``.bbclass`` files
846with operators like ``?=``. Using ``_append`` ensures the operation 846with operators like ``?=``. Using ``:append`` ensures the operation
847takes effect. 847takes effect.
848 848
849As shown in its simplest use, ``IMAGE_INSTALL_append`` affects all 849As shown in its simplest use, ``IMAGE_INSTALL:append`` affects all
850images. It is possible to extend the syntax so that the variable applies 850images. It is possible to extend the syntax so that the variable applies
851to a specific image only. Here is an example:: 851to 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
1544name can be found through the 1544name can be found through the
1545``${``\ :term:`PN`\ ``}`` variable, then 1545``${``\ :term:`PN`\ ``}`` variable, then
1546you specify the dependencies for the main package by setting 1546you 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
1548would set ``RDEPENDS_${PN}-tools``, and so forth. 1548would set ``RDEPENDS:${PN}-tools``, and so forth.
1549 1549
1550Some runtime dependencies will be set automatically at packaging time. 1550Some runtime dependencies will be set automatically at packaging time.
1551These dependencies include any shared library dependencies (i.e. if a 1551These 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
1866If you are adding services and the service initialization script or the 1866If you are adding services and the service initialization script or the
1867service file itself is not installed, you must provide for that 1867service file itself is not installed, you must provide for that
1868installation in your recipe using a ``do_install_append`` function. If 1868installation in your recipe using a ``do_install:append`` function. If
1869your recipe already has a ``do_install`` function, update the function 1869your recipe already has a ``do_install`` function, update the function
1870near its end rather than adding an additional ``do_install_append`` 1870near its end rather than adding an additional ``do_install:append``
1871function. 1871function.
1872 1872
1873When you create the installation for your services, you need to 1873When 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
2137Post-installation scripts run immediately after installing a package on 2137Post-installation scripts run immediately after installing a package on
2138the target or during image creation when a package is included in an 2138the target or during image creation when a package is included in an
2139image. To add a post-installation script to a package, add a 2139image. 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
2142to attach to the ``postinst`` script. To apply the post-installation 2142to attach to the ``postinst`` script. To apply the post-installation
2143script to the main package for the recipe, which is usually what is 2143script to the main package for the recipe, which is usually what is
@@ -2147,7 +2147,7 @@ PACKAGENAME.
2147 2147
2148A post-installation function has the following structure:: 2148A 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``
2367binaries in separate packages. Since ``bindir`` would be packaged into 2367binaries in separate packages. Since ``bindir`` would be packaged into
2368the main :term:`PN` package by default, we prepend the :term:`PACKAGES` variable 2368the main :term:`PN` package by default, we prepend the :term:`PACKAGES` variable
2369so additional package names are added to the start of list. This results 2369so additional package names are added to the start of list. This results
2370in the extra ``FILES_*`` variables then containing information that 2370in the extra ``FILES:*`` variables then containing information that
2371define which files and directories go into which packages. Files 2371define which files and directories go into which packages. Files
2372included by earlier packages are skipped by latter packages. Thus, the 2372included by earlier packages are skipped by latter packages. Thus, the
2373main :term:`PN` package does not include the above listed files. 2373main :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
2398from the appropriate area. In particular, this class sets ``noexec`` on 2398from the appropriate area. In particular, this class sets ``noexec`` on
2399both the :ref:`ref-tasks-configure` 2399both the :ref:`ref-tasks-configure`
2400and :ref:`ref-tasks-compile` tasks, 2400and :ref:`ref-tasks-compile` tasks,
2401sets ``FILES_${PN}`` to "/" so that it picks up all files, and sets up a 2401sets ``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
2403effectively copies all files from ``${S}`` to ``${D}``. The 2403effectively 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
4578the built library. 4578the built library.
4579 4579
4580The :term:`PACKAGES` and 4580The :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
4583by the ``do_install`` task are packaged. By default, the :term:`PACKAGES` 4583by the ``do_install`` task are packaged. By default, the :term:`PACKAGES`
4584variable includes ``${PN}-staticdev``, which represents all static 4584variable includes ``${PN}-staticdev``, which represents all static
@@ -6510,8 +6510,8 @@ function in your recipe. The ``do_split_packages`` function searches for
6510a pattern of files or directories under a specified path and creates a 6510a pattern of files or directories under a specified path and creates a
6511package for each one it finds by appending to the 6511package for each one it finds by appending to the
6512:term:`PACKAGES` variable and 6512:term:`PACKAGES` variable and
6513setting the appropriate values for ``FILES_packagename``, 6513setting the appropriate values for ``FILES:packagename``,
6514``RDEPENDS_packagename``, ``DESCRIPTION_packagename``, and so forth. 6514``RDEPENDS:packagename``, ``DESCRIPTION:packagename``, and so forth.
6515Here is an example from the ``lighttpd`` recipe:: 6515Here 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
7389set it for a specific package type and/or package. Note that the order 7389set it for a specific package type and/or package. Note that the order
7390of precedence is the same as this list: 7390of 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::
7664This line pulls in the 7664This line pulls in the
7665listed include file that contains numerous lines of exactly that form:: 7665listed 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
8947Viewing Package Information with ``oe-pkgdata-util`` 8947Viewing Package Information with ``oe-pkgdata-util``