gramps/INSTALL

For rebuilding from source, here are some guidelines to follow.  For
developers who may be adding functionality to the program, be sure to read
the last section of this documen: "FINAL WORDS".

SUPER-SHORT VERSION:
You should be able to just run "./configure && make". But if you make any
significant changes or experience any problems, you may wish to run
"./autogen.sh && make" to regenerate everything.

This will call aclocal if necessary, then automake, which creates
Makefile.in from Makefile.am rules. Then it calls autoconf, which will
generate configure from configure.in and the Makefile.{am,in} sources.
Finally, autogen calls configure to generate the final files necessary for
building gramps.

SHORT VERSION:
Execute:
aclocal
automake --add-missing --gnu && autoconf && make

HTML documentation is built from SGML sources via jw.  It is known to work
with docbook-utils-0.6.9.  There is a problem with 0.6.10, which seems to
have some messed up dsl files. If you have difficulty building the HTML
documentation with your version of jw, then remove "doc" from the SUBDIRS
list in the top-level Makefile and send a report of where the failure was to
the gramps-devel list.  This distribution is tested with the style sheets
and PNG support from the gnome-doc-tools-2-1 package.

MORE INFO: Version and package info is now set in configure.in through a
call to the AM_INIT_AUTOMAKE macro.  The results are stored in variables
PACKAGE and VERSION, which then get substituted wherever necessary. 
(gramps.sh, gramps.spec, src/const.py, asst. Makefiles, etc.) We also
manually set the RELEASE variable for setting things like "pre" or minor
bugfix issues. * Note: Using @VERSION@ in the manuals has the advantage that
the current manual always states that it describes current version of
gramps.  The disadvantage is that this becomes misleading if the manual
isn't regularly updated.  Keep in mind this is GRAMPS version and not
*manual* version. Another problem is that the standard GNOME SGML
documentation make rules (sgmldocs.make) have their own rule, but automake
generates its own rule and this introduces a conflict.

"make (un)install" now runs scrollkeeper-update to ensure
documentation database is up to date. Scrollkeeper v. > 0.1.4 should in
principle work, v. > 0.2 should see no problems.  

VERBOSE, UGLY DETAILS FOR DEVELOPERS:
Using automake/autoconf adds many, MANY build targets to the makefiles.
Basically, we only care about the main and "install" targets.  However,
there are some others that bear further notice:

* make dist -- will create a lovely gramps-{VERSION}.tar.gz archive with
everything needed to distribute, including the HTML documentation just in
case Joe User doen't know about or have a compatable jw/db2html.  After
running "make dist" you can create the  rpms using 
"rpm -ta gramps-{VERSION}.tar.gz".  How nice is that?

* make clean -- only gets rid of byte-compiled stuff like .so files.

* make distclean -- improves on clean by eliminating configuration (*.in,
config.*, Makefiles, and converted documentation.) stuff. This is generally
what you (as a developer) will want for testing "fresh" compiles.

* make trans -- We add this one on our own for building the template.po file.

Another caveat of the automake mantra is that new/overriding make
targets/rules/defines should generally go in the Makefile.am files rather
than Makefile.in.  

* Note: Another beauty of the automake mechanism (and having automake macros
in the configure script) is that once the scripts have been made, a change
to any .am file will trigger "make" to regenerate the Makefile.in/configure
scripts as appropriate.  It is _very_ convenient.

FINAL WORDS: automake "thinks" of a distribution in terms of "SOURCES", such
as raw C code, "COMPILED OBJECTS" like executables and libraries, and
"DATA", such as images, scripts, and documentation.  Thus, for gramps we
concentrate on DATA-type objects.  We must tell automake what objects are
important.  We do this by adding to the EXTRA_DIST variable in the various
Makefile.am files before running automake.