diff mbox series

[06/30] manuals: add references to the "do_deploy" task

Message ID 20220923175219.6652-7-michael.opdenacker@bootlin.com
State New
Headers show
Series manuals: add missing references to tasks | expand

Commit Message

Michael Opdenacker Sept. 23, 2022, 5:51 p.m. UTC
From: Michael Opdenacker <michael.opdenacker@bootlin.com>

[YOCTO #14508]
Reported-by: Quentin Schulz <foss@0leil.net>
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 .../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(-)

Comments

Quentin Schulz Sept. 26, 2022, 1:40 p.m. UTC | #1
Hi Michael,

On 9/23/22 19:51, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> [YOCTO #14508]
> Reported-by: Quentin Schulz <foss@0leil.net>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>   .../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 8a8d19d605..4c0de7b0f6 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 <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.
> +:ref:`ref-tasks-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.
> +Most recipes and classes that inherit the :ref:`deploy <ref-classes-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 <ref-classes-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

You missed one here.

Cheers,
Quentin
Quentin Schulz Sept. 26, 2022, 2:04 p.m. UTC | #2
Hi Michael,

On 9/23/22 19:51, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> [YOCTO #14508]
> Reported-by: Quentin Schulz <foss@0leil.net>
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---

Missing one:
https://git.yoctoproject.org/yocto-docs/tree/documentation/migration-guides/migration-3.2.rst#n210

Cheers,
Quentin

>   .../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 8a8d19d605..4c0de7b0f6 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 <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.
> +:ref:`ref-tasks-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.
> +Most recipes and classes that inherit the :ref:`deploy <ref-classes-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 <ref-classes-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 <ref-classes-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 e5938ee236..5efe64b35d 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 <ref-classes-deploy>` class and should write the output
>   to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be
>   confused with ``${DEPLOY_DIR}``. The :ref:`deploy <ref-classes-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 8055f044d0..8fac7f77ad 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -6712,7 +6712,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
> 
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#3221): https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.yoctoproject.org_g_docs_message_3221&d=DwIFaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=F4I8M4SGcdazHCULA4b6vl9pU2JK4-B0XBUvtEqEX2ylNswIzUdWZ3CCfiIiibuD&s=ZEyJmQPpQCxzN0I8nTIITQMrc8SiUNh09KC0AxVJhp0&e=
> Mute This Topic: https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.yoctoproject.org_mt_93876107_6293953&d=DwIFaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=F4I8M4SGcdazHCULA4b6vl9pU2JK4-B0XBUvtEqEX2ylNswIzUdWZ3CCfiIiibuD&s=BFZheqvjA3rsYQi2OpLkymqO-SSiALZOk8nJIzBDmOI&e=
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.yoctoproject.org_g_docs_unsub&d=DwIFaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=F4I8M4SGcdazHCULA4b6vl9pU2JK4-B0XBUvtEqEX2ylNswIzUdWZ3CCfiIiibuD&s=euGgllMDt11J4RgqDdpdhWuZkm2IFiAUyowdcsO3LWc&e=  [quentin.schulz@theobroma-systems.com]
> -=-=-=-=-=-=-=-=-=-=-=-
>
diff mbox series

Patch

diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst
index 8a8d19d605..4c0de7b0f6 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 <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.
+:ref:`ref-tasks-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.
+Most recipes and classes that inherit the :ref:`deploy <ref-classes-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 <ref-classes-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 <ref-classes-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 e5938ee236..5efe64b35d 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 <ref-classes-deploy>` class and should write the output
 to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be
 confused with ``${DEPLOY_DIR}``. The :ref:`deploy <ref-classes-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 8055f044d0..8fac7f77ad 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6712,7 +6712,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