Adding back svn-ignore file (accidentaly removed during git import)
[autotools.git] / README
1 == Introduction ==
2
3 These are templates for a modern autoconf/automake build system,
4 using separate directories for everything and non-recursive make.
5
6 This document assumes you have basic notions of what autoconf and automake
7 are. It uses some modern features of autotools which are not so common.
8
9 Please read http://moin.conectiva.com.br/AutotoolsetTips for some tips
10 (or the local copy: AutotoolsetTips.html, available with this template).
11
12 This template is licensed under the GNU-GPL, which basically means any
13 changes in the build-scripts must be made public and released under the
14 same license if they're ever distributed. See the COPYING file for
15 details.
16
17 The build-system code can be downloaded from:
18 http://svn.ademar.org/code/trunk/autotools-build_system-template
19
20 If you have any question or believe you need an exception for this
21 license, please contact Ademar Reis <ademar@ademar.org>.
22
23
24 == Descriptions of template files ==
25
26  - configure.ac: if you don't know what this file is, you should read a
27                  tutorial or two about autoconf;
28  - Makefile.am: if you don't know what this file is, you should read a
29                 tutorial or two about automake;
30  - *.pc.in: pkg-config files. See the list of resources below;
31  - mk/auxdevel.am: main makefile addons (included in Makefile.am);
32  - mk/libtool-fix.am: fix for b0rken "make -s" on some systems when
33                       using libtool;
34  - m4/auxdevel.m4: main autoconf macros used by this template;
35  - m4/check.m4: macros to support unit-tests via check;
36  - m4/acx_pthread.m4: autoconf macros to search for pthread in a portable
37                       way on different unixes;
38  - m4/define_dirs.m4: autoconf macros that define installation directories
39                       at configure time;
40
41
42 == Usage ==
43
44 You should be able to understand the way this template works by looking at
45 the source, output and the examples inside configure.ac and Makefile.am.
46
47 Important hints:
48   - autoreconf is all you need to run in order to generate the build
49     scripts (see the step-by-step guide below);
50   - configure should not be run on the top directory. You should create
51     a build directory and call configure from there (see the step-by-step
52     guide below);
53   - If you don't understand what a particular macro or keyword means, try
54     looking for its documentation on the info pages or google for it.
55
56 A step-by-step guide:
57
58   * Change configure.ac and Makefile.am, changing source-code references and
59     removing what you don't need. The template includes as output config
60     files, pkgconfig and has a lot of other features which probably are not
61     needed by your project;
62   * If you're building libraries, rename and fill the *.pc.in files
63   * Run "autoreconf -ifs" (see --help) to generate the configure and other
64     necessary scripts.
65   * To build your software, create a build-directory and run configure from
66     there (avoid polution on the top directory, as most autotools based
67     software do); Examples of correct configure usage:
68     $ mkdir build; cd build; ../configure; make; make install; [...]
69     $ mkdir /tmp/bla; cd /tmp/bla; /path-to-project/configure; make; [...]
70   * To confirm that everything is OK, run "make distcheck";
71   * To test installation, use "make install DESTDIR=/whatever-tmp-dir";
72   * To reference an installation path inside the source-code, use the set of
73     macros provided by m4/define-dirs.m4;
74
75 Interesting/additional make targets:
76
77   * make check
78   * make lcov
79   * make debug
80   * make doc
81
82 Important directory path variables set by configure.ac:
83
84   * srcdir: The top directory for your package (standard autoconf variable).
85   * csource: Where you keep the source files.  These templates
86              assume that you keep the source in a subdirectory of $srcdir.
87   * headerdir: If your package distribute header files, set to the directory
88                where you keep them.
89   * utestdir: Directory where check test suites are kept.
90
91 Useful resources:
92  - good, extense autotools tutorial:
93    http://www-src.lip6.fr/homepages/Alexandre.Duret-Lutz/autotools.html
94  - doxygen: http://www.stack.nl/~dimitri/doxygen
95  - check: http://check.sourceforge.net
96  - lcov: http://ltp.sourceforge.net/coverage/lcov.php
97  - pkgconfig: http://pkgconfig.freedesktop.org/wiki/
98  - program library howto: http://tldp.org/HOWTO/Program-Library-HOWTO/
99  - why recursive make is a bad idea:
100    http://members.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html
101
102 == SVN integration ==
103
104 The file svn-ignore contains listing of files which should not be kept under
105 revision control. Use them like this:
106
107 {{{
108   frobnicator $ svn propset svn:ignore -F svn-ignore .
109 }}}
110
111
112 == Glossary ==
113
114   * Autoconf is a tool for configuring sources.  It's main use is to deal with
115     portability issues and ensuring the presence of needed dependencies.  It's
116     also useful for configuring C defines and other options which should be set
117     by the user before compiling.
118
119   * Automake is a tool for generating makefiles with lots of standard targets.
120     These targets are complicated to be built in a manner portable to different
121     make implementations.  Many of them, like "make tags", "make uninstall" or
122     "make distcheck", came to be expected by users.  Since they're complicated
123     and mechanic, they're good candidates for auto generation.  Automake assumes
124     that the package uses autoconf, and provides the infrastructure for libtool,
125     gettext and check.
126
127     We're requiring Automake to ensure portable, VPATH-enabled makefiles with
128     targets used in the test system, like "make distcheck".
129
130   * Libtool is a tool for building shared libraries and dlopen(3) modules.  Not
131     all systems have a shared library system, and those who do often use very
132     different schemes for building, installing, using and removing the
133     libraries.  Libtool can take care of these tasks for many different systems.
134
135 # vim: et:

(C) 2002-2009 Ademar de Souza Reis Jr.
http://www.ademar.org/
http://blog.ademar.org/