ref-manual: variables: document IMGDEPLOYDIR

DEPLOY_DIR_IMAGE has been replaced by IMGDEPLOYDIR for most use cases
since OE-Core rev 6d969bacc718e21a5246d4da9bf9639dcae29b02. Document
IMGDEPLOYDIR and add a note to DEPLOY_DIR_IMAGE about it.

(From yocto-docs rev: dad7046f9428bde476d2241209c118d52529bed5)

Signed-off-by: Daniel Wagenknecht <dwagenknecht@emlix.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Reviewed-by: Nicolas Dechesne <nicolas.dechesne@linaro.org>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

documentation/ref-manual/variables.rst

@@ -1673,6 +1673,13 @@ system and gives an overview of their function and contents.
       resides within the :term:`Build Directory` as
       ``${DEPLOY_DIR}/images/${MACHINE}/``.
 
+      It must not be used directly in recipes when deploying files. Instead,
+      it's only useful when a recipe needs to "read" a file already deployed
+      by a dependency. So, it should be filled with the contents of
+      :term:`DEPLOYDIR` by the :ref:`deploy <ref-classes-deploy>` class or
+      with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image
+      <ref-classes-image>` class.
+
       For more information on the structure of the Build Directory, see
       ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section.
       For more detail on the contents of the ``deploy`` directory, see the
@@ -3324,6 +3331,18 @@ system and gives an overview of their function and contents.
       desired, and this suffix would then be used consistently across
       the build artifacts.
 
+   :term:`IMGDEPLOYDIR`
+      When inheriting the :ref:`image <ref-classes-image>` class directly or
+      through the :ref:`core-image <ref-classes-core-image>` class, the
+      ``IMGDEPLOYDIR`` points to a temporary work area for deployed files
+      that is set in the ``image`` class as follows::
+
+         IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
+
+      Recipes inheriting the ``image`` class should copy files to be
+      deployed into ``IMGDEPLOYDIR``, and the class will take care of
+      copying them into :term:`DEPLOY_DIR_IMAGE` afterwards.
+
    :term:`INC_PR`
       Helps define the recipe revision for recipes that share a common
       ``include`` file. You can think of this variable as part of the