GNU Automake

index -|- references -|- end

Preamble:

2009-04-22: Update: This original page was written running cygwin in Windows XP. While this functioned just 'ok', I eventually installed Ubuntu linux as a dual boot, and REMOVED cygwin completely. Accordingly, this page has been updated to using the 'automake' tools in that system...

The following is 10 steps to make a program, a binary executable, in cygwin, using 'automake', 'autoconf', './configure', and 'make' ... I am still very new to this environment, so any 'old-pro' reading this should just be amused ;=)) I can only get BETTER ...

Ok, as usual, the process is relatively EASY, and quite PAINLESS, once you KNOW HOW ;=))

top


Project: testap

This is a simple project, with only one(1) 'src' folder. This sample created a 'testap.exe' in cygwin, and just 'testap' in Ubuntu, from a single source, 'testap.cxx', given below ... but it should be easy to extend it ... more source, more source folders, and include special libraries ... you have to start small ;=))

Step 1: Build Directory Structure

Choose a 'root' folder for the project, in this case I have chosen a folder called 'testap2'. Place the source file, or files, in the 'src' subdirectory ...

Step 2: Write the Makefile.am Files

Create two (2) 'Makefile.am' files, with some simple information ... one for the project root, and one for the 'src' folder ... the following are the contents, which should be easy to follow, duplicate, and expand on ...

<content file="Makefile.am">
# Makefile.am

SUBDIRS = src

</content>
<content file="src/Makefile.am">
# src/Makefile.am

bin_PROGRAMS = testap

testap_SOURCES = testap.cxx

INCLUDES = -I$(top_srcdir) -I$(top_srcdir)/src
</content>

Step 3: Create a configure.ac (or configure.in) File

A lot can be read about the macros contained in this file, and some testing and case switching can be very complicated, but here is my minimalist contents :-
<content file="configure.ac">
# configure.am

AC_INIT([testap], [0.0.1], [username@domain.com], [testap])

PACKAGE=testap
VERSION=0.0.1

AC_ARG_PROGRAM
AC_PROG_MAKE_SET
AC_PROG_CC
AC_PROG_CPP
AC_PROG_CXX
AC_PROG_RANLIB
AC_PROG_INSTALL

AC_CONFIG_FILES([Makefile src/Makefile])
AC_OUTPUT
</content>

Step 4: Populate with Other Files

As per the '$automake --help' certain files are automatically distributed. Although it says, 'if found', it emits warnings of some are not, and it can automatically create others ...

The files I created were :-
AUTHORS, NEWS, README, ChangeLog
I have just put a few words in each, but note they are sometimes of zero length in certain projects!

The files 'automake' will copy, create, are :-
COPYING, INSTALL, install-sh, missing, and mkinstalldirs

Step 5: Run automake -a -c -v

Run the command -
$ automake -a -c -v

As the command $ automake --help will show, this creates a 'Makefile.in' from your 'configure.ac' (or 'configure.in') and 'makefile.am' files ...

If this is all successful, then by now you will have a considerable list of files :-

~/testap2 $ ls -l
   total 66
   -rw-r--r-- 1 username None 38 Nov 19 16:25 AUTHORS
   -rwxr-x--- 1 username None 17992 Nov 19 15:11 COPYING
   -rw-r--r-- 1 username None 45 Nov 19 16:26 ChangeLog
   -rwxr-x--- 1 username None 7831 Nov 19 15:11 INSTALL
   -rwxrwxrwx 1 username None 32 Nov 19 02:47 Makefile.am
   -rw-r--r-- 1 username None 9848 Nov 19 16:50 Makefile.in
   -rw-r--r-- 1 username None 22 Nov 19 16:23 NEWS
   -rw-r--r-- 1 username None 32 Nov 19 16:24 README
   -rw-r--r-- 1 username None 254 Nov 19 16:21 configure.in
   -rwxr-x--- 1 username None 5598 Nov 19 15:11 install-sh
   -rwxr-x--- 1 username None 6480 Nov 19 15:11 missing
   -rwxr-x--- 1 username None 722 Nov 19 15:11 mkinstalldirs
   drwxrwxrwx+ 2 username None 0 Nov 19 16:49 src
   ~/testap2 $ ls src -l
   total 14
   -rwxrwxrwx 1 username None 121 Nov 19 02:47 Makefile.am
   -rw-r--r-- 1 username None 9061 Nov 19 16:50 Makefile.in
   -rwxrwxrwx 1 username None 165 Nov 18 12:26 testap.cxx
   ~/testap2

