The GNU build system, also known as the Autotools, is a suite of programming tools designed to assist in making source-code

packages portable to manyUnix-like systems. It can be difficult to make a software program portable: the C compiler differs from system to system; certain library functions are missing on some systems; header files may have different names. One way to handle this is write conditional code, with code blocks selected by means of preprocessor directives (#ifdef); but because of the wide variety of build environments this approach quickly becomes unmanageable. The GNU build system is designed to address this problem more manageably. The GNU build system is part of the GNU toolchain and is widely used in many free-software and opensource packages. The tools comprising the GNU build system are free-software-licensed under the GNU [1][2] General Public License with special license exceptions permitting use of the GNU build system withproprietary software.

Tools included in the GNU build system

The GNU build system comprises the GNU utility programs Autoconf, Automake, and Libtool. Other related tools frequently used with the GNU build system are GNUs make program, GNU gettext, pkgconfig, and the GNU Compiler Collection, also called GCC.
[3]

[edit]GNU Autoconf
Autoconf generates a configure script based on the contents of a configure.ac file which characterizes a particular body of source code. The configure script, when run, scans the build environment and generates a subordinateconfig.status script which, in turn, converts other input files and most commonly Makefile.in into output files (Makefile) which are appropriate for that build environment. Finally the make program uses Makefile to generate executable programs from source code. The complexity of the GNU build system reflects the variety of circumstances under which a body of source code may be built. If a source code file is changed then it suffices to re-run make which only re-compiles that part of the body of the source code affected by the change. If a .in file has changed then it suffices to re-run config.status and make. If the body of source code is copied to another computer then it is suffices to rerun configure (which runsconfig.status) and make. (For this reason source code using the GNU build system is normally distributed without the files that configure generates.) If the body of source code is changed more fundamentally then configure.ac and the .in files need to be changed and all subsequent steps also followed.

To process files, autoconf uses the GNU implementation of the m4 macro system. Autoconf comes with several auxiliary programs such as Autoheader, which is used to help manage C header files; Autoscan, which can create an initial input file for Autoconf; and ifnames, which can list C pre-processor identifiers used in the program.

[edit]GNU Automake

Automake helps to create portable Makefiles, which are in turn processed with the make utility. It takes its input asMakefile.am, and turns it into Makefile.in, which is used by the configure script to generate the file Makefile output.

[edit]GNU Libtool
Libtool helps manage the creation of static and dynamic libraries on various Unix-like operating systems. Libtool accomplishes this by abstracting the library-creation process, hiding differences between various systems (e.g. GNU/Linux systems vs.Solaris).

[edit]Gnulib
Gnulib simplifies the process of making software that uses Autoconf and Automake portable to a wide range of systems.

[edit]Advantages of the GNU build system

The GNU build system allows a programmer to write cross-platform software. It also makes the build process easier on a user who wants to compile the program on his or her own computer. The user does not need to have GNU build system components installed on the computer but only needs to run the supplied configure script which has no dependencies other than the presence of a Bournecompatible shell.

[edit]Limitations of the GNU build system

The GNU build system uses Bourne-compatible shell scripts to assist the user in the configuration and build process. The GNU build system can be used both for building native programs on the build machine [4] and also for cross-compiling to other architectures. Cross-compiling software to run on a Windows host from a GNU/Linux or other Unix-like build system is also possible, using MinGW, however native compilation is often desirable on operating systems (such as the Microsoft Windows family of systems) that cannot run Bourne shell scripts on their own. This makes building such software on the Windows operating system a bit harder than on a Unix-like system which provides the Bourne shell as a standard component. One can install the Cygwin or MSYS system on top of Windows to provide a Unix-like compatibility layer, though, allowingconfigure scripts to run. Cygwin also provides the GNU Compiler Collection, GNU make, and other software that provides a nearly complete Unix-like system within Windows; MSYS also provides GNU make and other tools designed to work with the MinGW version of GCC. Projects which use the GNU build system may or may not provide a configure script within their Version control systems (such as CVS or Subversion). If a project that uses the GNU build system does not have a generated ./configure file available for the user, the user must generate it. One possible way this can be done is to execute the autoreconf tool at a shell prompt: $ autoreconf -i This will invoke aclocal, autoconf, autoheader and automake as needed, and install any necessary files. In some cases, more commands may be necessary. An older convention is to provide a script, often named autogen.sh or bootstrap, that runs all the needed pre-build tools.

The autoconf-generated configure can be slow because it executes programs like the C compiler many times in order to test whether various libraries, header files, and language features are present. This particularly affects Cygwin, which, due to its lack of a native fork system call, may execute configure [5] scripts an order of magnitude slower than Linux.

5.1 Introducing the GNU tools

When we speak of the GNU build system we refer primarily to the following four packages: 1. Autoconf produces a configuration shell script, named `configure', which probes the installer platform for portability related information which is required to customize makefiles, configuration header files, and other application specific files. Then it proceeds to generate customized versions of these files from generic templates. This way, the user will not need to customize these files manually. 2. Automake produces makefile templates, `Makefile.in' to be used by Autoconf, from a very high level specification stored in a file called `Makefile.am'. Automake produces makefiles that conform to the GNU makefile standards, taking away the extraordinary effort required to produce them by hand. Automake requires Autoconf in order to be used properly. 3. Libtool makes it possible to compile position independent code and build shared libraries in a portable manner. It does not require either Autoconf, or Automake and can be used independently. Automake however supports libtool and interoperates with it in a seamless manner. 4. Autotoolset helps you develop portable source code that conforms to the GNU coding standards by generating various boilerplate files from which you can plunge into developing your software. Some tasks that are simplified by the GNU build system include: 1. Building multidirectory software packages. It is much more difficult to use raw make recursively. Having simplified this step, the developer is encouraged to organize per source code in a deep directory tree rather than lump everything under the same directory. Developers that use raw make often can't justify the inconvenience of recursive make and prefer to disorganize their source code. With the GNU tools this is no longer necessary. 2. Automatic configuration. You will never have to tell your users that they need to edit your Makefile. You yourself will not have to edit your Makefiles as you move new versions of your code back and forth between different machines. 3. Automatic makefile generation. Writing makefiles involves a lot of repetition, and in large projects very error-prone. Also, certain portions of a good makefile, such as the `install' and `uninstall' targets are very critical because they are run by the superuser. They must be written without any bugs! The GNU build system automates makefile writing. You are only

required to write `Makefile.am' files that are much more terse and easy to maintain. 4. Support for test suites. You can very easily write test suite code, and by adding one extra line in your `Makefile.am' make a check target available such that you can compile and run the entire test suite by running make check. 5. Automatic distribution building. The GNU build tools are meant to be used in the development of free software, therefore if you have a working build system in place for your programs, you can create a source code distribution out of it by running make distcheck. 6. Shared libraries. Building shared libraries becomes as easy as building static libraries. The GNU build system needs to be installed only when you are developing programs that are meant to be distributed. To build a program from distributed source code, the installer only needs a working make utility, a compiler, a shell, and sometimes standard Unix utilities like sed, awk, yacc, lex. The objective is to make software installation as simple and as automatic as possible for the installer. Also, by setting up the GNU build system such that it creates programs that don't require the build system to be present during their installation, it becomes possible to use the build system to bootstrap itself.

5.2 Installing the GNU build system

If you are on a Unix system, don't be surprised if the GNU development tools are not installed. Some Unix sysadmins have never heard about them. If you do have them installed check to see whether you have the most recent versions. To do that, type:
% autoconf --version % automake --version % libtool --version

This manual is current with Autoconf 2.57, Automake 1.6.3 and Libtool 1.4.3. If you don't have any of the above packages, you need to get a copy and install them on your computer. The distribution filenames for the GNU build tools, are:
autoconf-2.57.tar.gz automake-1.6.3.tar.gz libtool-1.4.3.tar.gz autotoolset-0.11.6.tar.gz

Before installing these packages however, you will need to install the following needed packages from the FSF:

make-*.tar.gz m4-*.tar.gz texinfo-4.3.tar.gz tar-*.shar.gz

The asterisks in the version numbers mean that the version for these programs is not critically important. You will need the GNU versions of make, m4 and tar even if your system already has native versions of these utilities. To check whether you do have the GNU versions see whether they accept the --version flag. If you have proprietary versions of make or m4, rename them and then install the GNU ones. You will also need to install Perl, the GNU C compiler, and the TeX typesetting system. These programs are always installed on a typical Debian GNU/Linux system. It is important to note that the end user will only need a decent shell and a working make to build a source code distribution. The developer however needs to gather all of these tools in order to create the distribution. The installation process, for all of these tools that you obtain as `*.tar.gz' distributions is rather straightforward:
% % % % ./configure make make check make install

Most of these tools include documentation which you can build with
% make dvi

5.3 Hello world example with Autoconf and Automake

To get started we will show you how to do the Hello world program using `autoconf' and `automake'. In the fine tradition of K&R, the C version of the hello world program is:
#include <stdio.h> main() { printf("Howdy world!\n"); }

Call this `hello.c' and place it under an empty directory. Simple programs like this can be compiled and ran directly with the following commands:
% gcc hello.c -o hello % hello

If you are on a Unix system instead of a GNU system, your compiler might be called `cc' but the usage will be pretty much the same. Now to do the same thing the `autoconf' and `automake' way create first the following files:
`Makefile.am' bin_PROGRAMS = hello hello_SOURCES = hello.c `configure.in' AC_INIT(hello.c) AM_INIT_AUTOMAKE(hello,0.1) AC_PROG_CC AC_PROG_INSTALL AC_OUTPUT(Makefile)

Now run `autoconf':

% aclocal % autoconf

This will create the shell script `configure'. Next, run `automake':
% automake -a required file required file required file required file required file required file required file required file required file "./install-sh" not found; installing "./mkinstalldirs" not found; installing "./missing" not found; installing "./INSTALL" not found; installing "./NEWS" not found "./README" not found "./COPYING" not found; installing "./AUTHORS" not found "./ChangeLog" not found

The first time you do this, `automake' will complain a couple of things. First it notices that the files `install-sh', `mkinstalldirs' and `missing' are not present, and it installs copies. These files contain boiler-plate shell scripts that are needed by the makefiles that `automake' generates. It also complains that the following files are not around:

INSTALL, COPYING, NEWS, README, AUTHORS, ChangeLog

These files are required to be present by the GNU coding standards, and we discuss them in detail in Maintaining the documentation files. At this point, it is important to at least touch these files, otherwise if you attempt to do a `make distcheck' it will deliberately fail. To make these files exist, type:
% touch NEWS README AUTHORS ChangeLog

and to make Automake aware of the existence of these files, rerun it:
% automake -a

You can assume that the generated `Makefile.in' is correct, only when Automake completes without any error messages. Now the package is exactly in the state that the end-user will find it when person unpacks it from a source code distribution. For future reference, we will call this state autoconfiscated. Being in an autoconfiscated state means that, you are ready to type:
% ./configure % make % ./hello

to compile and run the hello world program. If you really want to install it, go ahead and call the `install' target:
# make install

To undo installation, that is to uninstall the package, do:

# make uninstall

If you didn't use the `--prefix' argument to point to your home directory, or a directory in which you have permissions to write and execute, you may need to be superuser to invoke the install and uninstall commands. If you feel like cutting a source code distribution, type:
make distcheck

This will create a file called `hello-0.1.tar.gz' in the current working directory that contains the project's source code, and test it out to see whether all the files are actually included and whether the source code passes the regression test suite. In order to do all of the above, you need to use the GNU `gcc' compiler. Automake depends on `gcc''s ability to compute dependencies. Also, the `distcheck' target requires GNU make and GNU tar. The GNU build tools assume that there are two types of hats that people like to wear: the developer hat and the installer hat. Developers develop the source code and create the source code distribution. Installers just want to compile and install a source code distribution on their system. In the free software community, the same people get to wear either hat depending on what they want to do. If you are a developer, then you need to install the entire GNU build system, period (see section Installing the GNU build system). If you are an installer, then all you need to compile and install a GNU package is a minimal `make' utility and a minimal shell. Any native Unix shell and `make' will work. Both Autoconf and Automake take special steps to ensure that packages generated through the `distcheck' target can be easily installed with minimal tools. Autoconf generates `configure' shell scripts that use only portable Bourne shell features. (see section Portable shell programming) Automake ensures that the source code is in an autoconfiscated state when it is unpacked. It also regenerates the makefiles before adding them to the distribution, such that the installer targets (`all', `install', `uninstall', `check', `clean', `distclean') do not depend on GNU make features. The regenerated makefiles also do not use the `gcc' cruft to compute dependencies. Instead, precomputed dependencies are included in the regenerated makefiles, and the dependencies generation mechanism is disabled. This will allow the end-user to compile the package using a native compiler, if the GNU compiler is not available. For future reference we will call this the installer state. Now wear your installer hat, and install `hello-0.1.tar.gz':
% % % % % % gunzip hello-0.1.tar.gz tar xf hello-0.1.tar cd hello-0.1 configure make ./hello

This is the full circle. The distribution compiles, and by typing `make install' it installs. If you need to switch back to the developer hat, then you should rerun `automake' to get regenerate the makefiles. When you run the `distcheck' target, `make' will create the source code distribution `hello-0.1.tar.gz' and it will pretend that it is an installer and see if it the distribution can be unpacked, configured, compiled and installed. It will also run the test suite, if one is bundled. If you would like to skip these tests, then run the `dist' target instead:
% make dist

Nevertheless, running `distcheck' is extremely helpful in debugging your build cruft. Please never release a distribution without getting it through `distcheck'. If you make daily distributions for off-site backup, please do pass them through `distcheck'. If there are files missing from your distribution, the `distcheck' target will detect them. If you fail to notice such problems, then your backups will be incomplete leading you to a false sense of security.

5.4 Understanding the hello world example

When you made the `hello-0.1.tar.gz' distribution, most of the files were automatically generated. The only files that were actually written by your fingers were:
`hello.c' #include <stdio.h> main() { printf("Howdy, world!\n"); } `Makefile.am' bin_PROGRAMS = hello hello_SOURCES = hello.c `configure.in' AC_INIT(hello.cc) AM_INIT_AUTOMAKE(hello,1.0) AC_PROG_CC AC_PROG_INSTALL AC_OUTPUT(Makefile)

In this section we explain briefly what the files `Makefile.am' and `configure.in' mean.

The language of `Makefile.am' is a logic language. There is no explicit statement of execution. Only a statement of relations from which execution is inferred. On the other hand, the language of `configure.in' isprocedural. Each line of `configure.in' is a command that is executed. Seen in this light, here's what the `configure.in' commands shown do:

The AC_INIT command initializes the configure script. It must be passed as argument the name of one of the source files. Any source file will do. The AM_INIT_AUTOMAKE performs some further initializations that are related to the fact that we are using `automake'. If you are writing your `Makefile.in' by hand, then you don't need to call this command. The two comma-separated arguments are the name of the package and the version number. The AC_PROG_CC checks to see which C compiler you have. The AC_PROG_INSTALL checks to see whether your system has a BSD compatible install utility. If not then it uses `install-sh' which `automake' will install at the root of your package directory if it's not there yet. The AC_OUTPUT tells the configure script to generate `Makefile' from `Makefile.in'

The `Makefile.am' is more obvious. The first line specifies the name of the program we are building. The second line specifies the source files that compose the program. For now, as far as `configure.in' is concerned you need to know the following additional facts:

If you are building a library, then your configure script must determine how to handle `ranlib'. To do that, add the AC_PROG_RANLIB command. If your source code contains C++ files, you need to add the AC_PROG_CXX to your `configure.in'. If your source code contains `yacc' and `lex' files, then you need to add:
AC_PROG_YACC AC_PROG_LEX

to your `configure.in'. If your source code contains Fortran source code, you need to add `AC_PROG_FC' to your code. If you want to mix C and Fortran, then you need to do a lot more than just that. See section Using Fortran effectively, for more details.

If you have any makefiles in subdirectories you must also put them in the AC_OUTPUT statement like this:
AC_OUTPUT(Makefile dir1/Makefile dir2/Makefile ) \ \ \

Note that the backslashes are not needed if you are using the bash shell. For portability reasons, however, it is a good idea to include them. Make sure that every subdirectory where building takes place, is mentioned!

Now consider the commands that are used to build the hello world distribution:
% % % % % % aclocal autoconf touch README AUTHORS NEWS ChangeLog automake -a ./configure make

The first three commands bring the package in autoconfiscated state. The remaining two commands do the actual configuration and building. More specifically:

The `aclocal' command installs a file called `aclocal.m4'. Normally, in that file you are supposed to place the definitions of any `autoconf' macros that you've written that happen to be in use in`configure.in'. We will teach you how to write `autoconf' macros later. The `automake' utility uses the AM_INIT_AUTOMAKE macro which is not part of the standard `autoconf' macros. For this reason, it's definition needs to be placed in `aclocal.m4'. If you call `aclocal' with no arguments then it will generate the appropriate `aclocal.m4' file. Later we will show you how to use `aclocal' to also install your own `autoconf' macros. The `autoconf' command combines the `aclocal.m4' and `configure.in' files and produces the `configure' script. And now we are in business. The `touch' command makes the files `README' and friends exist. It is important that these files exist before calling Automake, because Automake decides whether to include them in a distribution by checking if they exist at the time that you invoke `automake'. Automake must decide to include these files, because when you type `make distcheck' the presence of these files will be required.

The `automake' command compiles a `Makefile.in' file from `Makefile.am' and if absent it installs various files that are required either by the GNU coding standards or by the makefile that will be generated.

The `configure' script probes your platform and generates makefiles that are customized for building the source code on your platform. The specifics of how the probing should be done are programmed in`configure.in'. The generated makefiles are based on templates that appear in `Makefile.in' files. In order for these templates to cooperate with `configure' and produce makefiles that conform to the GNU coding standards they need to contain a tedious amount of boring stuff. This is where Automake comes in. Automakes generates the `Makefile.in' files from the more terse description in `Makefile.am'. As you have seen in the example, `Makefile.am' files can be very simple in simple cases. Once you have customized makefiles, your make utility takes over. How does `configure' actually convert the template `Makefile.in' to the final makefile? The `configure' script really does two things: 1. It maintains a list of substitutions that it accumulates while probing the installer platform. Each one of these substitutions consists of a symbolic name, and the actual text that we want to substitute. When the`configure' script runs AC_OUTPUT it parses all of the files listed in AC_OUTPUT and every occurence of @FOO@ in these files is substituted with the text that corresponds to FOO. For example, if you add the following lines to `configure.in' you will cause @FOO@ to be substituted with `hello':
FOO="hello" AC_SUBST(FOO)

2. This is how `configure' exports compile-time decisions to the makefile, such as what compiler to use, what flags to pass the compilers and so on. Occasionally, you want to use `configure''s substitution capability directly on files that are not makefiles. This is why it is important to be aware of it. See section Scripts with Automake, for an example. 3. It maintains a list of C preprocessor macros with defined values that it also accumulates while probing the installer platforms. Before finishing off, `configure' will either generate a configuration file that defines these C preprocessor macros to the desired values, or set a flag in the generated makefile (through substitution) that will pass `-D' flags to the compiler. We discuss configuration headers in the following

See section Writing Autoconf macros, for more details on the internals of `configure' scripts.

5.5 Using configuration headers

If you inspect the output of `make' while compiling the hello world example, you will see that the generated Makefile is passing `-D' flags to the compiler that define the macros PACKAGE and VERSION. These macros are assigned the arguments that are passed to the AM_INIT_AUTOMAKE command in `configure.in'. One of the ways in which `configure' customizes your source code to a specific platform is by getting such C preprocessors defined. The definition is requested by appropriate commands in the `configure.in'. The AM_INIT_AUTOMAKE command is one such command. The GNU build system by default implements C preprocessor macro definitions by passing `-D' flags to the compiler. When there is too many of these flags, we have two problems: the `make' output becomes hard to read, and more importantly we are running the risk of hitting the buffer limits of braindead Unix implementations of `make'. To work around this problem, you can ask Autoconf to use another approach in which all macros are defined in a special header file that is included in all the sources. This header file is called a configuration header. A hello world program using this technique looks like this
`configure.in' AC_INIT(hello.c) AM_CONFIG_HEADER(config.h) AM_INIT_AUTOMAKE(hello,0.1) AC_PROG_CC AC_PROG_INSTALL AC_OUTPUT(Makefile) `Makefile.am' bin_PROGRAMS = hello hello_SOURCES = hello.c `hello.c' #ifdef HAVE_CONFIG_H #include <config.h> #endif #include <stdio.h> main() { printf("Howdy, pardner!\n"); }

To request the use of a configuration header we use the AM_CONFIG_HEADER command. The configuration header must be installed conditionally with the following three lines:
#if HAVE_CONFIG_H #include <config.h> #endif

It is important that `config.h' is the first thing that gets included. Now autoconfiscate the source code by typing:
% % % % % aclocal autoconf touch NEWS README AUTHORS ChangeLog autoheader automake -a

It is important to type these commands in the order shown. The difference between this, and what we did in Hello world example with Autoconf and Automake, is that we had to run a new program: `autoheader'. This program scans `configure.in' and generates a template file `config.h.in' listing all the C preprocessor macros that might be defined and comments that should accompany the macros describing what they do. When you run `configure', it will load in `config.h.in' and use it to generate the final `config.h' that will be used by the source code during compilation. Now you can go ahead and build the program:
% configure % make gcc -DHAVE_CONFIG_H -I. -I. -I. gcc -g -O2 -o hello hello.o

-g -O2 -c hello.c

Note that now instead of multiple -D flags, there is only one such flag passed: DHAVE_CONFIG_H. Also, appropriate -I flags are passed to make sure that `hello.c' can find and include `config.h'. To test the distribution, type:
% make distcheck ...... ======================== hello-0.1.tar.gz is ready for distribution ========================

and it should all work out.

The `config.h' files go a long way back in history. In the past, there used to be packages where you would have to manually edit `config.h' files and adjust the macros you wanted defined by hand. This made these packages very difficult to install because they required intimate knowledge of your operating system. For example, it was not unusual to see a comment saying "if your system has a broken vfork, then define this macro". Many installers found this frustrating because they didn't really know how to configure the esoteric details of the `config.h' files. With autoconfiguring source code all of these details can be taken care of automatically, shifting this burden from the installer to the developer where it belongs.

5.6 Maintaining the documentation files

Every software project must have its own directory. A minimal "project" is the example that we described in Hello world example with Autoconf and Automake. In general, even a minimal project must have the files:
README, INSTALL, AUTHORS, THANKS, NEWS, ChangeLog

Before distributing your source code, it is important to write the real contents of these files. In this section we give a summary overview on how these files should be maintained. For more details, please see the GNU coding standards as published by the FSF.

The README file: Every distribution must contain this file. This is the file that the installer must read fully after unpacking the distribution and before configuring it. You should briefly explain the purpose of the distribution, and reference all other documentation available. Instructions for installing the package normally belong in the `INSTALL' file. However if you have something that you feel the installer should know then mention it in this file. Do not make the configuration or installation process more complex, because you fear installers will not `README' files. Assume this file is being read. For pretest releases, only, you might also decide to distribute a file `READMEalpha' containing special comments for your friendly pretesters. If you use the recommended version numbering scheme (see sectionHandling version numbers), you can automate it's distribution by adding the following code in your `configure.in':
changequote(,)dnl case $VERSION in [0-9]*.[0-9]*[a-z]) DIST_ALPHA="README-alpha";; [0-9]*.[0-9]*.[0-9]*) DIST_ALPHA="README-alpha";;

