			Notes for Developers                         -*-text-*-
			--------------------

Note: these notes apply only if you are working on some flavor of Unix.

You will need to install several GNU tools to be able to use the cvs
sources.  If you do not have these tools available, build from the tar
file distribution instead, available from peano.mathematik.uni-freiburg.de

To build from the CVS sources, you will need:
  * GNU gcc (version >= 2.95) 
  * GNU make
  * autoconf (version >= 2.13)
  * automake (version >= 1.4)


After the *initial* checkout of the sources, (see cvs.html) you will
need to execute the following commands from the top of the source
tree.

    automake --add-missing
    autoreconf
        ^^
Be careful!  The second command is autoREconf, not simply autoconf.

There will be some warnings, which are ignorable as long as you get a
working configure script: the configure script will fix all those
problems.

Now, configure and build as per INSTALL.  If configure fails, please 
look through `config.log' for clues.


Development Rules of the Road
-----------------------------

 1) _Every_ change must be properly ChangeLogged.  Since we create the
    ChangeLog automatically from the cvs commit logs, you can do this 
    by giving meaningful logs when cvs commits asks for them.

 2) If you make a user-visible change please add a blurb about it to the
    NEWS file.  A couple sentences is fine; don't repeat the
    documentation but give folks enough of an idea so they can decide if
    they want to learn more.  Bug fixes (unless they're _really_ user
    visible) shouldn't be noted in the NEWS file.

 3) If you add a new user-visible feature, don't forget to update the
    appropriate documentation at the same time!

 4) Bug fixes may be committed at any time (unless we're in code freeze
    for a release), usually without much review (unless you want someone
    else to look at it).  All our code freeze, etc. is merely
    procedural, not enforced, so it's important you read jade-devel
    and keep up-to-date with the current state of the tree.

 5) New features should be discussed on the list to ensure everyone
    thinks they're "appropriate". 

 6) If the new feature is large enough, unstable enough, or not
    targeted at the next release, it should go on a private branch.
    Otherwise, consensus will probably have it installed on the main
    branch.


        ** Of course, compile and test before committing! **


Dealing with CVS
----------------

I will fill in some details sometime.


Changing a Makefile
-------------------

First of all, NEVER edit anything named Makefile or Makefile.in.  These
are both derived from the corresponding Makefile.am.  The most common
reason for editing is to change the list of sources.

Steps: 1. edit foo/blah/Makefile.am
       2. re-run "make" from the top of the build directory

Step 2 will take care of rebuilding the Makefile.in and Makefile from your
changed Makefile.am.

Makefile.am has a simple format, basically:

        bin_PROGRAMS = openjade

        fvmw2_SOURCES = blah.cxx blah.h foo.cxx foo.h ...

Notice that you have to add all files, C++-code *and* headers, to the
_SOURCES line.  This is vital, because this is the list of files that are
packed into the distribution.  If you leave one out, nobody will be able
to build the distributed tar file!


Changing configure.in
---------------------

The most common reason to do this is to change the version string.  If
you're editing it for any other reason, I will assume you know what you're
doing.

Steps: 1. edit configure.in, and find the line containing
          AM_INIT_AUTOMAKE(OpenJade, x.y.z) at the top of the file
       2. change x.y.z to the new version string
       3. re-run "make" from the top of the build directory

Step 3 will take care of rebuilding the configure script, and usually all
the other Makefiles.


Building a distribution
-----------------------

By this, I mean the file "OpenJade-x.y.z.tar.gz".

Steps: 1. ./configure
       2. make clean
       3. double check that you get no warnings during the build (the
          options for compilers other than gcc may be different):
          make CFLAGS="-g -O2 -Wall -Werror"
       4. make distcheck
       5. ensure that you see the message
          "OpenJade-x.y.z.tar.gz ready for distribution"

Note that you need to have actually build everything before packing
the distribution, thus if we ever have files which are compiled only
conditionally, you'll have to add the necessary options 1. to make 
sure everything is built.  Among other things, this generates
the proper dependency information for insertion into Makefile.in's
generated in step 4.

Step 4 will create the tar file, then unpack it and attempt a build &
install (to a scratch directory, not /usr/local).  This makes sure
that you really DID include all the files necessary to build the
package into the tar file. It may be hard to appreciate how useful
this is, until it has reminded you that you forgot file "foo.h" in
some _SOURCES line.  But trust me, it will save your bacon in this way
some day!


If this is to be an "official", labeled release, then do also the
following:

       6. tag the CVS tree:
          cvs tag openjade_x_y_z
       7. increase the version number in configure.in (see above)
          and `cvs commit' this change
       8. put the file up for ftp somewhere 
       9. add a link to the download.html page, which is in the
          cvs module named www.  Committing the new version to the
          repository will bring it online shortly after.

Be sure to do steps 6 and 7 in that order, so you get the label on the
right version of configure.in.
