[ptxdist] [PATCH 1/4] doc: ref_make_macros: improve world/image-clean documentation

[ptxdist] [PATCH 1/4] doc: ref_make_macros: improve world/image-clean documentation

[Roland Hieber]

Improve the phrasing that the default clean stage already calls
world/image-clean, then order the macros alphabetically like in the
section header as well as the order in which they are usually called.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/ref_make_macros.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/ref_make_macros.rst b/doc/ref_make_macros.rst
index fe300c45757a..a81d54961298 100644
--- a/doc/ref_make_macros.rst
+++ b/doc/ref_make_macros.rst
@@ -155,19 +155,15 @@ Usage:
 
 .. code-block:: none
 
- @$(call world/image-clean, <PKG>)
  @$(call ptx/image-install, <PKG>, $(<PKG>_BUILD_DIR)/<source-image-name>[, <image-name>])
  @$(call ptx/image-install-link, <PKG>, <link-target>, <link-name>)
+ @$(call world/image-clean, <PKG>)
 
 These macros are used to install files to ``|ptxdistPlatformDir|/images``.
 They are only allowed in the *targetinstall* stage. They are used by
 packages that produce files that are not part of a filesystem. Bootloaders
 are typical packages that do this.
 
-``world/image-clean`` will remove the files that were created by the other
-two macros in a previous run of the *targetinstall* stage. This also
-happens implicitly when the package is cleaned.
-
 ``ptx/image-install`` copies a file. The source must be an absolute path.
 The destination must be relative to the image directory. If the destination
 file name is the source file without the path, then this argument can be
@@ -175,6 +171,10 @@ omitted.
 
 ``ptx/image-install-link`` creates a symlink in the image directory.
 
+``world/image-clean`` will remove the files that were created by the other
+two macros in a previous run of the *targetinstall* stage. This macro is also
+called automatically by PTXdist's default *clean* stage.
+
 .. _world_image_fit:
 
 world/image-fit
-- 
2.39.2

[ptxdist] [PATCH 2/4] docs: ref_rule_file_layout: document default clean stage

[Roland Hieber]

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/ref_rule_file_layout.rst | 37 ++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

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
 ~~~~~~~~~~~~~~~~
 
-- 
2.39.2

[ptxdist] [PATCH 3/4] doc: conf.py: replace 'versatilepb' with example placeholder

[Roland Hieber]

The platform is the last placeholder referring to a specific name, which
regularly seems to confuse people that are new to PTXdist. Replace it by
a more expressive placeholder marking its example status, unless a more
specific platform name can be used from PTXCONF_PLATFORM.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 49d19965f8e8..b1a6fe3293b6 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -114,7 +114,7 @@ try:
 except:
 	toolchain = "/opt/OSELAS.Toolchain-2022.10.0/arm-v7a-linux-gnueabihf/gcc-12.2.1-clang-15.0.2-glibc-2.36-binutils-2.39-kernel-6.0.5-sanitized/bin".split("/")
 
-ptxdistPlatformName = os.getenv("PTXCONF_PLATFORM", "versatilepb")
+ptxdistPlatformName = os.getenv("PTXCONF_PLATFORM", "example")
 ptxdistPlatformDir = "platform-" + ptxdistPlatformName
 oselasTCNarch = gnu_target.split("-")[0]
 oselasTCNvariant = gnu_target.split("-")[1]
@@ -127,7 +127,7 @@ ptxdistBSPName = "OSELAS.BSP-" + ptxdistHwVendor + "-" + ptxdistHwProduct + os.g
 ptxdistBSPRevision = os.getenv("PTXDIST_BSP_AUTOVERSION", "???")
 ptxdistCompilerName = gnu_target
 ptxdistCompilerVersion = toolchain[-2]
-ptxdistPlatformConfigDir = os.path.basename(os.getenv("PTXDIST_PLATFORMCONFIGDIR")) if os.getenv("PTXDIST_PLATFORMCONFIGDIR") != os.getenv("PTXDIST_TOPDIR") else "platform-versatilepb"
+ptxdistPlatformConfigDir = os.path.basename(os.getenv("PTXDIST_PLATFORMCONFIGDIR")) if os.getenv("PTXDIST_PLATFORMCONFIGDIR") != os.getenv("PTXDIST_TOPDIR") else "platform-<example>"
 ptxdistPlatformCollection = "\ "
 ptxdistVendorVersion = os.getenv("PTXDIST_VERSION_YEAR") + "." + os.getenv("PTXDIST_VERSION_MONTH") + "." + os.getenv("PTXDIST_VERSION_BUGFIX")
 package = "<package>"
