[ptxdist] [PATCH] doc: mention dedicated PTXdist macros to be used in rule files

[ptxdist] [PATCH] doc: mention dedicated PTXdist macros to be used in rule files

[Juergen Borleis]

In order to simplify rule files, it's worth to use more of the provided
rule file macros PTXdist already provides.

Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
---
 doc/dev_manual.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
index f0c2e00ee..984e91cd4 100644
--- a/doc/dev_manual.rst
+++ b/doc/dev_manual.rst
@@ -909,6 +909,23 @@ file and add the correct parameters:
 .. important:: Please note the trailing ``PTXCONF_`` for each define. While Kconfig is
   using ``FOO_BAR``, the rule file must use ``PTXCONF_FOO_BAR`` instead.
 
+This kind of rule file style is sometimes error prone and hard to read. There
+is a simpler way available to handle these build-time options. PTXdist
+provides some macros to unify and simplify creating these options on demand.
+Using these macros makes the rule file looks like instead:
+
+.. code-block:: make
+
+    #
+    # autoconf
+    #
+    FOO_CONF_OPT := $(CROSS_AUTOCONF_USR) \
+        --$(call ptx/endis, PTXCONF_FOO_DEBUG)-debug \
+        --$(call ptx/wwo, PTXCONF_FOO_BAR)-bar
+
+Refer :ref:`Rule File Macro Reference <param_macros>` for further details about
+these kind of macros.
+
 It is a good practice to add both settings, e.g. ``--disable-debug``
 even if this is the default case. Sometimes ``configure`` tries to guess
 something and the binary result might differ depending on the build
-- 
2.11.0


_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH] doc: mention dedicated PTXdist macros to be used in rule files

[Michael Olbrich]

On Fri, Feb 22, 2019 at 11:30:06AM +0100, Juergen Borleis wrote:
> In order to simplify rule files, it's worth to use more of the provided
> rule file macros PTXdist already provides.
> 
> Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
> ---
>  doc/dev_manual.rst | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
> index f0c2e00ee..984e91cd4 100644
> --- a/doc/dev_manual.rst
> +++ b/doc/dev_manual.rst
> @@ -909,6 +909,23 @@ file and add the correct parameters:
>  .. important:: Please note the trailing ``PTXCONF_`` for each define. While Kconfig is

Not about your change, but I think 'trailing' is the wrong word here. Maybe
something with 'prefix'? Other ideas?

>    using ``FOO_BAR``, the rule file must use ``PTXCONF_FOO_BAR`` instead.
>  
> +This kind of rule file style is sometimes error prone and hard to read. There

I think we should rewrite the code block above instead.

> +is a simpler way available to handle these build-time options. PTXdist
> +provides some macros to unify and simplify creating these options on demand.
> +Using these macros makes the rule file looks like instead:
> +
> +.. code-block:: make
> +
> +    #
> +    # autoconf
> +    #
> +    FOO_CONF_OPT := \
	$(CROSS_AUTOCONF_USR) \

Breaking lines like this is recommend.

Michael

> +        --$(call ptx/endis, PTXCONF_FOO_DEBUG)-debug \
> +        --$(call ptx/wwo, PTXCONF_FOO_BAR)-bar
> +
> +Refer :ref:`Rule File Macro Reference <param_macros>` for further details about
> +these kind of macros.
> +
>  It is a good practice to add both settings, e.g. ``--disable-debug``
>  even if this is the default case. Sometimes ``configure`` tries to guess
>  something and the binary result might differ depending on the build
> -- 
> 2.11.0
> 
> 
> _______________________________________________
> ptxdist mailing list
> ptxdist@pengutronix.de

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de

Re: [ptxdist] [PATCH] doc: mention dedicated PTXdist macros to be used in rule files

[Juergen Borleis]

Hi Michael,

On Friday 22 February 2019 12:42:47 Michael Olbrich wrote:
> > In order to simplify rule files, it's worth to use more of the provided
> > rule file macros PTXdist already provides.
> >
> > Signed-off-by: Juergen Borleis <jbe@pengutronix.de>
> > ---
> >  doc/dev_manual.rst | 17 +++++++++++++++++
> >  1 file changed, 17 insertions(+)
> >
> > diff --git a/doc/dev_manual.rst b/doc/dev_manual.rst
> > index f0c2e00ee..984e91cd4 100644
> > --- a/doc/dev_manual.rst
> > +++ b/doc/dev_manual.rst
> > @@ -909,6 +909,23 @@ file and add the correct parameters:
> >  .. important:: Please note the trailing ``PTXCONF_`` for each define.
> > While Kconfig is
>
> Not about your change, but I think 'trailing' is the wrong word here.
> Maybe something with 'prefix'? Other ideas?

Arrgh, "leading" I meant... m(

Will send a V2.

jb

-- 
Pengutronix e.K.                             | Juergen Borleis             |
Industrial Linux Solutions                   | http://www.pengutronix.de/  |

_______________________________________________
ptxdist mailing list
ptxdist@pengutronix.de