doc: fix and improve rule file documentation

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

1 files changed, 134 insertions, 92 deletions

diff --git a/doc/ref_manual.rst b/doc/ref_manual.rst
index 024737a61..2391982d2 100644
--- a/doc/ref_manual.rst
+++ b/doc/ref_manual.rst
@@ -323,6 +323,8 @@ Prepare Stage
   All other configuration tools have no default options. This variable is
   ignored for kconfig and python/python3.
 
+.. _vars_compile:
+
 Compile Stage
 ^^^^^^^^^^^^^
 
@@ -332,7 +334,8 @@ Compile Stage
   necessary defines are picked up in the prepare stage. For python/python3
   packages PTXdist will use the default value from ``<PKG>_CONF_ENV``.
   For packages without configuration tool this must be set correctly,
-  usually based on the ``<PKG>_CONF_ENV`` default values.
+  usually based on the ``<PKG>_CONF_ENV`` default values, e,g.
+  ``$(CROSS_ENV)`` for target packages.
 
 ``<PKG>_MAKE_OPT``
   This variables defines additional parameters to be forwarded to ``make`` in
@@ -343,7 +346,9 @@ Compile Stage
   This variables informs PTXdist, if this package can be built in parallel. Some
   (mostly very smart selfmade) buildsystems fail doing so. In this case this
   variable can be set to ``NO``. PTXdist will then build this package with one
-  CPU only.
+  CPU only. The default is, to build packages in parallel.
+
+.. _vars_install:
 
 Install Stage
 ^^^^^^^^^^^^^
@@ -353,10 +358,19 @@ Install Stage
   It can be overwritten if the package needs a special target to install its
   results.
 
+.. _pkg_pkgdir:
+
+``<PKG>_PKGDIR``
+  This variable must not be set by the user. It defines package
+  install directory. All files will be installed relative to this
+  directory. It can be used by manual install stages. It is defined as
+  ``$(PKGDIR)/$(<PKG>)`` which expands to
+  ``<platform-dir>/packages/foo-1.1.0`` on our *foo* example.
+
 Targetinstall Stage
 ^^^^^^^^^^^^^^^^^^^
 
-TBD
+The *targetinstall* stage has no additional variables.
 
 .. _image_packages:
 
@@ -528,14 +542,14 @@ The ``<source>`` parameter can be:
   of the target's filesystem.
 * an absolute path to a file that should be copied to the target's root
   filesystem. To avoid fixed paths, all packages are providing the
-  <package> _DIR variable. So, this parameter in our
+  <PKG>_DIR variable. So, this parameter in our
   *foo* example package can be a ``$(FOO_DIR)/foo``.
 * a minus sign (``-``). PTXdist uses the <destination>
-  parameter in this case to locate the file to copy from. This only works
-  if the package uses the default *install* stage. Only in this
-  case an additional folder in ``<platform-dir>/packages`` will
-  be created for the package and its files. For our *foo* example
-  package this directory is ``<platform-dir>/packages/foo-1.1.0``.
+  parameter in this case to locate the file to copy from. 
+  The <destination> is uses a path relative to the :ref:`package install
+  directory<pkg_pkgdir>`. This only works if the package uses the default
+  or a similar *install* stage.  For our *foo* example used source file is
+  ``<platform-dir>/packages/foo-1.1.0/<destination>``.
 
 The ``<dest>`` parameter can be:
 