*) DIST_ALPHA=;; esac changequote([, ])dnl AC_SUBST(DIST_ALPHA)

In your top-level `Makefile.am', add something like:

EXTRA_DIST = $(DIST_ALPHA)

The INSTALL file: Because the GNU installation procedure is streamlined, a standard `INSTALL' file will be created for you automatically by Automake. If you have something very important to say, it may be best to say it in the `README' file instead. the `INSTALL' file is mostly for the benefit of people who've never installed a GNU package before. However, if your package is very unusual, you may decide that it is best to modify the standard INSTALL file or write your own. The AUTHORS file: This file should collect a trace of all the legal paperwork that you have exchanged with contributors for your particular package. This information is very useful for registering the copyright of your package. The file might have an introductory blurb similar to this one:
Authors of PACKAGE The following contributions warranted legal paper exchanges with [the Free Software Foundation | Your Name]. Also see files ChangeLog and THANKS

Then, list who the contributors are and what files they have worked on. Indicate whether they created the file, or whether they modified it. For example:
Random J. Hacker: entire files -> foo1.c , foo2.c , foo3.c modifications -> foo4.c , foo5.c

The THANKS file: All distributions should contain a `THANKS' file containing a two column list of the contributors, one per line, alphabetically sorted. The left column gives the contributor's name, while the right column gives the last known good email address for this contributor. This list should be introduced with a wording similar to this one:
PACKAGE THANKS file PACKAGE has originally been written by ORIGINAL AUTHOR. Many people further contributed to PACKAGE by reporting problems, suggesting various improvements or submitting actual code. Here is a list of these people. Help me keep it complete and

