Macro Format
============

Each macro in the Archive has an all-upper-case name with the prefix AX_.  The macro is stored in a file with the same name, in lower case, and with the suffix .m4.

The file should begin with a header comment containing three named sections: synopsis, description, and license.

The synopsis gives a summary of the macro usage and arguments.  In this section, square brackets ([]) are used to indicate optional parameters, and may be nested.

The description contains a prose description of the macro.  It should describe the function of the macro, and the meaning of any arguments given in the synopsis.  The description should also identify:

  * any default macro parameter values

  * any new --with or --enable options, and their default values

  * any argument variables consulted (AC_ARG_VAR)

  * any substituted variables (AC_SUBST)

  * any defined precompiler constants (AC_DEFINE)

Macros should be defined with AC_DEFUN, using correct quoting.  Comments should be used liberally within the macro, with dnl used for comments at the m4sh level and # used for comments at the shell level.

If a macro is renamed, the AU_ALIAS macro should be used to guide users of the old name to the new name:

     AU_ALIAS([OLD_NAME], [AX_NEW_NAME])

Submitting Macros
=================

To submit updates to the Autoconf Archive, please create an issue in the patch tracker (http://savannah.gnu.org/patch/?func=additem&group=autoconf-archive) and attach a (preferably git-format-patch(1)-formatted) patch file. Users of github.com may prefer to create a pull request for the Autoconf Archive Mirror at Github (https://github.com/peti/autoconf-archive). Please make sure your submission contains the following items:

  * a synopsis that shows how the macro must be be called,

  * a brief description of the macro's purpose,

  * the list of authors (optionally with e-mail addresses),

  * licensing terms, and

  * the m4 source code.

Macros can be submitted under any GPL-compatible free software license (http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses). The Free Software Foundation, however, recommends use of the all-permissive license (http://www.gnu.org/prep/maintain/html_node/License-Notices-for-Other-Files.html) for Autoconf macros.

Writing Highly Usable Macros
============================

Autoconf macros are used in a surprising variety of ways, and a well-written macro should be flexible enough to suit all of these uses.

See the Autotools Mythbuster (http://www.flameeyes.eu/autotools-mythbuster) for suggestions on how to write well-encapsulated, portable macros.