-- 
2.39.2

[ptxdist] [PATCH 4/4] doc: conf.py: update default toolchain version

[Roland Hieber]

Update it to the current version.

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 doc/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/conf.py b/doc/conf.py
index b1a6fe3293b6..9936c4f0dacc 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -112,7 +112,7 @@ gnu_target = os.getenv("PTXCONF_GNU_TARGET") or "arm-v7a-linux-gnueabihf"
 try:
 	toolchain = os.readlink(os.path.join(os.getenv("PTXDIST_PLATFORMDIR",""), "selected_toolchain")).split("/")
 except:
-	toolchain = "/opt/OSELAS.Toolchain-2022.10.0/arm-v7a-linux-gnueabihf/gcc-12.2.1-clang-15.0.2-glibc-2.36-binutils-2.39-kernel-6.0.5-sanitized/bin".split("/")
+	toolchain = "/opt/OSELAS.Toolchain-2023.07.1/arm-v7a-linux-gnueabihf/gcc-13.2.1-clang-16.0.6-glibc-2.37-binutils-2.40-kernel-6.3.6-sanitized/bin".split("/")
 
 ptxdistPlatformName = os.getenv("PTXCONF_PLATFORM", "example")
 ptxdistPlatformDir = "platform-" + ptxdistPlatformName
-- 
2.39.2

Re: [ptxdist] [APPLIED] doc: ref_make_macros: improve world/image-clean documentation

[Michael Olbrich]

Thanks, applied as 7242b87b98e2f4f1503ae72c28b481da4812a567.

Michael

[sent from post-receive hook]

On Thu, 12 Sep 2024 14:11:37 +0200, Roland Hieber <rhi@pengutronix.de> wrote:
> Improve the phrasing that the default clean stage already calls
> world/image-clean, then order the macros alphabetically like in the
> section header as well as the order in which they are usually called.
> 
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20240808094035.1636229-1-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> diff --git a/doc/ref_make_macros.rst b/doc/ref_make_macros.rst
> index fe300c45757a..a81d54961298 100644
> --- a/doc/ref_make_macros.rst
> +++ b/doc/ref_make_macros.rst
> @@ -155,19 +155,15 @@ Usage:
>  
>  .. code-block:: none
>  
> - @$(call world/image-clean, <PKG>)
>   @$(call ptx/image-install, <PKG>, $(<PKG>_BUILD_DIR)/<source-image-name>[, <image-name>])
>   @$(call ptx/image-install-link, <PKG>, <link-target>, <link-name>)
> + @$(call world/image-clean, <PKG>)
>  
>  These macros are used to install files to ``|ptxdistPlatformDir|/images``.
>  They are only allowed in the *targetinstall* stage. They are used by
>  packages that produce files that are not part of a filesystem. Bootloaders
>  are typical packages that do this.
>  
> -``world/image-clean`` will remove the files that were created by the other
> -two macros in a previous run of the *targetinstall* stage. This also
> -happens implicitly when the package is cleaned.
> -
>  ``ptx/image-install`` copies a file. The source must be an absolute path.
>  The destination must be relative to the image directory. If the destination
>  file name is the source file without the path, then this argument can be
> @@ -175,6 +171,10 @@ omitted.
>  
>  ``ptx/image-install-link`` creates a symlink in the image directory.
>  
> +``world/image-clean`` will remove the files that were created by the other
> +two macros in a previous run of the *targetinstall* stage. This macro is also
> +called automatically by PTXdist's default *clean* stage.
> +
>  .. _world_image_fit:
>  
>  world/image-fit

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

[Michael Olbrich]

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
>  ~~~~~~~~~~~~~~~~
>  

Re: [ptxdist] [APPLIED] doc: conf.py: replace 'versatilepb' with example placeholder

[Michael Olbrich]

Thanks, applied as 8c01cc58de694e420d21949c74bc2eecc14b5828.

