Autotools nano-HOWTO

http://juha.vierinen.net/files/autotools-nano-howto.html

Introduction

One often gets a warm fuzzy feeling seeing the autoconf generated configure file after unpacking a source tarball – this is because your chances of easily compiling the piece of software have grown significantly. This doesn't mean that you won't have any problems – you will have problems with compiling software sooner or later – it just means that things tend to go more smoothly when autoconf and automake (referred to as autotools in this text) are involved. The main purpose of these tools is ease the pain of compiling software on different platforms, but automake can additionally automate many other aspects of software configuration management.

Building autotools managed software

The end user never needs to use autoconf or automake, as these tools create a plain vanilla sh script called configure. This way the platform used for compiling doesn't need to have a working autotools, just a regular bourne shell. The normal way to proceed after untarring a source package is this:

./configure ; make ; make install

Usually there are also many custom options provided by the package maintainer. The help option usually lists these.

./configure --help

For example, –prefix will install the software into the home directory of the user instead of the default location (/usr or /usr/local).

./configure --prefix=/home/user

Common environment variables are CFLAGS, CXXFLAGS, FFLAGS, FCFLAGS, LIBS and LDFLAGS. These are processed and tested by configure and added to the flags that configure comes up with. On more obscure (e.g., AIX) platforms, you will often have to come up with CFLAGS and LDFLAGS that will find the right headers and libraries. For example:

> export CFLAGS="-O42 -g --funny-compiler-flag -I/hard/to/guess/directory"
> ./configure ; make # will usually use your CFLAGS for compiling</span>

Sometimes, a package might also include custom arguments to do this as well eg.:

> ./configure --with-blas="-L/home/user -lblas"
> ./configure --with-blas="/opt/supafastblaswithstripesandachrometailpipe.a"

Automake default targets

The commonly used targets are:

make           # Compile everything.
make clean     # Remove all objects, temporary files and such.
make distclean # Remove automatically generated autoconf/automake files.

make dist      # Create a tar.gz file containing source ready for distribution.
make install   # Install software to you kit.

Other useful targets:

<a name="flags">make tags      <span class="comment"># Generate etags files for the source.</span>
make dist-zip  <span class="comment"># Create a zip file (great for windows people)</span>

make uninstall <span class="comment"># Uninstall the files installed with make install</span>
make check     <span class="comment"># Run tests bundled with the project</span>
</a></pre>

===== The anatomy of a automake and autoconf governed project =====

<p><a name="flags">Automake operates on a high abstraction level. You define the
source files that are needed to build an executable or a
library and automake generates the necessary make rules --
also rules for packaging and installing are automatically
created. Automake reads <code>Makefile.am

and

configure.in

as input.</a>

<a name=“flags”>Autoconf is on the abstraction level of a normal Makefile. The main purpose of autoconf is create a configure script that finds necessary compilers and compiler flags. Autoconf also reads it's input from

configure.in

(or sometimes

configure.ac

). Automake depends on autoconf for generating the

configure

script. Autoconf can also be used stand-alone by creating a Makefile template in

Makefile.in

. When the

configure

script is run by the user, placeholders for compilers and compiler flags in

Makefile.in

are replaced with the platform specific values to create a

Makefile

.</a>

<pre><a name=“flags”>autogen.sh # Semi-standard script for generating the configure

         # script and possibly the Makefile.in files
         # by running automake and autoconf.</span>

configure.[in,ac] # Definitions used for producing configure Makefile.in # Autoconf makefile template Makefile.am # Automake project description file. </a></pre>

Maintaining an autoconf project

<a name=“flags”>If only autoconf is used, then Makefile.in is the file to edit. Autoconf variables appear as

@VARIABLE@

like definitions (these are replaced with values found by the configure script). It is also possible to use autoconf definitions in Makefile.am files, this is especially useful for situations where automake functionality runs short. A snippet of Makefile.in can look like: </a>

<pre><a name=“flags”>screensave.@OBJEXT@: screensave.c @CC@ @CFLAGS@ -c -o $@ $< </a></pre>

<a name=“flags”>Here,

@OBJEXT@

,

@CC@

, and

@CFLAGS@

are replaced with values found by the configure script to create a normal makefile.</a>

<h2><a name=“flags”>Maintaining an autoconf+automake project</a></h2>

<a name=“flags”>If automake is used, the file to edit is Makefile.am. You can also mix custom Makefile directives in here, but stick with automake definitions whenever possible, as it will save a lot of time. A simple Makefile.am could look like this: </a>

<pre><a name=“flags”>bin_PROGRAMS=hello hello_SOURCES=hello.c hello.h someotherfile.f manylanguages.cpp </a></pre>

<a name=“flags”>This example will create a

configure

that looks for working C, Fortran 77 and C++ compilers, ending up with a working Makefile that will compile the executable <bold>hello</bold>, which will be copmiled from a mix of C, fortran and C++.</a>

Commands