Not bad for a tiny one-source-file project ;=)) but you are NOT finished ...

Step 6: Run 'autoconf' to Generate 'configure'

You should now be ready to run the command '$ autoconf' ...

If this run successfully, you should have two more entries in the root folder -
drwxr-xr-x+ 2 username None 0 Nov 19 17:02 autom4te.cache
-rwxr-xr-x 1 username None 117413 Nov 19 17:02 configure

Step 7: Run $./configure to Generate the 'makefile' Set

You can run the command -
$ ./configure --help
and read more about this process. The important thing is where to 'install' the final application, or library, if building a library ... the --help will advise you the default, but this simple application does not need to be installed there.

As the help states -
"By default, `make install' will install all the files in `/usr/local/bin', `/usr/local/lib' etc. You can specify an installation prefix other than `/usr/local' using `--prefix', for instance `--prefix=$HOME'."

Try the command -
$ ./configure --prefix=$HOME

I have not worked out yet, how to give a name to the executable binary, so it defaults to the generic 'a.exe' ... an extract of the lines of output from this step show this -
checking for C compiler default output file name... a.exe
but later my chosen name is used, so perhaps this can be ignored ...

The files I wanted have been created ... the last few lines of output -
configure: creating ./config.status
config.status: creating Makefile
config.status: creating src/Makefile

And verifying this -
$ ls Makefile -l
-rw-r--r-- 1 username None 10166 Nov 19 17:15 Makefile
$ ls src/Makefile -l
-rw-r--r-- 1 username None 9527 Nov 19 17:15 src/Makefile

Step 8: The 'make' of the Application

Finally we are ready for the 'make' ... it will use the 'Makefile', and 'src/Makefile' to compile, and link the application ... enter the command :-
$ make
As the output shows -
Making all in src
This defaults to making all in the src folder ... and a check of what new files were created, if the compile and link was successful :-
-rwxr-xr-x 1 username None 31398 Nov 19 17:25 testap.exe
-rw-r--r-- 1 username None 22958 Nov 19 17:25 testap.o

The 'testap.exe' is the executable binary, and the 'testap.o' is the object file. If you look closely at the compile input line you will note a '-g' ... this builds the DEBUG version ... that is a version that contains lots of debug information, whether you wanted it or not ... this is removed later ...

At this point the new application can be run by a simple command :-
$ ./src/testap

Step 9: The Final Installation