exempt of errors.

The easiest policy with this file is to thank everyone who contributes to the project, without judging the value of the contribution. Unlike `AUTHORS', the `THANKS' file is not maintained for legal reasons. It is maintained to thank all the contributors that helped you out in your project. The `AUTHORS' file can not be used for this purpose because certain contributions, like bug reports or ideas and suggestions do not require legal paper exchanges. You can also decide to send some kind of special greeting when you initially add a name to your `THANKS' file. The mere presence of a name in `THANKS' is then a flag to you that the initial greeting has been sent. The NEWS file: List the major new features of this distribution and identify the version that they pertain to. Don't discard items from previous versions. Leave them in the file after the newer items, so that a user upgrading from any previous version can see what is new. The ChangeLog file: Use this file to record all the changes that you make to your source code. If your source code is distributed among many subdirectories, and there is reason enough to think of the contents of the subdirectories as different subpackages,then please maintain a separate `ChangeLog' file for each subdirectory. For example, although there is usually no need to maintain a `ChangeLog' for your documentation, if you do decide to maintain one anyway, it should be separate from your sources `ChangeLog'. The GNU coding standards explain in a lot of detail how you should structure a `ChangeLog', so you should read about it there. The basic idea is to record semi-permanant modifications you make to your source code. It is not necessary to continuously record changes that you make while you are experimenting with something. But once you decide that you got a modification worked out, then you should record Please do record version releases on the central `ChangeLog' (see section Handling version numbers). This way, it will be possible to tell what changes happened between versions. You can automate `ChangeLog' maintenance with emacs. See section Navigating source code, for more details. Recently versions of Emacs use the ISO 8601 standard for dates which is: YYYY-MM-DD (year-month-date). A typical `ChangeLog' entry looks like this:
1998-05-17 Eleftherios Gkioulekas <lf@amath.washington.edu>

* src/acmkdir.sh: Now acmkdir will put better default content

to the files README, NEWS, AUTHORS, THANKS

Every entry contains all the changes you made within the period of a day. The most recent changes are listed at the top, the older changes slowly scroll to the bottom. Changes are sorted together in groups, per day of work.

COPYING This file contains the copyright permissions for your distribution, in particular the General Public License (see section Licensing Free Software). This file is generated automatically for you by Automake. However, it requires that you insert copyright headers in your source code that refer to this file. See section Applying the GPL, for more details. Copyright is one of the many legal concerns that you need to be aware of if you develop free software. See section Legal issues with Free Software, for more details. The philosophy of the GNU project, that software should be free, is very important to the future of our community. See section Philosophical issues, to read Richard Stallman's essays on this topic.

5.7 Organizing your project in subdirectories

If your program is very small, you can place all your files in the top-level directory, like we did in the Hello World example (see section Hello world example with Autoconf and Automake). Such packages are calledshallow. In general, it is preferred to organize your package as a deep package. In a deep package, the documentation files
README, INSTALL, AUTHORS, THANKS, ChangeLog, COPYING

as well as the build cruft are placed at the top-level directory, and the rest of the files are placed in subdirectories. It is standard practice to use the following subdirectories: `src' The actual source code that gets compiled. Every library should have it's own subdirectory. Executables should get their own directory as well. If each executable corresponds only to one or two files then it is sensible to put them all under the same directory. If your executables need more source files, or they can be separated in distinct classes of functionalities you may like to regroup them under multiple directories. Feel free to use your judgment on how to do this best. It is easiest to place the library test suites on the same directory with the library source code. If that does not sit well with you however, you should

