TITLE: GNU Autotools AUTHOR: Elko Holl DATE: 2003-09-16 LICENSE: GNU Free Documentation License Version 1.2 SYNOPSIS: Introduction to the GNU Autotools. DESCRIPTION: This document describes the steps you must take to start a project in GNU fashion. You'll learn to use autoconf and automake to create portable configure scripts and Makefiles. PREREQUISITES: This hint requires that you have a little general knowledge of programming. HINT: $Id: autotools.txt,v 1.3 2003/09/16 19:10:55 tushar Exp $ Contents -------- * Preface * Versions * Creating the source file(s) * Adapting configure.in * Creating config.h.in * Creating Makefile.am and Makefile.in * Creating the configure script * Testing the result * Making a distribution * Related documents and links * Suggestions Preface ------- Ok, so you have your BLFS finished and have all the applications you can think of installed. Now what? You start to learn BaSH, Perl, C and kernel internals and finally, you code up some cool program which you think is worth uploading to SourceForge or Freshmeat for example. But how are you going to distribute your program? Just pack everything in a tarball and present a Makefile to your users that they have to modify? NO! You want your project to be like all the packages you already installed, so that means having a configure script so you can at least specify the installation --prefix for your program. With the GNU range of applications this means using autoconf and automake, rather then coding the required files yourself; these programs are part of the GNU Autotools collection. Here is a quote from the autoconf manual: "Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of UNIX-like systems. The configuration scripts produced by Autoconf are independent of Autoconf when they are run, so their users do not need to have Autoconf." For more information on autoconf and automake skip to the section at the bottom titled "Related documents". It is assumed that you already know a bit about writing a Makefile. If this is not the case, then you can use this Make manual (if needed) while reading: http://www.gnu.org/manual/make/ Note: You can use Makefiles for more then C-program compilation, you can for example create targets for commonly used functions (shell-scripts). If this doesn't ring a bell right now, read the Make manual and it will start to make sense (i.e. `make backup' for your system operators). Versions -------- The versions of autoconf and automake used in this document are: [elko@elkos ~]$ (autoconf -V;automake --version) 2>&1 | grep "^auto" autoconf (GNU Autoconf) 2.52 automake (GNU automake) 1.6.1 Sometimes, newer versions of autoconf and automake may cause some not so up-to-date applications to fail to compile on your system. You can always downgrade autoconf or automake again; so if you experience any problems building certain packages after upgrading to the versions used in this document, try to downgrade first before complaining somewhere. If you are happy with your autoconf and automake release, and don't want to upgrade, then this document can still be used as a quick guide to start a project; some of the semantics may differ though, consult the documentation of your release for the details. Creating the source file(s) --------------------------- This document only uses one source file, since it's just a quick guide to start a GNU fashion project. In almost any situation, your project will have more then one source file. That is why it is wishful that you know how to write Makefiles, since more sourcefiles mean more described dependencies in your 'Makefile.am'; more on that later. Read along or skip to the section called "Related documents" (at the bottom) and get your information there. First, create a directory where you start your project and create the famous "Hello World!" source-file (a slightly altered version though): cd $HOME && mkdir hello && cd hello && cat >hello.c < #endif #include #include int main() { fprintf (stdout, "Hello World!\n"); #ifdef _WITH_GOODBYE sleep (1); fprintf (stdout, "Goodbye Cruel World!\n"); #endif return (0); } EOHF Note that there are some header-files included and there is a symbol definition check present to change the behavior of the program. This is done on purpose to show some details of the Autotools; almost every project you create will have conditionals in the source to enhance or alter the behavior of your software. The #ifdef and #ifndef statements play an important part in your flexibility with the GNU Autotools. The next step is to create the 'config.h' file, which autoscan uses to create the input file for autoheader: cat >config.h <Makefile.am 2>/dev/null <', which will quietly fail if the directory is not empty. Making a distribution --------------------- It is possible to create a tarball from your project by executing: make dist In this example you would end up with a file called "hello-1.0.tar.gz", and a file "hello-1.0.tar.bz2" since the target has dependencies, check what the package contains: tar tvzf hello-1.0.tar.gz If you would only like a bzipped tarball, execute: make dist-bzip2 && ls -l hello-1.0.tar.bz2 && tar tvjf hello-1.0.tar.bz2 Hint: If you install "bash_completion" (available on http://freshmeat.net), then you can get all available make targets by entering 'make ' and pressing TAB twice (notice the space after the `make' command!). With bash_completion, the same is true for `./configure --', which will list the available configure options; very neat indeed! To end the foolishness of making a GNU package of a 326 byte hello.c sourcefile, unpack the distribution you just made and see that it is 258048 bytes now; that is ~791.56 times bigger then the original sourcefile: tar xjf hello-1.0.tar.bz2 && du -sb hello-1.0 But it is supposed to be portable now. Related documents and links --------------------------- For a full description and all the macros's you can use, visit: http://www.gnu.org/manual/make/ http://www.gnu.org/manual/autoconf/ http://www.gnu.org/manual/automake/ For information about installing the Autotools, see Linuxfromscratch: http://www.linuxfromscratch.org/view/cvs/chapter06/make.html http://www.linuxfromscratch.org/view/cvs/chapter06/autoconf.html http://www.linuxfromscratch.org/view/cvs/chapter06/automake.html I recommend reading this as well: http://sources.redhat.com/autobook/autobook/autobook_toc.html Other links to sites mentioned in this document: http://sourceforge.net http://freshmeat.net Suggestions ----------- If you have any questions about, or suggestions for this document, then please contact the author. If this document has been of any use to you or if you are making a translation of it, please drop the author an email, your feedback is very WelkoM. Happy Landings! CHANGELOG: [2002/07/15] * Initial hint. [2003-09-16] * Just some textual changes for the new format.