<pre><a name=“flags”>autoscan # Scan your source code to detect which tests might be needed and

          # create a configure.scan, which can be used as a basis of 
    # configure.in.</span>

autoheader # Scan configure.in and create a config.h.in file, that will

          # be used as a basis of your config.h (if you use one)</span>

automake # Go through configure.in and Makefile.am files and create

          # Makefile.in files.</span>

autoconf # Go through configure.in and create the configure script. </a></pre>

<a name=“flags”>Still can't figure out what to run and in which order? Try running automake, aclocal, autoconf and autoheader in random combinations, and you'll usually end up with something useful after a couple of iterations. When you get a feeling of what is needed, write it down into autogen.sh, so you'll remember it next time. </a>

Writing custom tests

<a name=“flags”>You can write tests directly into configure.in. The language is a macro-language called <a href=“http://www.gnu.org/software/m4/”>M4</a>, which is used to generate Bourne shell script. So you basically write in a mixture of sh and M4. Eg. </a>

<pre><a name=“flags”>AC_MSG_CHECKING([for answer to meaning of life]) # M4 function call answer=“42” # sh variable assignment AC_MSG_RESULT($answer) # M4 function call </a></pre>

<a name=“flags”>Even writing modular and reusable M4+sh is possible, just take a look at the autoconf source for the default AC_* macros. </a>

<a name=“flags”>If you intend to write a lot of tests, it is beneficial to write them into separate .m4 files. This has an advantage of keeping configure.in more understandable. Eg. you might have a file acx_blas.m4 that contains a routine that gives a BLAS library as an argument to

./configure

: </a>

<pre><a name=“flags”>AC_DEFUN([ACX_BLAS], [ acx_blas_ok=no AC_ARG_WITH(blas, [AC_HELP_STRING([–with-blas=<lib>], [use BLAS library <lib>])]) case $with_blas in yes | “”) ;; no) acx_blas_ok=disable ;; -* | */* | *.a | *.so | *.so.* | *.o) BLAS_LIBS=“$with_blas” ;; *) BLAS_LIBS=“-l$with_blas” ;; esac # Get fortran symbol name of sgemm (a blas routine). AC_FC_FUNC(sgemm) acx_blas_save_LIBS=“$LIBS” LIBS=“$LIBS $FCLIBS $FLIBS” # First, check BLAS_LIBS environment variable if test “x$BLAS_LIBS” != x; then save_LIBS=“$LIBS”; LIBS=“$BLAS_LIBS $LIBS” AC_MSG_CHECKING([for $sgemm in $BLAS_LIBS]) AC_TRY_LINK_FUNC($sgemm, [acx_blas_ok=yes], [BLAS_LIBS=“”]) AC_MSG_RESULT($acx_blas_ok) LIBS=“$save_LIBS” fi # restore the libs variable LIBS=$acx_blas_save_LIBS ]) </a></pre>

<a name=“flags”>This can be then added to

configure.in

like this: </a>

<pre><a name=“flags”>sinclude([acx_blas.m4]) ACX_BLAS LIBS=“$BLAS_LIBS $FLIBS” </a></pre>

CVS and autotools

<a name=“flags”>CVS and autotools is an evil combination. AM_MAINTAINER_MODE is the key many of the problems with mixed up timestamps, but there are other things to know as well. </a>

<a name=“flags”>CVS updates often break autotools managed files files beyond repair. This can be seen as weird errors in while using make. One way to proceed might be to re-run configure to create everything – or if even configure is broken a </a>

<pre><a name=“flags”>rm configure ; cvs update configure ; ./configure </a></pre>

<a name=“flags”>Alternatively, you can regenerate the configure yourself, if you have autotools installed: </a>

<pre><a name=“flags”>sh autogen.sh ; ./configure </a></pre>

Troubleshooting

<a name=“flags”>When a test fails and configure fails to give a reasonable explanation of what went wrong (the usual case), searching config.log will often give more detailed information about what went wrong. </a>

More information

<a name=“flags”>The best way to learn is to study (i.e., steal) code from others – just search for projects that use the same libraries and programming languages that you do. The documentation that comes with automake and autoconf is extremely good: </a>

<a href=“http://www.gnu.org/software/autoconf/manual/index.html”>Autoconf manual</a>

<a href=“http://www.gnu.org/software/automake/manual/index.html”>Automake manual</a>

There is also a semi-official autoconf macro index contains a wide range of tests. They might not be perfect, but usually are a good starting point.

<a href=“http://autoconf-archive.cryp.to/macros-by-category.html”>Autoconf macro archive</a>

Another useful reference is the code itself. Need to know a shell variable that is produced by some test? Look it up from the autoconf/lib/autoconf directory of autoconf source.

Libtool is another useful tool to learn, for making cross-platform libraries, but libtool is not discussed here.

<a href=“http://directory.fsf.org/All_Packages_in_Directory/autoproject.html”>Autoproject</a> is a tool that creates a skeleton automake and autoconf managed project.

rigacci.org

Table of Contents