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 autoconf macros - they are grouped by category on the left side. Downloading all macros at onceIn 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 ArchiveThe GNU Autoconf Macro Archive lives at http://www.gnu.org/software/ac-archive which has a CVS repository at the sourceforge-like savannah project page at http://savannnah.gnu.org/projects/ac-archive 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 <guidod@gmx.de> 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 historyThere 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 /usr/share/autoconf. 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 "aclocal.m4" - 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 seen these). 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 will ignore. 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 ones.
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:
|
Please contribute! Just send the m4 source to Guido Draheim <guidod@gmx.de> via electronic mail for inclusion into the Autoconf Macro Archive. I would appreciate if you could split your macros into one-per-mail, rather than sending me your whole aclocal.m4 file, because this makes the inclusion of the submission into the archive much easier for me.
Also, I'd like to ask you to adhere to a few formatting rules in your submissions: Every macro should start with a few comment lines, describing what exactly it tests, what results it does produce and how it may be called by potential users. After the comments, the actual m4 code follows.
In the comments, you should use a few directives to mark special contents, that is interpreted by the perl scripts which convert the m4 input to the HTML page the users will see:
Here is an example, how your submission should look like:
dnl @synopsis The syntax how to use the macro. dnl dnl A description of what the macro does and what results dnl it produces. dnl dnl This description may extend over multiple paragraphs, dnl if you like. dnl dnl Every line that is indented by more than one dnl blank will be formatted verbatim, so that you dnl can include examples in the description. dnl dnl @version $Id$ dnl @author Your Name <your@email.address> dnl AC_DEFUN([MACRO_NAME], [...] ])dnl |
Macro names should always be quoted in brackets, otherwise Autoconf will break in case a macro definition is (accidently) included multiple times in a configure.in file, as the macro name would be expanded the second time the definition is parsed. Note that autoconf can warn about symbols starting with AC_ or AM_ when it does exist but has not been found. That is a nice trick, however one should rarely start naming macros with the AC_/AM_ prefix since they might coincide with names of macros from future versions from autoconf/automake and which would shadow your own macro then. The AX_ prefix is reserved for the usage in the ac-archive and it will be ensured that only one macro of the different name exists here (and the `acinclude` tool does already recognize this prefix and warns about missing ones).
Please note that every macro contained in this archive is copyrighted by its respective author, unless the macro source explicitely says otherwise. Permission has been granted, though, to use and distribute all macros under the following license, which is a modified version of the GNU General Public License version 2:
Every Autoconf macro presented on this web site is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.
They are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. (You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA.)
As a special exception, the Free Software Foundation gives unlimited permission to copy, distribute and modify the configure scripts that are the output of Autoconf. You need not follow the terms of the GNU General Public License when using or distributing such scripts, even though portions of the text of Autoconf appear in them. The GNU General Public License (GPL) does govern all other use of the material that constitutes the Autoconf program.
Certain portions of the Autoconf source text are designed to be copied (in certain cases, depending on the input) into the output of Autoconf. We call these the "data" portions. The rest of the Autoconf source text consists of comments plus executable code that decides which of the data portions to output in any given case. We call these comments and executable code the "non-data" portions. Autoconf never copies any of the non-data portions into its output.
This special exception to the GPL applies to versions of Autoconf released by the Free Software Foundation. When you make and distribute a modified version of Autoconf, you may extend this special exception to the GPL to apply to your modified version as well, *unless* your modified version has the potential to copy into its output some of the text that was the non-data portion of the version that you started with. (In other words, unless your change moves or copies text from the non-data portions to the data portions.) If your modification has such potential, you must delete any notice of this special exception to the GPL from your modified version.
(generated )