From 9fece9c36125aeec1ee3b3845fc914ec0dbf3034 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Fri, 23 Sep 2022 17:20:26 +0200 Subject: manuals: add reference to the "do_install" task [YOCTO #14508] (From yocto-docs rev: 933ad27b81dfc4a28e7c48ca7bb2d1363e8c037f) Signed-off-by: Michael Opdenacker Reported-by: Quentin Schulz Signed-off-by: Richard Purdie --- documentation/dev-manual/common-tasks.rst | 32 ++++++++++++------------ documentation/migration-guides/migration-3.2.rst | 4 +-- documentation/migration-guides/migration-4.0.rst | 2 +- documentation/overview-manual/concepts.rst | 4 +-- documentation/ref-manual/classes.rst | 8 +++--- documentation/ref-manual/faq.rst | 2 +- documentation/ref-manual/qa-checks.rst | 12 ++++----- documentation/ref-manual/tasks.rst | 2 +- documentation/ref-manual/variables.rst | 2 +- documentation/sdk-manual/extensible.rst | 2 +- 10 files changed, 35 insertions(+), 35 deletions(-) diff --git a/documentation/dev-manual/common-tasks.rst b/documentation/dev-manual/common-tasks.rst index 3d96399047..a6e61c891f 100644 --- a/documentation/dev-manual/common-tasks.rst +++ b/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:* ` 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 diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst index a4d0479d92..8d251deaf7 100644 --- a/documentation/migration-guides/migration-3.2.rst +++ b/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 ` 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 ` 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 ` 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. diff --git a/documentation/migration-guides/migration-4.0.rst b/documentation/migration-guides/migration-4.0.rst index ce3212a464..02d3c3e2bd 100644 --- a/documentation/migration-guides/migration-4.0.rst +++ b/documentation/migration-guides/migration-4.0.rst @@ -145,7 +145,7 @@ Python changes :ref:`python_setuptools_build_meta ` and :ref:`python_poetry_core `. -- The :ref:`setuptools3 ` class ``do_install()`` task now +- The :ref:`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 diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index fa060ce0de..2e1aa3df48 100644 --- a/documentation/overview-manual/concepts.rst +++ b/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:`ref-tasks-rootfs`, and :ref:`do_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 diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index f402d090c9..673e90d9ec 100644 --- a/documentation/ref-manual/classes.rst +++ b/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 diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst index 61049523a0..cb90677923 100644 --- a/documentation/ref-manual/faq.rst +++ b/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 diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst index fbab1dc92e..ff8916aedf 100644 --- a/documentation/ref-manual/qa-checks.rst +++ b/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. diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst index 2a692c1725..24203fcf78 100644 --- a/documentation/ref-manual/tasks.rst +++ b/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 diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 2e2e16574c..1582664e62 100644 --- a/documentation/ref-manual/variables.rst +++ b/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`" diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst index 0df6519b8e..09b7169811 100644 --- a/documentation/sdk-manual/extensible.rst +++ b/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. -- cgit v1.2.3-54-g00ecf