4.1 Initializing configure

Every configure script must call AC_INIT before doing anything else that produces output. Calls to silent macros, such as AC_DEFUN, may also occur prior to AC_INIT, although these are generally used via aclocal.m4, since that is implicitly included before the start of configure.ac. The only other required macro is AC_OUTPUT (see Output).

Macro: AC_INIT (package, version, [bug-report], [tarname], [url])

Process any command-line arguments and perform initialization and verification.

Set the name of the package and its version. These are typically used in --version support, including that of configure. The optional argument bug-report should be the email to which users should send bug reports. The package tarname differs from package: the latter designates the full package name (e.g., ‘GNU Autoconf’), while the former is meant for distribution tar ball names (e.g., ‘autoconf’). It defaults to package with ‘GNU ’ stripped, lower-cased, and all characters other than alphanumerics and underscores are changed to ‘-’. If provided, url should be the home page for the package.

Leading and trailing whitespace is stripped from all the arguments to AC_INIT, and interior whitespace is collapsed to a single space. This means that, for instance, if you want to put several email addresses in bug-report, you can put each one on its own line:

# We keep having problems with the mail hosting for
# gnomovision.example, so give people an alternative.
AC_INIT([Gnomovision], [17.0.1], [
    bugs@gnomovision.example
    or gnomo-bugs@reliable-email.example
])

The arguments to AC_INIT may be computed by M4, when autoconf is run. For instance, if you want to include the package’s version number in the tarname, but you don’t want to repeat it, you can use a helper macro:

m4_define([gnomo_VERSION], [17.0.1])
AC_INIT([Gnomovision],
        m4_defn([gnomo_VERSION]),
        [bugs@gnomovision.example],
        [gnomo-]m4_defn([gnomo_VERSION]))

This uses m4_defn to produce the expansion of gnomo_VERSION as a quoted string, so that if there happen to be any more M4 macro names in gnomo_VERSION, they will not be expanded. See Renaming Macros in GNU m4 macro processor.

Continuing this example, if you don’t want to embed the version number in configure.ac at all, you can use m4_esyscmd to look it up somewhere else when autoconf is run:

m4_define([gnomo_VERSION],
  m4_esyscmd([build-aux/git-version-gen .tarball-version]))
AC_INIT([Gnomovision],
        m4_defn([gnomo_VERSION]),
        [bugs@gnomovision.example],
        [gnomo-]m4_defn([gnomo_VERSION]))

This uses the utility script git-version-gen to look up the package’s version in its version control metadata. This script is part of Gnulib (see Gnulib).

The arguments to AC_INIT are written into configure in several different places. Therefore, we strongly recommend that you write any M4 logic in AC_INIT arguments to be evaluated before AC_INIT itself is evaluated. For instance, in the above example, the second argument to m4_define is not quoted, so the m4_esyscmd is evaluated only once, and gnomo_VERSION is defined to the output of the command. If the second argument to m4_define were quoted, m4_esyscmd would be evaluated each time the version or tarname arguments were written to configure, and the command would be run repeatedly.

In some of the places where the arguments to AC_INIT are used, within configure, shell evaluation cannot happen. Therefore, the arguments to AC_INIT may not be computed when configure is run. If they contain any construct that isn’t always treated as literal by the shell (e.g. variable expansions), autoconf will issue an error.

The tarname argument is used to construct filenames. It should not contain wildcard characters, white space, or anything else that could be troublesome as part of a file or directory name.

Some of M4’s active characters (notably parentheses, square brackets, ‘,’ and ‘#’) commonly appear in URLs and lists of email addresses. If any of these characters appear in an argument to AC_INIT, that argument will probably need to be double-quoted to avoid errors and mistranscriptions. See M4 Quotation.

The following M4 macros (e.g., AC_PACKAGE_NAME), output variables (e.g., PACKAGE_NAME), and preprocessor symbols (e.g., PACKAGE_NAME), are defined by AC_INIT:

AC_PACKAGE_NAME, PACKAGE_NAME

Exactly package.

AC_PACKAGE_TARNAME, PACKAGE_TARNAME

Exactly tarname, possibly generated from package.

AC_PACKAGE_VERSION, PACKAGE_VERSION

Exactly version.

AC_PACKAGE_STRING, PACKAGE_STRING

Exactly ‘package version’.

AC_PACKAGE_BUGREPORT, PACKAGE_BUGREPORT

Exactly bug-report, if one was provided. Typically an email address, or URL to a bug management web page.

AC_PACKAGE_URL, PACKAGE_URL

Exactly url, if one was provided. If url was empty, but package begins with ‘GNU ’, then this defaults to ‘https://www.gnu.org/software/tarname/’, otherwise, no URL is assumed.

If your configure script does its own option processing, it should inspect ‘$@’ or ‘$*’ immediately after calling AC_INIT, because other Autoconf macros liberally use the set command to process strings, and this has the side effect of updating ‘$@’ and ‘$*’. However, we suggest that you use standard macros like AC_ARG_ENABLE instead of attempting to implement your own option processing. See Site Configuration.