doc: ref manual: document {HOST_, CROSS_, EXTRA_, }PACKAGES{-y, -m, } variables

Some of them are already mentioned in the developer manual part, but it
makes sense to have all of them in the reference too.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>

2 files changed, 27 insertions, 0 deletions

diff --git a/doc/multi_image_platforms.inc b/doc/multi_image_platforms.inc
index 2010f1262..a90393839 100644
--- a/doc/multi_image_platforms.inc
+++ b/doc/multi_image_platforms.inc
@@ -28,6 +28,8 @@ how to create a new package.
 .. note:: PTXdist looks in ``patches/$(<PKG>)`` for the patches. Symlinks
   can be uses to share the patch stack across multiple bootloader packages.
 
+.. _multi_image_individual_root_filesystems:
+
 Creating Individual Root-Filesystems for each Variant
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index 74bf84b5c..e1e14f746 100644
--- a/doc/ref_manual.rst
+++ b/doc/ref_manual.rst
@@ -105,6 +105,31 @@ Other useful variables:
   ``PTXDIST_PLATFORMDIR`` points to the directory build tree of the
   currently selected platform.
 
+``PACKAGES``, ``PACKAGES-y``, ``PACKAGES-m``
+  ``PACKAGES`` is a list of space-separated lowercase package names that are
+  built and installed during the PTXdist build run, and installed into the
+  target root filesystem when building images.
+
+  The ``-y`` variant contains only those packages that are selected with
+  ``PTXCONF_<PKG>=y``, while the ``-m`` variant contains only those which are
+  selected with ``PTXCONF_<PKG>=m`` (used for collections).
+  A target package rule usually adds its name to one of those variables if it
+  has been selected.
+  The union of those two sets then ends up in ``PACKAGES``.
+
+``EXTRA_PACKAGES``, ``EXTRA_PACKAGES-y``, ``EXTRA_PACKAGES-m``
+  In analogy to ``PACKAGES``, target packages that are added to these lists will
+  be built normally during the build run.
+  In contrast however, they are not installed into a root filesystem by default
+  when building images, and image rules must request them explicitely.
+  This is useful for specialized packages that are only needed for specific
+  images, see :ref:`multi_image_individual_root_filesystems`.
+
+``HOST_PACKAGES``, ``CROSS_PACKAGES``
+  Similar to ``PACKAGES``, these variables contain the host and cross packages
+  that are built and installed during the PTXdist build run.
+  There are analogous ``-y`` and ``-m`` variants of those variables too.
+
 Package Specific Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~