From 353c10a744dc7b049ebdd7ce0bd56a39287b2726 Mon Sep 17 00:00:00 2001 From: "Donald A. Peterson" Date: Thu, 16 Jan 2003 19:49:53 +0000 Subject: [PATCH] Moved INSTALL to HACKING since INSTALL can be overwritten by autotools (namely autoreconf -vfi) svn: r1257 --- gramps/HACKING | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++ gramps/README | 2 +- 2 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 gramps/HACKING diff --git a/gramps/HACKING b/gramps/HACKING new file mode 100644 index 000000000..5b2bdffdd --- /dev/null +++ b/gramps/HACKING @@ -0,0 +1,79 @@ +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. diff --git a/gramps/README b/gramps/README index 183651e75..e005a7326 100644 --- a/gramps/README +++ b/gramps/README @@ -1,5 +1,5 @@ Please read the COPYING file first. -If building from source, also read the INSTALL file (at least through the +If building from source, also read the HACKING file (at least through the "SUPER-SHORT VERSION") before going further. Requirements