put the test suite for each library in subdirectories under that library's directory. It is a massively bad idea to put the test suites for different libraries under the same directory. `lib' An optional directory where you put portability-related source code. This is mainly replacement implementation for system calls that are unavailable on some systems. You can also put tools here that you commonly use across many different packages, tools that are too simple to just make libraries out of every one of them. Common files encountered here are files that replace system calls to the GNU C library that are not available in proprietary C libraries. `doc' A directory containing the documentation for your package. You have the creative freedom to present the documentation in any way that is effective. However the preferred way to document software is by using Texinfo. Texinfo has the advantage that you can produce both on-line help as well as nice printed books from the same source. Documentation is discussed in more detail in See section Maintaining Documentation. `m4' A directory containing `m4' files that you package may need to install. These files define new `autoconf' macros that you should make available to other developers who want to use your libraries. This is discussed in more detail in FIXME: cross reference. `intl' A directory containing boilerplate portability source code that allows your program to speak in many human languages. The contents of this directory are automatically maintained by `gettext'. (FIXME: cross reference) `po' A directory containing message catalogs for your software package. This is where the maintainer places the translations of per software in multiple human languages. (FIXME: cross reference)

Automake makes it very easy to maintain multidirectory source code packages, so you shouldn't shy away from taking advantage of it. Multidirectory packages are more convenient for most projects.

5.9 Handling version numbers

The number `0.1' in the filename `hello-0.1.tar.gz' is called the version number of the source code distribution. The purpose of version numbers is to label the various releases of a source code distribution so that it's development can be tracked. If you use the GNU build system, then the name of the package and the version number are specified in the line that invokes the `AM_INIT_AUTOMAKE' macro. In the hello world example (see section Hello world example with Autoconf and Automake) we used the following line to set the version number equal to 0.1:
AM_INIT_AUTOMAKE(hello,0.1)

