[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: RFC: doc for m4_include/aclocal and more
From: |
Richard Dawe |
Subject: |
Re: RFC: doc for m4_include/aclocal and more |
Date: |
Wed, 30 Apr 2003 09:49:18 +0100 |
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/ ]