== autoconf and automake ==


Perform the following steps to get the [http://www.gnu.org/software/autoconf autoconf]/[http://www.gnu.org/software/automake automake] tools from the [http://en.wikipedia.org/wiki/GNU_build_system GNU build system] working for you. The example shows how to set things up such that the binary ''startCompletionServer'' is built by a call to "./configure; make" and that the distribution ''autocomplete-0.1.tar.gz'' is built by a call to "make distcheck".

Create the file ''configure.in'':
{{{
AC_INIT(StartCompletionServer.cpp)
AM_INIT_AUTOMAKE(autocomplete,0.1)
AC_PROG_CC
AC_PROG_CXX
AC_PROG_INSTALL
AC_OUTPUT(Makefile)
}}}

Create the file ''Makefile.am'':
{{{
INCLUDES = -I/.
LDFLAGS =  -L/KM/ir/berkeleydb/lib -static
LDADD = -lpthread -ldb_cxx-4.2 -lz

bin_PROGRAMS = startCompletionServer

startCompletionServer_SOURCES = \
               StartCompletionServer.cpp Globals.cpp \
               HYBCompleter.cpp \
               IndexBase.cpp History.cpp codes.cpp nrutil.c \
               QueryParameters.cpp \
               HYBIndex.cpp INVIndex.cpp WordsFile.cpp \
               ConcurrentLog.cpp DocsDB.cpp Document.cpp \
               ExcerptsGenerator.cpp ExcerptsDB.cpp \
               CompletionServer.cpp CompleterBase.cpp \
codes.h                        HYBIndex.h \
CompleterBase.h                IndexBase.h \
CompletionServer.h             INVCompleter.h \
Completions.h                  INVIndex.h \
CompressionAlgorithm.h         MetaInfo.h \
ConcurrentLog.h                nrutil.h \
DocList.h                      Query.h \
DocsDB.h                       QueryParameters.h \
Document.h                     QueryResult.h \
DummyCompressionAlgorithm.h    ScoreAggregators.h \
Exception.h                    Separator.h \
ExcerptData.h                  server.h \
ExcerptsDB.h                   Simple9CompressionAlgorithm.h \
ExcerptsDB_NEW.h               Timer.h \
ExcerptsGenerator.h            TrivialCompressionAlgorithm.h \
File.h                         Vector.h \
Globals.h                      WordList.h \
History.h                      WordRange.h \
HuffmanCompressionAlgorithm.h  WordsFile.h \
                               ZipfCompressionAlgorithm.h \
HYBCompleter.h

}}}

Now type the following commands:

{{{
$ aclocal    # create file aclocal.m4 (ignore this file on first use)
$ autoconf   # create file configure from configure.in
$ touch NEWS README AUTHORS ChangeLog   # automake insists on these files existing
$ automake -a   # create file Makefile.in from Makefile.am; create missing files such as install.sh
}}}

Now you are in the same state that the end user of your package will be. You can now make the binary and run it:

{{{
$ ./configure
$ make
$ ./startCompletionServer
}}}

To make the distribution file ''autocomplete-0.1.tar.gz'', type the following:
{{{
$ make distcheck
}}}

This will create a file called ''autocomplete-0.1.tar.gz'' in the current working directory (which contains all the source code), and test it out to see whether all necessary files are included and whether the source code passes the regression test suite (if you have such a suite).

Read here for a fine tutorial on the GNU build system: http://autotoolset.sourceforge.net/tutorial.html#SEC39.

=== 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 ''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'''.

To use this file, do the following:

Add the following 2nd line to ''confgure.in'':

{{{
AC_INIT(StartCompletionServer.cpp)
AM_CONFIG_HEADER(config.h)
AM_INIT_AUTOMAKE(autocomplete,0.1)
...
}}}

Add the following at the top of ''Globals.h'':
 	
{{{
#if HAVE_CONFIG_H
#include <config.h>
#endif
}}}

Now issue the following commands:

{{{
$ autoconf
$ autoheader # scans configure.in and generates a template file config.h.in
$ automake
$ ./configure
$ make
}}}


== Starting from scratch with autoproject ==

If you start a project from scratch, you might consider using the autoproject tool:

autoproject  simplifies the creation of a source package for a new program.  
The idea is that you execute  autoproject  just  once  when  you
       start  a  new  project.  It will create a new directory and populate it
       with standard files, customized for the new project.

In an empty directory, just do an

{{{
$ autoproject
}}}

and answer the questions.