Whenever you publish a new version of your program, you must increase the version number. We also recommend that you note on `ChangeLog' the release of the new version. This way, when someone inspects your`ChangeLog', person will be able to determine what changes happened between any two specific versions. To release the current version of your source code, run
% make distcheck

to build the distribution and apply the test suite to validate it. Once you get this to work, change your version number in `configure.in', record an entry in `ChangeLog' saying that you are cutting the new version, and update the `NEWS' file. Without making any other changes, do
% make dist

to rebuild the distribution without having to wait for the test suite to run all over again. Most packages declare their version with two integers: a major number and a minor number that are separated by a dot in the middle. In our example above, the major number is 0 and the minor number is 1. The minor number should be increased when you release a version that contains new features and improvements over the old version that you want your users to upgrade to. The major number should be increased when the incremental improvements bring your program into a new level of maturity

and stability. A major number of 0 indicates that your software is still experimental and not ready for prime time. When you release version 1.0, you are telling people that your software has developed to the point that you recommend it for general use. Releasing version 2.0 means that your software has significantly matured from user feedback. Before releasing a new major version, it is a good idea to publish a prerelease to your beta-testers. In general, the prerelease for version 1.0 is labeled 0.90 regardless of what the previous minor number was. (8) When releasing a 0.90 version, development should freeze, and you should only be fixing bugs. If the prerelease turns out to be stable, it becomes the stable version. If not, you may need to release further bugfixing prereleases: 0.91, 0.92, etc. Many maintainers like to publish working versions of their code, so that contributors can donate code against the most recent version of the source code. These unofficial versions should only be used by people who are interested in contributing to the project, and not by end users. It is useful to use a third integer for writing the version numbers for these "unofficial" releases. Please use only two integers for official releases so that it is easy to distinguish them from unofficial releases. A possible succession of version numbers might look like this:
0.1, 0.1.1, 0.1.2, ... , 0.2, ..., 0.3, ..., 0.90, ..., 1.0