You are now ready to 'install' the application in your desired directory, so using the command 'make install' achieves this ... this is not necessarily a good place to 'install' it ... this is just for example ... here is the output :-
~/testap2
$ make install
Making install in src
make[1]: Entering directory `/home/username/testap2/src'
make[2]: Entering directory `/home/username/testap2/src'
/bin/sh ../mkinstalldirs /home/username/bin
mkdir /home/username/bin
/usr/bin/install -c testap /home/username/bin/testap
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/username/testap2/src'
make[1]: Leaving directory `/home/username/testap2/src'
make[1]: Entering directory `/home/username/testap2'
make[2]: Entering directory `/home/username/testap2'
make[2]: Nothing to be done for `install-exec-am'.
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/username/testap2'
make[1]: Leaving directory `/home/username/testap2'

~/testap2
You will note it used the mkinstalldirs script to create a folder in your $HOME, called 'bin' ...

Step 10: Clean up - The strip!

Until I learn how to instruct the compiler to only build the release version, this extra step is require, unless you wish to leave this large executable as is ...

Changing directory to $HOME/bin, I run the following commands ... the 'strip' is the important one -
~/bin
$ ls -l
total 32
-rwxr-xr-x 1 username None 31398 Nov 19 17:35 testap.exe
~/bin
$ strip testap.exe
~/bin
$ ls -l
total 4
-rwxr-xr-x 1 username None 3072 Nov 19 17:41 testap.exe
~/bin
$ ./testap.exe
Test application ...
~/bin

You will note, stripped of all debug information, the file size goes from 31398 bytes, down to a tidy 3072 bytes ... but the file still runs as an executable ...

And finally here is the SIMPLE SOURCE of testap.cxx

<source file="testap.cxx">
// testap.cxx
#include <stdio.h>

int main( int argc, char * argv[] ) {

   printf( "Test application ...\n" );

   return 0;
}
// eof - testap.cxx
</source>

Now you have it all ... while it seems a lot initially, once you get the hang of it, it all becomes second nature ;=)) Armed with this information, you should be able to build an application of any size and scope, like say FlightGear (http://www.flightgear.org) ... most sources you download will already supply many of the above 'build' files ... thus the build make begin at Step 6 or 7 ...

back

Some insights, AFTER-THE-FACT ;=))

After running, in the CVS PLIB (copy of) folder :-
$ automake -a -c -v (Step 5:)
to create 'Makefile.in', and then -
$ autoconf -v -f (Step 6:)
to create the 'configure', then -
$ ./configure prefix=/fg-0.9.9  (Step7:)
I got an ERROR, namely :-
./configure: line 1343: syntax error near unexpected token `plib,'
./configure: line 1343: `AM_INIT_AUTOMAKE(plib, 1.8.4)'
WHY?

Is there a clue in the 'warning' line as 'autoconf -v -f' runs? :-
configure.in:14: error: possibly undefined macro: AM_INIT_AUTOMAKE

And should I be running 'autoreconf' instead? But this was m FIRST run of 'autoconf' in this folder, AND I added the '-f' parameter to FORCE a re-build ... some references, found using 'unix AM_INIT_AUTOMAKE' in Yahoo! ...

From: http://www.openismus.com/documents/linux/automake/automake.shtml ...
It states, in part -
<quote>
Lines which every configure.ac should have
Every configure.ac should have lines like the following:
AC_INIT(hello.cc)
AM_INIT_AUTOMAKE(hello,0.1)
AC_PROG_CC
AC_PROG_CXX
AC_PROG_INSTALL
AC_OUTPUT(Makefile)

The AC_INIT macro can take any source file as an argument. It just checks that the file is there, which should, in turn, mean that the source directory is there.
The AM_INIT_AUTOMAKE line adds several standard checks. It takes the program name and version number as arguments.
AC_PROG_CC indicates that the source code may be in C. If the source code is C++ then we also need AC_PROG_CXX.
AC_PROG_INSTALL will generate an install target so that users may just type 'make install' to install the software.
AC_OUTPUT indicates the name of the Makefile which will be generated.
</quote>

On using 'automake' to generate 'Makefile.in' from the 'Makefile.am' see -
http://www.gnu.org/software/automake/manual/html_mono/automake.html
which makes statements like -
"The variable definitions and targets in the Makefile.am are copied verbatim into the generated file."
and it also bleats -
"The first step is to update your configure.in to include the commands that automake needs. The way to do this is to add an AM_INIT_AUTOMAKE call just after AC_INIT:

AC_INIT(zardoz, 1.0)
AM_INIT_AUTOMAKE
..."

Note, this 'AM_INIT_AUTOMAKE' has NO parameters!

It adds the comments -
"Now you must regenerate configure. But to do that, you'll need to tell autoconf how to find the new macro you've used. The easiest way to do this is to use the aclocal program to generate your aclocal.m4 for you. But wait... maybe you already have an aclocal.m4, because you had to write some hairy macros for your program. The aclocal program lets you put your own macros into acinclude.m4, so simply rename and then run:
mv aclocal.m4 acinclude.m4
aclocal
autoconf
Now it is time to write your Makefile.am for zardoz. ..."

What is this 'aclocal'? ... I have NOT included it in my 'steps'! Running '$ aclocal' certainly generates a NEW file -
-rw-r--r-- 1 username None 37294 Nov 19 22:49 aclocal.m4
then 'autoconf -v -f' (Step6:) to generate the 'configure' ...
then './configures --prefix=/fg-0.9.9 (Step7:)

NOW './confgure --prefix=/fg-0.9.9' runs FINE ... and the 'makefile' set is generated ... but when I run 'make' I am BACK at the error, where all this STARTED!
~/PLIB
$ make
Makefile:322: *** missing separator (did you mean TAB instead of 8 spaces?). Stop.
~/PLIB

Bah! BAH!! BAH!!!

Be back another day! ... the 'auto' software WILL NOT WIN ;=))

top


References

http://www.openismus.com/documents/linux/automake/automake.shtml
Had a recommended reading list -

 

top


back -|- top

checked by tidy  Valid HTML 4.01 Transitional