@@ -1181,8 +1195,9 @@ Each rule file provides PTXdist with the required steps (in PTXdist called
 4. compile
 5. install
 
-   - install.post
    - install.pack
+   - install.unpack
+   - install.post
 
 6. targetinstall
 
@@ -1208,9 +1223,9 @@ If the *get* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/@package@.get:
-    		@$(call targetinfo)
-    		@$(call touch)
+    $(STATEDIR)/<pkg>.get:
+    	@$(call targetinfo)
+    	@$(call touch)
 
 Which means this step is skipped.
 
@@ -1219,9 +1234,9 @@ following rule must exist in this case:
 
 .. code-block:: make
 
-    $(@package@_SOURCE):
-    		@$(call targetinfo)
-		@$(call get, @package@)
+    $(<PKG>_SOURCE):
+    	@$(call targetinfo)
+    	@$(call get, <PKG>)
 
 extract Stage Default Rule
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1230,12 +1245,12 @@ If the *extract* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/@package@.extract:
-    		@$(call targetinfo)
-		@$(call clean, $(@package@_DIR))
-		@$(call extract, @package@)
-		@$(call patchin, @package@)
-    		@$(call touch)
+    $(STATEDIR)/<pkg>.extract:
+    	@$(call targetinfo)
+    	@$(call clean, $(<PKG>_DIR))
+    	@$(call extract, <PKG>)
+    	@$(call patchin, <PKG>)
+    	@$(call touch)
 
 Which means a current existing directory of this package will be
 removed, the archive gets freshly extracted again and (if corresponding
@@ -1255,62 +1270,65 @@ autotoolized PTXdist templates makes use of this feature. Refer
 prepare Stage Default Rule
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If the *prepare* stage is omitted, PTXdist runs a default stage rule
-depending on some variable settings.
+If the *prepare* stage is omitted, PTXdist runs a default stage rule,
+which looks like this:
 
-If the package’s rule file defines ``@package@_CONF_TOOL`` to ``NO``,
-this stage is simply skipped.
+.. code-block:: make
 
-All rules files shall create the ``@package@_CONF_ENV`` variable and
-define it at least to ``$(CROSS_ENV)`` if the prepare stage is used.
+    $(STATEDIR)/<pkg>.prepare:
+    	@$(call targetinfo)
+    	@$(call world/prepare, <PKG>)
+    	@$(call touch)
 
-If the package’s rule file defines ``@package@_CONF_TOOL`` to
+What ``world/prepare`` does depends on some variable settings.
+
+If the package’s rule file defines ``<PKG>_CONF_TOOL`` to ``NO``,
+this stage is simply does nothing.
+
+All rules files can create the ``<PKG>_CONF_ENV`` variable and should
+define it at least to ``$(CROSS_ENV)`` (the default) if the prepare stage
+is used.
+
+If the package’s rule file defines ``<PKG>_CONF_TOOL`` to
 ``autoconf`` (``FOO_CONF_TOOL = autoconf`` for our *foo* example),
-PTXdist treats this package as an autotoolized package and runs:
+PTXdist treats this package as an autotoolized package and
+``world/prepare`` expands to something like this:
 
-.. code-block:: make
+.. code-block:: sh
 
-    $(STATEDIR)/@package@.prepare:
-    		@$(call targetinfo)
-		@$(call clean, $(@package@_DIR)/config.cache)
-		@cd $(@package@_DIR)/$(@package@_SUBDIR) && \
-			$(@package@_PATH) $(@package@_CONF_ENV) \
-			./configure $(@package@_CONF_OPT)
-    		@$(call touch)
+    cd ${<PKG>_DIR}/${<PKG>_SUBDIR} && \
+    	${<PKG>_PATH} ${<PKG>_CONF_ENV} \
+    	./configure ${<PKG>_CONF_OPT}
 
-The ``@package@_CONF_OPT`` should at least be defined to
-``$(CROSS_AUTOCONF_USR)`` or ``$(CROSS_AUTOCONF_ROOT)``.
+The ``<PKG>_CONF_OPT`` should at least be defined to
+``$(CROSS_AUTOCONF_USR)``.
 
-If the package’s rule file defines ``@package@_CONF_TOOL`` to ``cmake``
+If the package’s rule file defines ``<PKG>_CONF_TOOL`` to ``cmake``
 (``FOO_CONF_TOOL = cmake`` for our *foo* example), PTXdist treats this
-package as a *cmake* based package and runs:
+package as a *cmake* based package and ``world/prepare`` expands to
+something like this:
 
-.. code-block:: make
+.. code-block:: sh
 
-    $(STATEDIR)/@package@.prepare:
-    		@$(call targetinfo)
-		@cd $(@package@_DIR) && \
-			$(@package@_PATH) $(@package@_CONF_ENV) \
-			cmake $(@package@_CONF_OPT)
-    		@$(call touch)
+    cd ${<PKG>_DIR} && \
+    	${<PKG>_PATH} ${<PKG>_CONF_ENV} \
+    	cmake ${<PKG>_CONF_OPT}
 
-The ``@package@_CONF_OPT`` should at least be defined to
+The ``<PKG>_CONF_OPT`` should at least be defined to
 ``$(CROSS_CMAKE_USR)`` or ``$(CROSS_CMAKE_ROOT)``.
 
-If the package’s rule file defines ``@package@_CONF_TOOL`` to ``qmake``
+If the package’s rule file defines ``<PKG>_CONF_TOOL`` to ``qmake``
 (``FOO_CONF_TOOL = qmake`` for our *foo* example), PTXdist treats this
-package as a *qmake* based package and runs:
+package as a *qmake* based package and ``world/prepare`` expands to
+something like this:
 
-.. code-block:: make
+.. code-block:: sh
 
-    $(STATEDIR)/@package@.prepare:
-    		@$(call targetinfo)
-		@cd $(@package@_DIR) && \
-			$(@package@_PATH) $(@package@_CONF_ENV) \
-			qmake $(@package@_CONF_OPT)
-    		@$(call touch)
+    cd ${<PKG>_DIR} && \
+    	${<PKG>_PATH} ${<PKG>_CONF_ENV} \
+    	qmake ${<PKG>_CONF_OPT}
 
-The ``@package@_CONF_OPT`` should at least be defined to
+The ``<PKG>_CONF_OPT`` should at least be defined to
 ``$(CROSS_QMAKE_OPT)``.
 
 compile Stage Default Rule
@@ -1320,24 +1338,25 @@ If the *compile* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/@package@.compile:
-    		@$(call targetinfo)
-		@cd $(@package@_DIR) && \
-			$(@package@_PATH) $(@package@_MAKE_ENV) \
-			$(MAKE) $(@package@_MAKE_OPT) $(@package@_MAKE_PAR)
-    		@$(call touch)
+    $(STATEDIR)/<pkg>.compile:
+    	@$(call targetinfo)
+    	@$(call world/compile, <PKG>)
+    	@$(call touch)
 
-If some additional variables should be added to the ``@package@_MAKE_ENV``,
-always begin with the ``$(CROSS_ENV)`` and then add the additional
-variables.
+Except in some corner cases, ``world/compile`` expands to something like
+this:
 
-If the ``@package@_MAKE_OPT`` is intended for additional parameters to
-be forwarded to ``make`` or to overwrite some settings from the
-``@package@_MAKE_ENV``. If not defined in the rule file it defaults to
-an empty string.
+.. code-block:: sh
 
-Note: ``@package@_MAKE_PAR`` can be defined to ``YES`` or ``NO`` to
-control if the package can be built in parallel.
+    cd ${<PKG>_DIR} && \
+    	${<PKG>_PATH} ${<PKG>_MAKE_ENV} \
+    	${MAKE} ${<PKG>_MAKE_OPT} ${PARALLELMFLAGS}
+
+The variables that are used here are described in the :ref:`Compile
+Stage<vars_compile>` section of the variable reference.
+
+``PARALLELMFLAGS`` can be used in custom compile stages. The default stage
+uses the same value if ``<PKG>_MAKE_PAR`` is set to ``YES``.
 
 install Stage Default Rule
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1346,26 +1365,48 @@ If the *install* stage is omitted, PTXdist runs instead:
 
 .. code-block:: make
 
-    $(STATEDIR)/@package@.install:
-    		@$(call targetinfo)
-		@cd $(@package@_DIR) && \
-			$(@package@_PATH) $(@package@_MAKE_ENV) \
-			$(MAKE) $(@package@_INSTALL_OPT)
-    		@$(call touch)
+    $(STATEDIR)/<pkg>.install:
+    	@$(call targetinfo)
+    	@$(call world/install, <PKG>)
+    	@$(call touch)
 
-Note: ``@package@_INSTALL_OPT`` is always defined to ``install`` if not
-otherwise specified. This value can be replaced by a package’s rule file
-definition.
+Except in some corner cases, ``world/install`` expands to something like
+this:
 
-install.post Stage Default Rule
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. code-block:: sh
+
+    cd ${<PKG>_DIR} && \
+    	${<PKG>_PATH} ${<PKG>_MAKE_ENV} \
+    	${MAKE} ${<PKG>_INSTALL_OPT}
+
+The variables that are used here are described in the :ref:`Install
+Stage<vars_install>` section of the variable reference.
 
-TBD
+At the end of this stage, all relevant files must be installed in the
+:ref:`package install directory<pkg_pkgdir>`.
 
 install.pack Stage Default Rule
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-TBD
+The *install.pack* should not be overwritten. It consists of two steps. The
+first is, to make the installed files relocatable. This is necessary to
+ensure that everything works correctly once the files are copied to
+*sysroot* in *install.post*. If creating :ref:`pre-built archives<devpkgs>`
+is enabled, then the second step is to create the archive for the package.
+
+install.unpack Stage Default Rule
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *install.unpack* is only executed if using :ref:`pre-built
+archives<devpkgs>` is enabled. In this case, it replaces all previous
+stages. Here, the pre-built is extract.
+
+install.post Stage Default Rule
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *install.post* is mostly internal. Few packages need to customize it.
+It copies all files from the :ref:`package install directory<pkg_pkgdir>`
+into the corresponding *sysroot*.
 
 targetinstall Stage Default Rule
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1379,7 +1420,8 @@ root filesystem.
 targetinstall.post Stage Default Rule
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-TBD
+The *targetinstall.post* stage does nothing by default. It can be used to
+do some work after the *targetinstall* stage.
 
 Skipping a Stage
 ~~~~~~~~~~~~~~~~
@@ -1389,9 +1431,9 @@ be provided:
 
 .. code-block:: make
 
-    $(STATEDIR)/@package@.<stage_to_skip>:
-    		@$(call targetinfo)
-    		@$(call touch)
+    $(STATEDIR)/<pkg>.<stage_to_skip>:
+    	@$(call targetinfo)
+    	@$(call touch)
 
 Replace the <stage_to_skip> by ``get``, ``extract``, ``prepare``,
 ``compile``, ``install`` or ``targetinstall``.