pattern rules example (was: Makefile to Makefile.am)

[Ralf Wildenhues]

[ automake-patches@ added; followups can drop automake@ ]

Hello Thien-Thi,

* Thien-Thi Nguyen wrote on Mon, Aug 16, 2010 at 02:22:31AM CEST:
> () Ralf Wildenhues
> () Sun, 15 Aug 2010 23:32:44 +0200
> 
>    Yes, with a general example, please.
> 
> I am unsure what "general example" means, precisely, so
> the patch below simply uses the one in The GNU Make Manual.
> Is that ok?

The explanation is good, but there are a couple of reasons I'd prefer a
slightly different example: first, automake already generates rules for
compiling .c sources by itself, so this example should never be needed
for Automake users; then, the automake-generated rules are slightly
different: $(CPPFLAGS) come before $(CFLAGS), there are also the AM_*
or per-target flags, and .o might be .obj, giving rise to $(OBJEXT).

Further, there is the SUFFIXES variable to which suffixes should be
added when they are not of the default form.

Can we find a transformation that is known to most readers, not already
done by automake, general enough to be portable, and short enough to
serve as a quick example?  If a real-world one can't be found, then we
can still use a fake .foo -> .bar one.

Then, the placement of the description isn't optimal.  The "Multiple
Outputs" node is specifically about creating multiple output files with
a single rule.  A pattern example would better fit in the "Suffixes"
node; a cross reference from the "Multiple Outputs" node is a good idea
though, as in "see @ref{...} for more discussion of pattern rules".

Thanks,
Ralf

> Subject: [PATCH] Document a common conversion for GNU make pattern rules.
> 
> * doc/automake.texi (Multiple Outputs): Expand on GNU make
> pattern rules; explain how to convert a common case to use
> old-fashioned suffix rules; add simple example, xref.

> --- a/doc/automake.texi
> +++ b/doc/automake.texi
> @@ -11525,11 +11525,31 @@ @node Multiple Outputs
>  @c $$
>  
>  For completeness it should be noted that GNU @command{make} is able to
> -express rules with multiple output files using pattern rules
> -(@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
> -Manual}).  We do not discuss pattern rules here because they are not
> -portable, but they can be convenient in packages that assume GNU
> address@hidden
> +express rules with multiple output files using pattern rules.
> +Although pattern rules are not portable, they can be
> +convenient in packages that assume GNU @command{make}.
> address@hidden Examples, , Pattern Rule Examples, make, The GNU Make
> +Manual}.
> +
> +In the common case where the @samp{%} in the pattern rule is used to
> +match the stem of a filename, and the prerequisite and target differ
> +only in the filename extension, you can use the old fashioned suffix
> +rule instead.  For example:
> +
> address@hidden
> +# pattern rule, not portable
> +%.o : %.c
> +        $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
> +
> +# old fashioned suffix rule, portable
> +.c.o:
> +        $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
> address@hidden example
> +
> +Take care, when converting from pattern rule syntax to suffix rule
> +syntax, to place the prerequisite extension @file{.c} before that
> +of the target extension @file{.o}.
> address@hidden Rules, , Old-Fashioned Suffix Rule, make, The GNU Make Manual}.