GNU bug report logs - #9240
docs: give an example about use of `include'

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 4 Aug 2011 13:53:23 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Aug 04 09:53:23 2011
Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1QoyMV-0005Qy-F6
	for submit <at> debbugs.gnu.org; Thu, 04 Aug 2011 09:53:23 -0400
Received: from eggs.gnu.org ([140.186.70.92])
	by debbugs.gnu.org with esmtp (Exim 4.69)
	(envelope-from <stefano.lattarini@HIDDEN>) id 1QoyMS-0005Qp-0g
	for submit <at> debbugs.gnu.org; Thu, 04 Aug 2011 09:53:21 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <stefano.lattarini@HIDDEN>) id 1QoyLk-0007wq-4y
	for submit <at> debbugs.gnu.org; Thu, 04 Aug 2011 09:52:40 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00,FREEMAIL_FROM,
	RCVD_IN_DNSWL_LOW, T_DKIM_INVALID,
	T_TO_NO_BRKTS_FREEMAIL autolearn=unavailable version=3.3.1
Received: from lists.gnu.org ([140.186.70.17]:48617)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <stefano.lattarini@HIDDEN>) id 1QoyLk-0007wm-1W
	for submit <at> debbugs.gnu.org; Thu, 04 Aug 2011 09:52:36 -0400
Received: from eggs.gnu.org ([140.186.70.92]:55688)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <stefano.lattarini@HIDDEN>) id 1QoyLf-0003ZV-Dm
	for bug-automake@HIDDEN; Thu, 04 Aug 2011 09:52:35 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <stefano.lattarini@HIDDEN>) id 1QoyLd-0007vJ-Rs
	for bug-automake@HIDDEN; Thu, 04 Aug 2011 09:52:31 -0400
Received: from mail-wy0-f169.google.com ([74.125.82.169]:47342)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <stefano.lattarini@HIDDEN>)
	id 1QoyLZ-0007uq-TY; Thu, 04 Aug 2011 09:52:26 -0400
Received: by wyg36 with SMTP id 36so1572831wyg.0
	for <multiple recipients>; Thu, 04 Aug 2011 06:52:24 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;
	h=from:to:subject:date:user-agent:cc:references:in-reply-to
	:mime-version:content-type:content-transfer-encoding:message-id;
	bh=xC1KzkbTPf/mrChkkjtU6izTxkmg+JQffv2YjRyYXTY=;
	b=IPYlX9/m/F4uZXJ5+aDIu8tiFNxNPyvmKtQpZO1poMb7q4lKOT04Y6fRsfP7OfUp6B
	dCpDvQC2NRo2n0xTBQ/sjf1mhl6yRqNGDSlLxr3uehR7F+1/DIkJs8pnfEYd7YuYb80s
	qYXlxnf+QhjXm5SU1um/9UgeYR+fcZMYnkum0=
Received: by 10.227.32.136 with SMTP id c8mr757060wbd.7.1312465944668;
	Thu, 04 Aug 2011 06:52:24 -0700 (PDT)
Received: from bigio.localnet
	(host167-98-dynamic.20-79-r.retail.telecomitalia.it [79.20.98.167])
	by mx.google.com with ESMTPS id ff6sm1506416wbb.49.2011.08.04.06.52.21
	(version=TLSv1/SSLv3 cipher=OTHER);
	Thu, 04 Aug 2011 06:52:21 -0700 (PDT)
From: Stefano Lattarini <stefano.lattarini@HIDDEN>
To: automake@HIDDEN
Subject: Re: Implementing a plugin-like module
Date: Thu, 4 Aug 2011 15:52:12 +0200
User-Agent: KMail/1.13.3 (Linux/2.6.30-2-686; KDE/4.4.4; i686; ; )
References: <cone.1312425131.757181.12464.500@HIDDEN>
In-Reply-To: <cone.1312425131.757181.12464.500@HIDDEN>
MIME-Version: 1.0
Content-Type: Text/Plain;
  charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <201108041552.13271.stefano.lattarini@HIDDEN>
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3)
X-Received-From: 140.186.70.17
X-Spam-Score: -5.9 (-----)
X-Debbugs-Envelope-To: submit
Cc: Sam Varshavchik <mrsam@HIDDEN>, bug-automake@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.11
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -5.9 (-----)

Hello Sam.

On Thursday 04 August 2011, Sam Varshavchik wrote:
> I'm looking for a way to implement an optional plugin-like facility in  
> automake.
>
> Basically, take a stock distro installation of automake, then augment it  
> somehow so that automake would add my stuff into each Makefile.in file that  
> it generates from Makefile.am.
>
A quick workaround to obtain this behaviour is to write your custom/rules
defintion in a `.am' fragment in your source tree, and then include it
from all the Makefile.am files that need it:

  $ cat my-rules.am
  my_variable = ...
  .ctpl.c:
	# rules to create a C file from a template `.ctpl'.

  $ cat lib/Makefile.am
  include  $(top_srcdir)/my-rules.am
  ... [specific rules]

  $ cat src/Makefile.am
  include  $(top_srcdir)/my-rules.am
  ... [other specific rules]

