← Back to branch summary

~siretart/gnucash/ubuntu-fullsource

« back to all changes in this revision

Viewing changes to doc/README.build-system

  • Committer: Reinhard Tartler
  • Date: 2008-08-03 07:25:46 UTC
  • Revision ID: siretart@tauware.de-20080803072546-y6p8xda8zpfi62ys
import gnucash_2.2.4.orig.tar.gz

The original tarball had the md5sum: 27e660297dc5b8ce574515779d05a5a5

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/README.build-system
 
1
-*-text-*-
 
2
 
 
3
===========================================================================
 
4
Automake
 
5
 
 
6
GnuCash uses automake to handle the build process.  Make sure you
 
7
understand what automake provides/requires before you add anything
 
8
particularly fancy to the Makefile.am files.
 
9
 
 
10
Most of the time, a "make" or "make install" will automatically DTRT
 
11
and regenerate Makefiles or Makefile.ins, re-run configure, regenerate
 
12
configure from configure.in, etc. whenever needed.  However, it is
 
13
possible, if you make a mistake when working on the Makefile.am's to
 
14
leave yourself in a situation where automake won't work because a
 
15
Makefile is broken.  To fix this, just run:
 
16
 
 
17
 ./autogen.sh
 
18
 ./configure <your usual options>
 
19
 
 
20
That should sledgehammer the problem bit back into place.
 
21
 
 
22
===========================================================================
 
23
Adding files to AC_OUTPUT in configure.in.
 
24
 
 
25
Please do not add any non-makefiles to AC_OUTPUT unless you're
 
26
*absolutely* sure that it's safe and necessary to do so.  If you're
 
27
not sure, then please use the "generation with sed by hand approach"
 
28
that we use for other non-makefiles like src/scm/bootstrap.scm.  See
 
29
src/scm/bootstrap.scm.in and src/scm/Makefile.in for details.
 
30
 
 
31
The reasoning behind this is that there are often variables that
 
32
autoconf uses and replaces via the @@ mechanism that are recursively
 
33
defined in terms of other variables.  For example, @datadir@ might
 
34
expand into $prefix/share, which itself contains an unexpanded
 
35
variable.  Unless the @datadir@ replacement is performed on a file
 
36
that will eventually be processed by make, there's no guarantee that
 
37
the variable will *ever* be fully expanded and then your code will
 
38
break.
 
39
 
 
40
To get around this, we handle all non-makefiles (with a few notable
 
41
exceptions) manually with sed.  For example, we have
 
42
src/scm/bootstrap.scm.in which is processed in src/scm/Makefile.in
 
43
according to the following rule:
 
44
 
 
45
  ## We borrow guile's convention and use @-...-@ as the substitution
 
46
  ## brackets here, instead of the usual @...@.  This prevents autoconf
 
47
  ## from substituting the values directly into the left-hand sides of
 
48
  ## the sed substitutions.  *sigh*
 
49
  bootstrap.scm: bootstrap.scm.in
 
50
        rm -f $@.tmp
 
51
        sed < $@.in > $@.tmp \
 
52
            -e 's:@-VERSION-@:${VERSION}:g' \
 
53
            -e 's:@-GNC_CONFIGDIR-@:${GNC_SHAREDIR}:g' \
 
54
            -e 's:@-GNC_SHAREDIR-@:${GNC_CONFIGDIR}:g'
 
55
        chmod +x $@.tmp
 
56
        mv $@.tmp $@
 
57
 
 
58
This approach guarantees that the variables referred to will be
 
59
properly expanded at the right times.
 
60
 
 
61
Note that on OSX, you MUST have the GNU version of sed installed
 
62
via fink - the BSD version installed by default will not work with
 
63
some of the substitution operators used in the gnucash build.
 
64
 
 
65
The only non-Makefiles files that must be handled directly by
 
66
AC_OUTPUT are files that refer to variables that, when expanded, may
 
67
have makefile-hostile characters like '#' in them like
 
68
INCLUDE_LOCALE_H.  These may need to be replaced directly in the
 
69
relevant file via AC_OUTPUT since going through a makefile would break
 
70
the makefile when it interprets the '#' as the beginning of a comment.
 
71
You'd have something like this:
 
72
 
 
73
  FOO = "#include <locale.h>"
 
74
 
 
75
If you end up in a situation where you need to refer to both these
 
76
makefile-hostile variables and non-makefile hostile variables in the
 
77
same file, please restructure things (breaking the file up if
 
78
necessary) so that only the makefile hostile variables are in the
 
79
files being handled by AC_OUTPUT directly.
 
80
 
 
81
===========================================================================
 
82
 
 
83
It is not safe to use $prefix in configure.in for anything other than
 
84
an unexpanded reference.  If the user doesn't specify a --prefix, then
 
85
it'll be set to NONE until the end of the configure process.
 
86
 
 
87
===========================================================================