From 0e8d0ecc6ce511bacc59d06214d6e53ee4dceaad Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Fri, 23 Sep 2022 17:51:03 +0200 Subject: manuals: add references to the "do_deploy" task [YOCTO #14508] Reported-by: Quentin Schulz (From yocto-docs rev: b607a0578e8edd3e4ee013b4438481cb82bc106e) Signed-off-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/migration-guides/migration-3.2.rst | 4 ++-- documentation/overview-manual/concepts.rst | 18 +++++++++--------- documentation/ref-manual/tasks.rst | 8 ++++---- documentation/ref-manual/variables.rst | 2 +- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst index 8d251deaf7..a714bd6bca 100644 --- a/documentation/migration-guides/migration-3.2.rst +++ b/documentation/migration-guides/migration-3.2.rst @@ -207,9 +207,9 @@ 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 :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. +:ref:`ref-tasks-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. +Most recipes and classes that inherit the :ref:`deploy ` class or interact with :ref:`ref-tasks-deploy` are unlikely to be affected by this unless they add ``prefuncs`` to :ref:`ref-tasks-deploy` *which also* put files into ``${DEPLOYDIR}`` --- these should be refactored to use ``do_deploy_prepend`` instead. .. _migration-3.2-nativesdk-sdk-provides-dummy: diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst index 06220401bc..f3f8cbd95c 100644 --- a/documentation/overview-manual/concepts.rst +++ b/documentation/overview-manual/concepts.rst @@ -1801,14 +1801,14 @@ from the :ref:`deploy ` class:: The following list explains the previous example: -- Adding "do_deploy" to ``SSTATETASKS`` adds some required +- Adding ``do_deploy`` to ``SSTATETASKS`` adds some required sstate-related processing, which is implemented in the :ref:`sstate ` class, to before and after the :ref:`ref-tasks-deploy` task. - The ``do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"`` declares that - ``do_deploy`` places its output in ``${DEPLOYDIR}`` when run normally + :ref:`ref-tasks-deploy` places its output in ``${DEPLOYDIR}`` when run normally (i.e. when not using the sstate cache). This output becomes the input to the shared state cache. @@ -1818,15 +1818,15 @@ The following list explains the previous example: .. note:: - If ``do_deploy`` is not already in the shared state cache or if its input + If :ref:`ref-tasks-deploy` is not already in the shared state cache or if its input checksum (signature) has changed from when the output was cached, the task runs to populate the shared state cache, after which the contents of the shared state cache is copied to ${:term:`DEPLOY_DIR_IMAGE`}. If - ``do_deploy`` is in the shared state cache and its signature indicates + :ref:`ref-tasks-deploy` is in the shared state cache and its signature indicates that the cached output is still valid (i.e. if no relevant task inputs have changed), then the contents of the shared state cache copies directly to ${:term:`DEPLOY_DIR_IMAGE`} by the ``do_deploy_setscene`` task - instead, skipping the ``do_deploy`` task. + instead, skipping the :ref:`ref-tasks-deploy` task. - The following task definition is glue logic needed to make the previous settings effective:: @@ -1836,16 +1836,16 @@ The following list explains the previous example: } addtask do_deploy_setscene - ``sstate_setscene()`` takes the flags above as input and accelerates the ``do_deploy`` task + ``sstate_setscene()`` takes the flags above as input and accelerates the :ref:`ref-tasks-deploy` task through the shared state cache if possible. If the task was accelerated, ``sstate_setscene()`` returns True. Otherwise, it - returns False, and the normal ``do_deploy`` task runs. For more + returns False, and the normal :ref:`ref-tasks-deploy` task runs. For more information, see the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:setscene`" section in the BitBake User Manual. - The ``do_deploy[dirs] = "${DEPLOYDIR} ${B}"`` line creates - ``${DEPLOYDIR}`` and ``${B}`` before the ``do_deploy`` task runs, and - also sets the current working directory of ``do_deploy`` to ``${B}``. + ``${DEPLOYDIR}`` and ``${B}`` before the :ref:`ref-tasks-deploy` task runs, and + also sets the current working directory of :ref:`ref-tasks-deploy` to ``${B}``. For more information, see the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags`" section in the BitBake User Manual. diff --git a/documentation/ref-manual/tasks.rst b/documentation/ref-manual/tasks.rst index 8cffbb16c8..f47a30e467 100644 --- a/documentation/ref-manual/tasks.rst +++ b/documentation/ref-manual/tasks.rst @@ -81,7 +81,7 @@ Recipes implementing this task should inherit the :ref:`deploy ` class and should write the output to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be confused with ``${DEPLOY_DIR}``. The :ref:`deploy ` class sets up -``do_deploy`` as a shared state (sstate) task that can be accelerated +:ref:`ref-tasks-deploy` as a shared state (sstate) task that can be accelerated through sstate use. The sstate mechanism takes care of copying the output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. @@ -90,14 +90,14 @@ output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. Do not write the output directly to ``${DEPLOY_DIR_IMAGE}``, as this causes the sstate mechanism to malfunction. -The ``do_deploy`` task is not added as a task by default and +The :ref:`ref-tasks-deploy` task is not added as a task by default and consequently needs to be added manually. If you want the task to run after :ref:`ref-tasks-compile`, you can add it by doing the following:: addtask deploy after do_compile -Adding ``do_deploy`` after other tasks works the same way. +Adding :ref:`ref-tasks-deploy` after other tasks works the same way. .. note:: @@ -110,7 +110,7 @@ Adding ``do_deploy`` after other tasks works the same way. See the ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" section in the BitBake User Manual for more information. -If the ``do_deploy`` task re-executes, any previous output is removed +If the :ref:`ref-tasks-deploy` task re-executes, any previous output is removed (i.e. "cleaned"). .. _ref-tasks-fetch: diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index c6d058661a..00156cee94 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -6754,7 +6754,7 @@ system and gives an overview of their function and contents. - do_populate_lic - do_package_qa - do_populate_sysroot - - do_deploy + - :ref:`ref-tasks-deploy` Despite the default value of "" for the :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added -- cgit v1.2.3-54-g00ecf