Re: RFC: doc for m4_include/aclocal and more

[Richard Dawe]

Hello.

Alexandre Duret-Lutz wrote:
> 
> Could some native English correct me?  I started to document
> m4_include and aclocal, but ended up writing a bit more about
> aclocal's usage to manage local files, and its scheduled death.
> 
> Akim, I'd appreciate your opinion about the last section
> (aclocal's death).
> 
> Here is the clear text version the sections which have changed,
> for easier commenting.   The patch follows.
> 
> ----------------------------------------------------------------------
> 
> `m4_include'
>      Files included by `configure.in' using this macro will be detected
>      by Automake and automatically distributed.  They will also appear
>      as dependencies in `Makefile' rules.
> 
>      `m4_include' is seldom used by `configure.in' authors, but can
>      appear in `aclocal.m4' when `aclocal' detects that some required
>      macros come from files local to your package (as opposed to
>      macros installed in a system-wide directory, see *Note Invoking
>      aclocal::).
> 
> ----------------------------------------------------------------------
> 
> Auto-generating aclocal.m4
> ==========================
> 
>    Automake includes a number of Autoconf macros which can be used in
> your package (*note Macros::); some of them are actually required by
> Automake in certain situations.  These macros must be defined in your
> `aclocal.m4'; otherwise they will not be seen by `autoconf'.
> 
>    The `aclocal' program will automatically generate `aclocal.m4' files
> based on the contents of `configure.in'.  This provides a convenient
> way to get Automake-provided macros, without having to search around.
> The `aclocal' mechanism allows other packages to supply their own
> macros (*note Extending aclocal::).  You can also use it to maintain
> your own set of custom macros (*note Local Macros::).
> 
>    At startup, `aclocal' scans all the `.m4' files it can find, looking
> for macro definitions (*note Macro search path::).  Then it scans
> `configure.in'.  Any mention of one of the macros found in the first
> step causes that macro, and any macros it in turn requires, to be put
> into `aclocal.m4'.
> 
>    _Putting_ the file that contains the macro definition into
> `aclocal.m4' is usually done by copying the entire text of this file,
> including unused macro definitions as well as both `#' and `dnl'
> comments.  If you want to make a comment which will be completely
> ignored by `aclocal', use `##' as the comment leader.  When `aclocal'
> detects that the file containing the macro definition is local to your
> package, it will use `m4_include' instead of copying it; this makes the
> package smaller and eases dependency tracking.

At this point I was confused what is meant by "local". You say in the text for
m4_include that system-wide directories are not considered local. Presumably
everything else is?

It might be worth saying what is local & not in this node, to make it clearer.

Maybe you should split the above paragraph, so that the second paragraph would
start with "When `aclocal' detects that". That would separate the non-local
vs. local cases. Then you could say in the local case what is local.

>    The contents of `acinclude.m4', if it exists, are also automatically
> included in `aclocal.m4'.  We recommend against using `acinclude.m4' in
> new packages (*note Local Macros::).
> 
> ----------------------------------------------------------------------
> 
> Writing your own aclocal macros
> ===============================

This section seems to have been included twice in your mail.

>    The `aclocal' program doesn't have any built-in knowledge of any
> macros, so it is easy to extend it with your own macros.
> 
>    This can be used by libraries which want to supply their own Autoconf
> macros for use by other programs.  For instance the `gettext' library
> supplies a macro `AM_GNU_GETTEXT' which should be used by any package
> using `gettext'.  When the library is installed, it installs this macro
> so that `aclocal' will find it.
> 
>    A file of macros should be a series of `AC_DEFUN''s.  The `aclocal'
> programs also understands `AC_REQUIRE', so it is safe to put each macro
> in a separate file.  *Note Prerequisite Macros: (autoconf)Prerequisite
> Macros, and *Note Macro Definitions: (autoconf)Macro Definitions.
> 
>    A macro file's name should end in `.m4'.  Such files should be
> installed in `$(datadir)/aclocal'.  This is as simple as writing:
> 
>      aclocaldir = $(datadir)/aclocal
>      aclocal_DATA = mymacro.m4 myothermacro.m4
> 
>    Another situation where `aclocal' is commonly used is to manage
> macros which are used locally by the package, *Note Local Macros::.
[snip]

> ----------------------------------------------------------------------
> 
> Handling Local Macros
> =====================
> 
>    Feature tests offered by Autoconf do not cover all needs.  People
> often have to supplement existing tests with their own macros, or with
> third-party macros.
> 
>    There is basically two ways to organize custom macros in a package.

There is -> There are. I don't think "basically" adds much meaning to the
sentence, so you could remove that too.

>    The first possibility (the historical practice) is to list all your
> macros in `acinclude.m4'.  This file will be included in `aclocal.m4'
> when you run `aclocal', and its macro will henceforth be visible to

macro -> macro(s)?

> `autoconf'.  However if it contains numerous macros, it will rapidly
> become difficult to maintain, and it will be almost impossible to share
> macros between package.
[snip]

> The Future of `aclocal'
> =======================
> 
>    `aclocal' is expected to disappear.  This feature really should not

feature -> program

> be part of Automake.  Automake should focus on generating `Makefile's,

, -> ;

> dealing with M4 macros really is Autoconf's job.  That some people
> install Automake just to use `aclocal', but do not use `automake'
> otherwise is an indication of how that feature is misplaced.
> 
>    The new implementation will probably be done slightly differently,

I think you should split the sentence after "differently".

> for instance it could enforce the `m4/'-style layout discussed in *Note
> Local Macros::, and take care of copying (or even updating) third-party
> macro into this directory.
> 
>    We have no idea when and how this will happen.  This has been
> discussed several times on the last years, but someone still has to

on the last years -> "over the past few years" or "in the past" (the second
form is better IMHO).

> commit itself to that non-trivial task.

itself to that -> to this

>    From the user point of view, `aclocal''s removal might turns out to

might turns -> might turn

> be painful.  There is a simple precaution that you may take to make
> that switch more seamless: never call `aclocal' yourself.  Keep this
> guy under the exclusive control of `autoreconf' and Automake's rebuild
> rules.  The day `aclocal' disappears, `autoreconf' and Automake will be
> updated and you should not have to bother.  If otherwise you used to

should not have to bother -> should not have to worry.

You won't need to worry about things breaking, when aclocal disappears,
because everything will have been taken care of.

> call `aclocal' directly yourself or from some script, you will quickly
> notice the change.
[snip]

Hope that helps.

Bye, Rich =]

-- 
Richard Dawe [ http://www.phekda.freeserve.co.uk/richdawe/ ]