manuals: add reference to the "do_install" task

[YOCTO #14508]
(From yocto-docs rev: 933ad27b81dfc4a28e7c48ca7bb2d1363e8c037f)

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reported-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/dev-manual/common-tasks.rst

@@ -1731,7 +1731,7 @@ your software is built:
 
       If you need to install one or more custom CMake toolchain files
       that are supplied by the application you are building, install the
-      files to ``${D}${datadir}/cmake/Modules`` during ``do_install``.
+      files to ``${D}${datadir}/cmake/Modules`` during :ref:`ref-tasks-install`.
 
 -  *Other:* If your source files do not have a ``configure.ac`` or
    ``CMakeLists.txt`` file, then your software is built using some
@@ -1888,7 +1888,7 @@ Here are some common issues that cause failures.
 Installing
 ----------
 
-During ``do_install``, the task copies the built files along with their
+During :ref:`ref-tasks-install`, the task copies the built files along with their
 hierarchy to locations that would mirror their locations on the target
 device. The installation process copies files from the
 ``${``\ :term:`S`\ ``}``,
@@ -1906,14 +1906,14 @@ the software being built:
 -  *Autotools and CMake:* If the software your recipe is building uses
    Autotools or CMake, the OpenEmbedded build system understands how to
    install the software. Consequently, you do not have to have a
-   ``do_install`` task as part of your recipe. You just need to make
+   :ref:`ref-tasks-install` task as part of your recipe. You just need to make
    sure the install portion of the build completes with no issues.
    However, if you wish to install additional files not already being
    installed by ``make install``, you should do this using a
    ``do_install:append`` function using the install command as described
    in the "Manual" bulleted item later in this list.
 
--  *Other (using* ``make install``\ *)*: You need to define a ``do_install``
+-  *Other (using* ``make install``\ *)*: You need to define a :ref:`ref-tasks-install`
    function in your recipe. The function should call
    ``oe_runmake install`` and will likely need to pass in the
    destination directory as well. How you pass that path is dependent on
@@ -1923,7 +1923,7 @@ the software being built:
    For an example recipe using ``make install``, see the
    ":ref:`dev-manual/common-tasks:makefile-based package`" section.
 
--  *Manual:* You need to define a ``do_install`` function in your
+-  *Manual:* You need to define a :ref:`ref-tasks-install` function in your
    recipe. The function must first use ``install -d`` to create the
    directories under
    ``${``\ :term:`D`\ ``}``. Once the
@@ -1946,10 +1946,10 @@ installed correctly.
       might need to replace hard-coded paths in an initscript with
       values of variables provided by the build system, such as
       replacing ``/usr/bin/`` with ``${bindir}``. If you do perform such
-      modifications during ``do_install``, be sure to modify the
+      modifications during :ref:`ref-tasks-install`, be sure to modify the
       destination file after copying rather than before copying.
       Modifying after copying ensures that the build system can
-      re-execute ``do_install`` if needed.
+      re-execute :ref:`ref-tasks-install` if needed.
 
    -  ``oe_runmake install``, which can be run directly or can be run
       indirectly by the
@@ -1958,7 +1958,7 @@ installed correctly.
       runs ``make install`` in parallel. Sometimes, a Makefile can have
       missing dependencies between targets that can result in race
       conditions. If you experience intermittent failures during
-      ``do_install``, you might be able to work around them by disabling
+      :ref:`ref-tasks-install`, you might be able to work around them by disabling
       parallel Makefile installs by adding the following to the recipe::
 
          PARALLEL_MAKEINST = ""
@@ -1980,7 +1980,7 @@ additional definitions in your recipe.
 If you are adding services and the service initialization script or the
 service file itself is not installed, you must provide for that
 installation in your recipe using a ``do_install:append`` function. If
-your recipe already has a ``do_install`` function, update the function
+your recipe already has a :ref:`ref-tasks-install` function, update the function
 near its end rather than adding an additional ``do_install:append``
 function.
 
@@ -2337,7 +2337,7 @@ Single .c File Package (Hello World!)
 Building an application from a single file that is stored locally (e.g.
 under ``files``) requires a recipe that has the file listed in the
 :term:`SRC_URI` variable. Additionally, you need to manually write the
-``do_compile`` and ``do_install`` tasks. The :term:`S` variable defines the
+``do_compile`` and :ref:`ref-tasks-install` tasks. The :term:`S` variable defines the
 directory containing the source code, which is set to
 :term:`WORKDIR` in this case --- the
 directory BitBake uses for the build.
@@ -2407,8 +2407,8 @@ should store them in the
 :term:`EXTRA_OEMAKE` or
 :term:`PACKAGECONFIG_CONFARGS`
 variables. BitBake passes these options into the GNU ``make``
-invocation. Note that a ``do_install`` task is still required.
-Otherwise, BitBake runs an empty ``do_install`` task by default.
+invocation. Note that a :ref:`ref-tasks-install` task is still required.
+Otherwise, BitBake runs an empty :ref:`ref-tasks-install` task by default.
 
 Some applications might require extra parameters to be passed to the
 compiler. For example, the application might need an additional header
@@ -2567,7 +2567,7 @@ doing the following:
    :ref:`ref-tasks-patch` tasks to the
    :ref:`ref-tasks-install` task.
 
--  Make sure your ``do_install`` task installs the binaries
+-  Make sure your :ref:`ref-tasks-install` task installs the binaries
    appropriately.
 
 -  Ensure that you set up :term:`FILES`
@@ -4700,7 +4700,7 @@ the built library.
 The :term:`PACKAGES` and
 :term:`FILES:* <FILES>` variables in the
 ``meta/conf/bitbake.conf`` configuration file define how files installed
-by the ``do_install`` task are packaged. By default, the :term:`PACKAGES`
+by the :ref:`ref-tasks-install` task are packaged. By default, the :term:`PACKAGES`
 variable includes ``${PN}-staticdev``, which represents all static
 library files.
 
@@ -6862,7 +6862,7 @@ The previous example specifies a number of things in the call to
 ``do_split_packages``.
 
 -  A directory within the files installed by your recipe through
-   ``do_install`` in which to search.
+   :ref:`ref-tasks-install` in which to search.
 
 -  A regular expression used to match module files in that directory. In
    the example, note the parentheses () that mark the part of the
@@ -9594,7 +9594,7 @@ Running Specific Tasks
 
 Any given recipe consists of a set of tasks. The standard BitBake
 behavior in most cases is: :ref:`ref-tasks-fetch`, ``do_unpack``, ``do_patch``,
-``do_configure``, ``do_compile``, ``do_install``, ``do_package``,
+``do_configure``, ``do_compile``, :ref:`ref-tasks-install`, ``do_package``,
 ``do_package_write_*``, and ``do_build``. The default task is
 ``do_build`` and any tasks on which it depends build first. Some tasks,
 such as ``do_devshell``, are not part of the default build chain. If you

documentation/migration-guides/migration-3.2.rst

@@ -60,7 +60,7 @@ pseudo as the interprocess round trip to the server is avoided.
 
 There is a possible complication where some existing recipe may break, for
 example, a recipe was found to be writing to ``${B}/install`` for
-``make install`` in ``do_install`` and since ``${B}`` is listed as not to be tracked,
+``make install`` in :ref:`ref-tasks-install` and since ``${B}`` is listed as not to be tracked,
 there were errors trying to ``chown root`` for files in this location. Another
 example was the ``tcl`` recipe where the source directory :term:`S` is set to a
 subdirectory of the source tree but files were written out to the directory
@@ -207,7 +207,7 @@ files into a subdirectory and reference that instead.
 deploy class now cleans ``DEPLOYDIR`` before ``do_deploy``
 ----------------------------------------------------------
 
-``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as ``do_install`` cleans up ${:term:`D`} before running. This reduces the risk of :term:`DEPLOYDIR` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds.
+``do_deploy`` as implemented in the :ref:`deploy <ref-classes-deploy>` class now cleans up ${:term:`DEPLOYDIR`} before running, just as :ref:`ref-tasks-install` cleans up ${:term:`D`} before running. This reduces the risk of :term:`DEPLOYDIR` being accidentally contaminated by files from previous runs, possibly even with different config, in case of incremental builds.
 
 Most recipes and classes that inherit the :ref:`deploy <ref-classes-deploy>` class or interact with ``do_deploy`` are unlikely to be affected by this unless they add ``prefuncs`` to ``do_deploy`` *which also* put files into ``${DEPLOYDIR}`` --- these should be refactored to use ``do_deploy_prepend`` instead.
 

documentation/migration-guides/migration-4.0.rst

@@ -145,7 +145,7 @@ Python changes
   :ref:`python_setuptools_build_meta <ref-classes-python_setuptools_build_meta>`
   and :ref:`python_poetry_core <ref-classes-python_poetry_core>`.  
 
-- The :ref:`setuptools3 <ref-classes-setuptools3>` class ``do_install()`` task now
+- The :ref:`setuptools3 <ref-classes-setuptools3>` class :ref:`ref-tasks-install` task now
   installs the ``wheel`` binary archive. In current versions of ``setuptools`` the
   legacy ``setup.py install`` method is deprecated. If the ``setup.py`` cannot be used
   with wheels, for example it creates files outside of the Python module or standard

documentation/overview-manual/concepts.rst

@@ -1209,7 +1209,7 @@ The build system has knowledge of the relationship between these tasks
 and other preceding tasks. For example, if BitBake runs
 ``do_populate_sysroot_setscene`` for something, it does not make sense
 to run any of the :ref:`ref-tasks-fetch`, ``do_unpack``, ``do_patch``,
-``do_configure``, ``do_compile``, and ``do_install`` tasks. However, if
+``do_configure``, ``do_compile``, and :ref:`ref-tasks-install` tasks. However, if
 ``do_package`` needs to be run, BitBake needs to run those other tasks.
 
 It becomes more complicated if everything can come from an sstate cache
@@ -2163,7 +2163,7 @@ operations that are normally reserved for the root user (e.g.
 :ref:`do_package_write* <ref-tasks-package_write_deb>`,
 :ref:`ref-tasks-rootfs`, and
 :ref:`do_image* <ref-tasks-image>`). For example,
-the ``do_install`` task benefits from being able to set the UID and GID
+the :ref:`ref-tasks-install` task benefits from being able to set the UID and GID
 of installed files to arbitrary values.
 
 One approach to allowing tasks to perform root-only operations would be

documentation/ref-manual/classes.rst

@@ -1081,12 +1081,12 @@ Here are the tests you can list with the :term:`WARN_QA` and
    might result in host contamination of the build output.
 
 -  ``installed-vs-shipped:`` Reports when files have been installed
-   within ``do_install`` but have not been included in any package by
+   within :ref:`ref-tasks-install` but have not been included in any package by
    way of the :term:`FILES` variable. Files that do not
    appear in any package cannot be present in an image later on in the
    build process. Ideally, all installed files should be packaged or not
    installed at all. These files can be deleted at the end of
-   ``do_install`` if the files are not needed in any package.
+   :ref:`ref-tasks-install` if the files are not needed in any package.
 
 -  ``invalid-chars:`` Checks that the recipe metadata variables
    :term:`DESCRIPTION`,
@@ -1339,7 +1339,7 @@ Only a single U-boot boot script can be added to the FIT image created by
 ``kernel-fitimage`` and the boot script is optional.
 The boot script is specified in the ITS file as a text file containing
 U-boot commands. When using a boot script the user should configure the
-U-boot ``do_install`` task to copy the script to sysroot.
+U-boot :ref:`ref-tasks-install` task to copy the script to sysroot.
 So the script can be included in the FIT image by the ``kernel-fitimage``
 class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
 load the boot script from the FIT image and executes it.
@@ -2412,7 +2412,7 @@ uses these build systems, the recipe needs to inherit the ``setuptools3`` class.
 
    .. note::
 
-     The ``setuptools3`` class ``do_install()`` task now installs the ``wheel``
+     The ``setuptools3`` class :ref:`ref-tasks-install` task now installs the ``wheel``
      binary archive. In current versions of ``setuptools`` the legacy ``setup.py
      install`` method is deprecated. If the ``setup.py`` cannot be used with
      wheels, for example it creates files outside of the Python module or

documentation/ref-manual/faq.rst

@@ -437,7 +437,7 @@ practice very effective.
 **Q:** The files provided by my ``*-native`` recipe do not appear to be
 available to other recipes. Files are missing from the native sysroot,
 my recipe is installing to the wrong place, or I am getting permissions
-errors during the do_install task in my recipe! What is wrong?
+errors during the :ref:`ref-tasks-install` task in my recipe! What is wrong?
 
 **A:** This situation results when a build system does not recognize the
 environment variables supplied to it by :term:`BitBake`. The

documentation/ref-manual/qa-checks.rst

@@ -162,7 +162,7 @@ Errors and Warnings
    normally expected to be empty (such as ``/tmp``). These files may
    be more appropriately installed to a different location, or
    perhaps alternatively not installed at all, usually by updating the
-   ``do_install`` task/function.
+   :ref:`ref-tasks-install` task/function.
 
 .. _qa-check-arch:
 
@@ -536,7 +536,7 @@ Errors and Warnings
       in (e.g. ``FILES:${``\ :term:`PN`\ ``}`` for the main
       package).
 
-   -  Delete the files at the end of the ``do_install`` task if the
+   -  Delete the files at the end of the :ref:`ref-tasks-install` task if the
       files are not needed in any package.
 
     
@@ -582,7 +582,7 @@ Errors and Warnings
    ``${datadir}/mime/packages``) and yet does not inherit the mime
    class which will ensure that these get properly installed. Either
    add ``inherit mime`` to the recipe or remove the files at the