It is always a good idea to maintain an archive of at least all the official releases that you ever publish.

5.10 Hello world with acmkdir

Whenever you start out a new programming project, there is quite a bit of overhead setup that you need to do in order to use the GNU build system. You need to install the documentation files described in Maintaining the documentation files, and set up the directory structure described in Organizing your project in subdirectories. In the quest for never-ending automation, you can do these tasks automatically with the `acmkdir' utility. Start by typing the following command on the shell:
% acmkdir hello

`acmkdir' will ask you to enter the name of your program, your name and your email address. When you are done, `acmkdir' will ask you if you really want to go for it. Say `y'. Then, `acmkdir' will do the following routine work for you:

Create the `hello-0.1' directory and the `doc', `m4' and `src' subdirectories. Generate the following `configure.in':
AC_INIT AM_CONFIG_HEADER(config.h) AM_INIT_AUTOMAKE(test,0.1) AC_PROG_CC AC_PROG_CXX AC_PROG_RANLIB AC_OUTPUT(Makefile doc/Makefile m4/Makefile src/Makefile)

By default, both the C and C++ compilers are initialized, but you can take out `AC_PROG_CXX' if you don't plan to use C++. You can edit and customize this file to your needs. More specifically, you will need to update the version number in `AM_INIT_AUTOMAKE' every time you cut a new distribution (see section Handling version numbers). You should also make sure to list all the subdirectories that have a`Makefile.am' in `AC_OUTPUT'. Place boilerplate `Makefile.am' files on the toplevel directory as well as the `doc', `m4' and `src' subdirectories. The toplevel `Makefile.am' contains:
EXTRA_DIST = reconf configure SUBDIRS = m4 doc src

