Re: [ptxdist] [APPLIED] docs: ref_rule_file_layout: document default clean stage

[Michael Olbrich <m.olbrich@pengutronix.de>]

Thanks, applied as 598fc9c4fc327642d9cebe23347ceba1fa6b96ad.

Michael

[sent from post-receive hook]

On Thu, 12 Sep 2024 14:11:37 +0200, Roland Hieber <rhi@pengutronix.de> wrote:
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20240808094035.1636229-2-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> diff --git a/doc/ref_rule_file_layout.rst b/doc/ref_rule_file_layout.rst
> index 58f37b73da24..222ee46a7b29 100644
> --- a/doc/ref_rule_file_layout.rst
> +++ b/doc/ref_rule_file_layout.rst
> @@ -23,6 +23,8 @@ Each rule file provides PTXdist with the required steps (in PTXdist called
>  
>     - targetinstall.post
>  
> +7. clean
> +
>  .. note::
>  
>    Host, image and cross packages don't need to install anything in the target file system.
> @@ -255,6 +257,41 @@ targetinstall.post Stage Default Rule
>  The *targetinstall.post* stage does nothing by default. It can be used to
>  do some work after the *targetinstall* stage.
>  
> +clean Stage Default Rule
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The *clean* stage is only executed when calling ``ptxdist clean <package>``.
> +
> +The default *clean* stage calls the *world/clean* macro:
> +
> +.. code-block:: make
> +
> +    $(STATEDIR)/<pkg>.clean:
> +    	@$(call targetinfo)
> +    	@$(call world/clean, <PKG>)
> +
> +This will invalidate all stages of the package, and remove all its existing
> +build artefacts:
> +
> +* ``<PKG>_DIR``, and ``$(<PKG>_DIR)-build`` for out-of-tree builds,
> +* ``<PKG>_PKGDIR`` (i.e., usually ``$(PKGDIR)/$(<PKG>)``)
> +* the pre-built archive in ``PKGDIR`` (if enabled)
> +* the files that the package has installed into the respective sysroot folder
> +  (``|ptxdistPlatformDir|/sysroot-{target,host,cross}/``),
> +* for target packages, any output of the package's *targetinstall* stage built
> +  by the following macros:
> +
> +   - opkg packages defined by *install_init* and *install_finish*,
> +   - any files installed into the target root file system
> +     (``|ptxdistPlatformDir|/root/``) via *install_copy*, *install_glob*,
> +     *install_alternative*, *install_tree* and similar,
> +   - images installed to the image directory by *ptx/install-image* and
> +     *ptx/install-image-link*
> +
> +It will not remove any input files like patches or downloaded sources or config
> +files, nor will it remove any :ref:`pre-built archives <devpkgs>` from
> +``PTXCONF_PROJECT_DEVPKGDIR``.
> +
>  Skipping a Stage
>  ~~~~~~~~~~~~~~~~
>