I'd like to say one small thing before going into details:
Please contribute! Much effort has been put into this place,
in the hope that it will be useful to as many people as possible. But
we can't do it all by ourselves -- we need your help. If you have
written a macro (or two?) of which you think that it might be useful,
please contribute it to the archive.
Curiously enough, many people seem to be scared away by the idea
that "their macro is not good enough to be published". Try to look at
it this way: Nobody is perfect, nobody knows everything and nobody
will be flamed if there is a minor stylistic deficiency in the code of
a macro published here. Hey, do you know any better way to get
your code debugged for free by several hundred volunteers? :-)
Enough for now, just have a look at the
macros - they are grouped by category on the left side.
Downloading all macros at once
In case you want to download all macros at once rather than having to click
through the whole list and access them individually, just get tarballs and
rpm archives from the
project's sourceforge filelist, where updates are posted
every time a member of the archive changes or new macros are added.
The GNU Autoconf Macro Archive
The GNU Autoconf Macro Archive lives at
which has a CVS repository at the sourceforge-like
savannah project page at
that I am also co-maintaining - Peter Simons has created the
original idea of an Autoconf Macro Archive, and he does
also maintain the GNU pages that were created from his
original private site. Much of this front page was originally
written by him - including the GPL copyright information
at the end of page ;-)
If you want to contribute ...
then please don't hesitate a second! Just send the m4 source to Guido Draheim
<firstname.lastname@example.org> via electronic mail. See the
section about the contribution format
on the macro documentation guidelines. Note that the two ac-archive
repositories (sourceforge and savannah) are constantly kept in sync
while the sfnet branch offers space for experimental extras. It is
therefore updated more frequently than the original
GNU ac-archive which works the
traditional way without neither of the `aclocal` installoption
or the `acinclude` packageoption.
acpackage aclocal acinclude and other history
There was a time that the autoconf project was invented to help people
make their projects more portable and it was a time that the basic
autoconf project provided all the means to do it, and the automake project
invented the "aclocal" tool to augment on top of it with macro series
provided by other packages which they were installing in the /usr/share/aclocal
subdirectory. There you will find macro-files like "libtool.m4" which hold
the macros to properly "configure" the functionality of these tools in the
case that a developer wants to use them in a project. And the "aclocal" tool
will detect the macros in the "configure.in" script copying the needed
macros a file called "aclocal.m4" which the "autoconf" tool will see
automatically and bind in to its resources otherwise coming from
However, the macros in package-specific "share/aclocal" and the
base functionality in "share/autoconf" do not adress a specific area: the
use of macros in multiple projects where these macros are neither general
w.r.t. to portability and neither project-centric w.r.t. to just one project.
These are often some feature tests developed in one project and that was
found useful enough to be reused in other projects - and it is the natural
way to give it a name and reference the functionality by its name - et voila,
this is what the term "macro" says, to pack a series of commands under a
name, possibly with some arguments that to carry package-specific variables
into the heart of the memorized feature test.
It happens to be very easy to develop such a macro, (1) just cut out your
shell script that you came to test a feature, and put it into its own file,
e.g. "ac_mytest.m4". (2) Then put up the trailer and footer that you can see
in the "contribution" example or in any of the
other ac-archive scripts - i.e. add
a comment-block (using the "dnl"-m4-comment instead of the "#"-sh-comment)
and the AC_DEFUN([AC_MYTEST],[......]) declaration to give it the
name "AC_MYTEST". And (3) do not forget to look for the
"["s and "]"s in the macro body since these are the autoconf-quotes - just
double them into "[["s and "]]"s which "autoconf" will shrink back to simple
square when it expands your "configure.ac" to the "configure" script.
Well, that's all what is needed to create an ac-macro.
The next step is not related to creation of an ac-macro but how make these
to be reused in multiple projects. Just copying the bew file "ac_mytest.m4"
to that project directory is not enough since neither
"aclocal" nor "autoconf" will see it automatically. The way to manage these
has a bit of history to watch out for. (a) "autoconf" tool will use all the
macros in "share/autoconf/" directory plus the macros in "aclocal.m4" in the
project directory. (b) "aclocal" will use all the macros in "share/aclocal"
plus the macros in "acinclude.m4" in the project directory.
To augment on these tools, the traditional way is (A) create a subdirectory
"m4/" in your project directory, copy the ac-macros thereunder and
make sure to call "aclocal -I m4" to have these macros copied into
- to ensure this, watch out for "automake" which will create a rule in its
"Makefile.in" to call "aclocal" automatically. There is an option called
$(ACLOCAL_AMFLAGS) you can use to add the requried subdir for it.
(B) just copy the two macros you need into the project directory, and "cat"
the two macros together into the "acinclude.m4" file, i.e. "cat mytest1.m4
mytest2.m4 >acinclude.m4" - downside: you want to do that only for one or
two macros, not a dozen of them.
Well, both of these ways have a drawback - when you update your cross-project
ac-macro, how do you distribute the changes to other project directories?
Originally, the "aclocal" command could distribute the changes, and that is
what Guido Draheim started to do - to create a distribution archive including
rpm file that will install the extra macros into "share/aclocal" so that all
projects will instantly find the updated ac-macro. This was convenient for his
two dozen macros, and the project was called "aclocals" to give the impression
to extend the "aclocals" macros being installed. However, later he discovered
the ac-archive project invented by
Peter Simons, and instantly started to reuse some of the macros stored
there - which of course results in two
competeing strains of update paths with both packaging tarballs to carry
around macros. Well, in the opensource world there is never something wrong
with solving the problem of overlap between two projects - merge them!
I do not want to delve into the specifics why the merge did not succeed
instantly with the sfnet branch showing the benefit that the "aclocals"
packaging system can provide to the
ac-archive - the
gnu-hosted series is
pretty much the original site that was present as a subdirectory of Peter's
homepage and which is now a subdirectory at
www.gnu.org. Let's hope that
the final pieces can be solved later and the sfnet branch will degenerate
to a place for pure experimentation ... and rpm series which I doubt will
be shipped on the gnu.org servers sometime soon.
acinclude (the tool)
With more and more macros to show up in the
ac-archive however the
limitations of the "aclocals" installoption became more and more
inconvenient to handle - the merged series of user-centric macros
with the heap of macros out of the
ac-archive was just a bit much.
With the growing popularity (partly through the fame of being a gnu project)
the number of macros in the
ac-archive multiplied and it was unfair
to have 200 macros being handled in the "share/aclocal" directory. The
ac-archive website had been broken
into six subcategories for a reason
and with more and more macros showing up, we do actually consider to add
more subcategories in order to handle the bulk of macros more easily.
Furthermore, it became known that more and more projects started to get
another dependency on the ac-archive
project, or more specifically, the
sfnet branch for any maintainer-clean of those projects since for convience
these projects did not ship the m4
ac-archive macros but they did just
use the aclocal.m4 file being generated by "aclocal" itself. But any
maintainer-clean will sweep that file, and if a bootstrap build of a project
did not preinstall the ac-archive then
a number of unresolved autoconf macros will be the result
(debian autobuild maintainers may have
To overcome this problem area, Guido Draheim did develop the "acinclude"
tool recently - which is actually a copy of "aclocal" modified for the
needs of the "ac-archive". This tool will (as the name suggests) create
a file called "acinclude.m4" in the project directory which will be left
untouched by any maintainer-sweeps *and* which automake will see and
automatically include in a tarball of the resp. project directory.
Furthermore, this "acinclude" tool will not just scan one directory
like "aclocal" would but it will scan for m4-files in the subdirectories
of any of its "-I"-options - with a default to look for m4-files in the
subdirectories (!!) of "share/aclocal" which the original "aclocal" tool
That way, the new "acinclude" installoption will copy the ac-archive to
the "share/aclocal" path as it is - with all its subcategories represented
in the form of subdirectories. Furthermore, these directories are always
searched in alphabetic order with any macro found in later directories to
overwrite the previous ones - and since the official ac-archive directories
are starting in big-caps, any developer can start out with his own subdir
to hold his specific macros or some experimental extension to the official
Now have a look back into the previous section where we talked about the
sequence of tools the files that they create. This sequence is now simply
enlarged with a third tool - and it reads now like this:
(a) "autoconf" tool will use all the macros in "share/autoconf/"
plus the macros in "aclocal.m4" in the project directory
- creating "configure".
(b) "aclocal" will use all the macros in "share/aclocal/"
plus the macros in "acinclude.m4" in the project directory.
- creating "aclocal.m4"
(c) "acinclude" will use all the macros in "share/aclocal/*/" (the
subdirectoires of "share/aclocal" plus the macros in "acpackage.m4"
- creating "acinclude.m4"
and the "acinclude.m4" file will then be known to carry cross-project
macros coming either directly from the
ac-archive's official subcategories
or from a user-specific subcategories where examples can see be seen in the
sfnet branch for some well-known developers. However, please note:
the "acinclude" tool is a quick hack that just does what is should do - so
please report any problems or ideas about it as you would do for any