The ones in the src and doc subdirectories are empty. The one in `m4' contains a template `Makefile.am' which you should edit if you want to add new Autoconf macros. (FIXME: Crossreference) Create the files `COPYING', `INSTALL', `AUTHORS', `NEWS', `README', `THANKS' and `ChangeL og' and generate their default contents which you should edit further as you develop your package. (see sectionMaintaining the documentation files) Create a `reconf' script for reconfiguring your package every time you make a change in `configure.in'. Running `reconf' is equivalent to running the following commands on the shell from the top-level directory:
% % % % % % % rm -f config.cache rm -f acconfig.h aclocal -I m4 autoconf acconfig autoheader automake -a

Before `acmkdir' exits, it will call the `reconf' script for you once to set things up.

At this point, you can run

% ./configure % make

but nothing interesting will happen because the package is still empty. To add a simple hello world program, all you need to do is create the following two files:
`src/Makefile.am' bin_PROGRAMS = hello hello_SOURCES = hello.c `src/hello.c' #if HAVE_CONFIG_H # include <config.h> #endif #include <stdio.h> int main () { printf ("Hello world\n"); }

and type the following commands from the toplevel directory:

% % % % ./reconf ./configure make make distcheck

to compile the hello world program and build a distribution. It's that simple! In general, to develop simple programs with the GNU build system you setup the project directory tree with `acmkdir', you write your source code, you put together the necessary `Makefile.am' and update`configure.in' and you are set to go. In fact, at this point you practically know all you need to know to develop source code distributions that compile and install simple C programs. All you need to do is write the source code and list the source files in `*_SOURCES'. In the following chapters we will explain in more detail how to use the GNU build system to develop software that conforms to the GNU coding standards.