Automake will take care of processing the contents of my-rules.am, and will
copy the result in all the Makefile.in files derived from the Makefile.am
files that include it.

This way, if you have to change your custom rules or definitions, you
will only have to do so in one place (i.e., in my-rules.am).

All of this is documented in the Automake manual (in a very concise way
though, so I can understand why you've missed it):
 <http://www.gnu.org/software/automake/manual/html_node/Include.html>

Maybe a polished version of my example above will make a nice
addition to the "Extending Automake Rules" section in the automake
manual ...  I'm adding bug-automake on CC: so that we won't forget
about the issue.

> My situation is that I'm installing a toolkit; a library, a part of which is  
> a code generator. Let's say that my code generator produces filename.H from  
> filename.tmpl.
> 
> I can always write out the rules explicitly, something like:
> 
> BUILT_SOURCES=filename.H
> 
> filename.H: filename.tmpl
>      # build rule that runs the code generator goes here
> 
> bin_PROGRAMS=app
> 
> app_SOURCES=appmain.C
> 
> # and appmain.C #includes filename.H
> 
> 
> Something like that. That's the basic scenario. What I would like to  
> accomplish is to have the actual build rules defined by the installed  
> toolkit. The build rules are somewhat non-trivial, and with many code- 
> generated .H files, it gets tedious. I'm fine with limiting my portability  
> to gmake, so I can put something like
> 
> $(call GENERATE_TMPL_RULE,filename)
> 
> and my GENERATE_TMPL_RULE macro eval()s the appropriate make rules that  
> produce filename.H from filename.tmpl; then I just add additional calls to  
> this macro to generate rules for each code-generated .H file. Works fine.
>
Well, if the flags that need to be passes to the code generator are the
same for all your generated headers, you could use a suffix rule instead,
which is portable to non-GNU make:

  .tmpl.H:
	# build rule that runs the code generator goes here

> The definition of the GENERATE_TMPL_RULE is owned by the toolkit, and I'm  
> looking for a way to avoid having each app, that builds against the toolkit,  
> from explicitly adding the macro definition in its Makefile.am. I'd like to  
> have automake put the canned GENERATE_TMP_RULE into the Makefile.in that it  
> generates.
>
My proposed solution above should work quite nicely in this situation: you
just copy the GENERATE_TMP_RULE defintion in a, say, `my-toolkit.am' file,
and include it in all the Makefile.am files that require its rules.  If you
need to use this file in several projects, and don't want to keep multiple
copies around, you can save the "master copy" in a known location (say
under `~/my-toolkit.am'), and then symlink it into the source trees all the
required projects.

> In my distro, I see that automake has a collection of files in  
> /usr/share/automake-[VERSION]/am/*.am, which look like various snippets that  
> the main automake script pulls together into the Makefile.in script that it  
> produces. But it's not clear to me if it's possible for me to make the  
> necessary arrangements for the automake script to insert my own *.am script,  
> that my toolkit could install into that directory,
>
There's no need to install an `.am' file there in order to use it with the
`include' directive.

> into a Makefile.in  
> produced by automake. That's basically what I'm looking to do, in a  
> nutshell; I'm unable to locate any info on this topic in the automake  
> manual; any tips would be appreciated.
> 

HTH,
  Stefano