2.4.1 Creating amhello-1.0.tar.gz ¶

Here is how we can recreate amhello-1.0.tar.gz from scratch. The package is simple enough so that we will only need to write 5 files. (You may copy them from the final amhello-1.0.tar.gz that is distributed with Automake if you do not want to write them.)

Create the following files in an empty directory.

• src/main.c is the source file for the hello program. We store it in the src/ subdirectory, because later, when the package evolves, it will ease the addition of a man/ directory for man pages, a data/ directory for data files, etc.

  ~/amhello % cat src/main.c
  #include <config.h>
  #include <stdio.h>
  
  int
  main (void)
  {
    puts ("Hello World!");
    puts ("This is " PACKAGE_STRING ".");
    return 0;
  }
  

• README contains some very limited documentation for our little package.

  ~/amhello % cat README
  This is a demonstration package for GNU Automake.
  Type 'info Automake' to read the Automake manual.
  

• Makefile.am and src/Makefile.am contain Automake instructions for these two directories.

  ~/amhello % cat src/Makefile.am
  bin_PROGRAMS = hello
  hello_SOURCES = main.c
  ~/amhello % cat Makefile.am
  SUBDIRS = src
  dist_doc_DATA = README
  

• Finally, configure.ac contains Autoconf instructions to create the configure script.

  ~/amhello % cat configure.ac
  AC_INIT([amhello], [1.0], [bug-automake@gnu.org])
  AM_INIT_AUTOMAKE([-Wall -Werror foreign])
  AC_PROG_CC
  AC_CONFIG_HEADERS([config.h])
  AC_CONFIG_FILES([
   Makefile
   src/Makefile
  ])
  AC_OUTPUT
  

Once you have these five files, it is time to run the Autotools to instantiate the build system. Do this using the autoreconf command as follows:

~/amhello % autoreconf --install
configure.ac: installing './install-sh'
configure.ac: installing './missing'
configure.ac: installing './compile'
src/Makefile.am: installing './depcomp'

At this point the build system is complete.

In addition to the three scripts mentioned in its output, you can see that autoreconf created four other files: configure, config.h.in, Makefile.in, and src/Makefile.in. The latter three files are templates that will be adapted to the system by configure under the names config.h, Makefile, and src/Makefile. Let’s do this:

~/amhello % ./configure
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking for gcc... gcc
checking for C compiler default output file name... a.out
checking whether the C compiler works... yes
checking whether we are cross compiling... no
checking for suffix of executables...
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking for style of include used by make... GNU
checking dependency style of gcc... gcc3
configure: creating ./config.status
config.status: creating Makefile
config.status: creating src/Makefile
config.status: creating config.h
config.status: executing depfiles commands

You can see Makefile, src/Makefile, and config.h being created at the end after configure has probed the system. It is now possible to run all the targets we wish (see Standard Makefile Targets). For instance:

~/amhello % make
...
~/amhello % src/hello
Hello World!
This is amhello 1.0.
~/amhello % make distcheck
...
=============================================
amhello-1.0 archives ready for distribution:
amhello-1.0.tar.gz
=============================================

Running autoreconf is only needed initially, when the GNU Build System does not exist. When you later change some instructions in a Makefile.am or configure.ac, the relevant part of the build system will be regenerated automatically when you execute make.

autoreconf is a script that calls autoconf, automake, and related commands in the right order. If you are beginning with these tools, it is not important to figure out in which order all of these tools should be invoked and why. (But for the curious: the basic idea is to run:

1. aclocal (see Auto-generating aclocal.m4: Invoking aclocal),
2. autoconf (see The Autoconf Manual),
3. (if needed) autoheader (part of the Autoconf distribution), and
4. automake (see Creating a Makefile.in: Invoking automake).

If needed, tools related to Gettext (see GNU gettext utilities) and Libtool (see The Libtool Manual) are also invoked at different points. Thus, as you can see, using autoreconf is quite a bit more convenient.

Nevertheless, because Autoconf and Automake have separate manuals, an essential idea to understand is that Autoconf is in charge of creating configure from configure.ac, while Automake is in charge of creating Makefile.ins from Makefile.ams and configure.ac. This should at least direct you to the right manual when seeking answers.