File: autoconf.info,  Node: Initializing configure,  Next: Versioning,  Up: Setup

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’ (*note
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.  *Note
     Renaming Macros: (m4)Defn.

     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 (*note 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.  *Note 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.  *Note Site Configuration::.