Michael

[sent from post-receive hook]

On Thu, 12 Sep 2024 14:11:38 +0200, Roland Hieber <rhi@pengutronix.de> wrote:
> The platform is the last placeholder referring to a specific name, which
> regularly seems to confuse people that are new to PTXdist. Replace it by
> a more expressive placeholder marking its example status, unless a more
> specific platform name can be used from PTXCONF_PLATFORM.
> 
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20240808094035.1636229-3-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> diff --git a/doc/conf.py b/doc/conf.py
> index 49d19965f8e8..b1a6fe3293b6 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -114,7 +114,7 @@ try:
>  except:
>  	toolchain = "/opt/OSELAS.Toolchain-2022.10.0/arm-v7a-linux-gnueabihf/gcc-12.2.1-clang-15.0.2-glibc-2.36-binutils-2.39-kernel-6.0.5-sanitized/bin".split("/")
>  
> -ptxdistPlatformName = os.getenv("PTXCONF_PLATFORM", "versatilepb")
> +ptxdistPlatformName = os.getenv("PTXCONF_PLATFORM", "example")
>  ptxdistPlatformDir = "platform-" + ptxdistPlatformName
>  oselasTCNarch = gnu_target.split("-")[0]
>  oselasTCNvariant = gnu_target.split("-")[1]
> @@ -127,7 +127,7 @@ ptxdistBSPName = "OSELAS.BSP-" + ptxdistHwVendor + "-" + ptxdistHwProduct + os.g
>  ptxdistBSPRevision = os.getenv("PTXDIST_BSP_AUTOVERSION", "???")
>  ptxdistCompilerName = gnu_target
>  ptxdistCompilerVersion = toolchain[-2]
> -ptxdistPlatformConfigDir = os.path.basename(os.getenv("PTXDIST_PLATFORMCONFIGDIR")) if os.getenv("PTXDIST_PLATFORMCONFIGDIR") != os.getenv("PTXDIST_TOPDIR") else "platform-versatilepb"
> +ptxdistPlatformConfigDir = os.path.basename(os.getenv("PTXDIST_PLATFORMCONFIGDIR")) if os.getenv("PTXDIST_PLATFORMCONFIGDIR") != os.getenv("PTXDIST_TOPDIR") else "platform-<example>"
>  ptxdistPlatformCollection = "\ "
>  ptxdistVendorVersion = os.getenv("PTXDIST_VERSION_YEAR") + "." + os.getenv("PTXDIST_VERSION_MONTH") + "." + os.getenv("PTXDIST_VERSION_BUGFIX")
>  package = "<package>"

Re: [ptxdist] [APPLIED] doc: conf.py: update default toolchain version

[Michael Olbrich]

Thanks, applied as f1161b95a536551c905047d0356ddcf2260282c0.

Michael

[sent from post-receive hook]

On Thu, 12 Sep 2024 14:11:39 +0200, Roland Hieber <rhi@pengutronix.de> wrote:
> Update it to the current version.
> 
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20240808094035.1636229-4-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> diff --git a/doc/conf.py b/doc/conf.py
> index b1a6fe3293b6..9936c4f0dacc 100644
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -112,7 +112,7 @@ gnu_target = os.getenv("PTXCONF_GNU_TARGET") or "arm-v7a-linux-gnueabihf"
>  try:
>  	toolchain = os.readlink(os.path.join(os.getenv("PTXDIST_PLATFORMDIR",""), "selected_toolchain")).split("/")
>  except:
> -	toolchain = "/opt/OSELAS.Toolchain-2022.10.0/arm-v7a-linux-gnueabihf/gcc-12.2.1-clang-15.0.2-glibc-2.36-binutils-2.39-kernel-6.0.5-sanitized/bin".split("/")
> +	toolchain = "/opt/OSELAS.Toolchain-2023.07.1/arm-v7a-linux-gnueabihf/gcc-13.2.1-clang-16.0.6-glibc-2.37-binutils-2.40-kernel-6.3.6-sanitized/bin".split("/")
>  
>  ptxdistPlatformName = os.getenv("PTXCONF_PLATFORM", "example")
>  ptxdistPlatformDir = "platform-" + ptxdistPlatformName