-   ``do_install`` step if they are not needed.
+   :ref:`ref-tasks-install` step if they are not needed.
 
 
 .. _qa-check-mime-xdg:
@@ -592,7 +592,7 @@ Errors and Warnings
     The specified package contains a .desktop file with a 'MimeType' key
     present, but does not inherit the mime-xdg class that is required in
     order for that to be activated. Either add ``inherit mime`` to the
-    recipe or remove the files at the ``do_install`` step if they are not
+    recipe or remove the files at the :ref:`ref-tasks-install` step if they are not
     needed.
 
 
@@ -667,8 +667,8 @@ Errors and Warnings
 
     If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package
     installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this
-    message, it indicates that the ``do_install`` step (or perhaps the build process that
-    ``do_install`` is calling into, e.g. ``make install`` is using hardcoded paths instead
+    message, it indicates that the :ref:`ref-tasks-install` step (or perhaps the build process that
+    :ref:`ref-tasks-install` is calling into, e.g. ``make install`` is using hardcoded paths instead
     of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be
     changed so that it does.
 

documentation/ref-manual/tasks.rst

@@ -168,7 +168,7 @@ section in the Yocto Project Overview and Concepts Manual.
 Copies files that are to be packaged into the holding area
 ``${``\ :term:`D`\ ``}``. This task runs with the current
 working directory set to ``${``\ :term:`B`\ ``}``, which is the
-compilation directory. The ``do_install`` task, as well as other tasks
+compilation directory. The :ref:`ref-tasks-install` task, as well as other tasks
 that either directly or indirectly depend on the installed files (e.g.
 :ref:`ref-tasks-package`, ``do_package_write_*``, and
 :ref:`ref-tasks-rootfs`), run under

documentation/ref-manual/variables.rst

@@ -5675,7 +5675,7 @@ system and gives an overview of their function and contents.
          way to ensure this is to use the ``oe_runmake`` function.
 
          If the software being built experiences dependency issues during
-         the ``do_install`` task that result in race conditions, you can
+         the :ref:`ref-tasks-install` task that result in race conditions, you can
          clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a
          workaround. For information on addressing race conditions, see the
          ":ref:`dev-manual/common-tasks:debugging parallel make races`"

documentation/sdk-manual/extensible.rst

@@ -1112,7 +1112,7 @@ links created within the source tree:
       ``${``\ :term:`D`\ ``}``.
 
    -  ``sysroot-destdir/``: Contains a subset of files installed within
-      ``do_install`` that have been put into the shared sysroot. For
+      :ref:`ref-tasks-install` that have been put into the shared sysroot. For
       more information, see the
       ":ref:`dev-manual/common-tasks:sharing files between recipes`" section.