			Living with CVS and Autoconf                 -*-text-*-
			----------------------------

These notes are intended for code developers.

You will need GNU gcc and GNU make to use the sources from the CVS
server.  If you do not have these tools available, build from the tar
file distribution instead, available from ftp.hpc.uh.edu.

All the derived files (the configure script, config.h.in, and all the
Makefile.in's) are checked into the repository.  Hence, you need to
know NOTHING about autoconf/automake to check out the sources and
build it.  NOR do you need to install these tools.  You can even hack
on the sources without these tools.

The ONLY time you need the tools is if you have to change a makefile or
the configure script.  Or if you want to build a tar file for
distribution.


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.

As above, you must have automake installed in order to modify makefiles.
PLEASE NOTE!  Automake will squirrel away some values in the automake
script itself when it is configured.  These values then find their way
into the Makefile.in files that automake generates.  Since we check in
these files, it's imperative that everyone running automake use the
_same_ values for these variables, or we'll be flip-flopping the
Makefile.in files back and forth in CVS.

In particular, after installing automake please edit the automake script
itself and look for this line:

  $TAR = "tar";

If the value of the $TAR variable is _anything_ other than "tar" (e.g.,
"gtar", "gnutar", etc.) please change it to plain "tar" immediately.

Makefile.am has a simple format, basically:

        bin_PROGRAMS = fvwm2

        fvmw2_SOURCES = blah.c blah.h foo.c 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(fvwm, 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 "fvwm-x.y.z.tar.gz".

Steps: 1. make sure the TAR variable in your automake script is set to 'tar'
          as described above.
       2. make sure you have XPM and a C++ compiler
       3. tag the CVS tree:
          cvs rtag -R version-x_y_z fvwm
       4. configure with the flag --enable-extras
       5. make
       6. make distcheck
       7. ensure that you see the message
          "fvwm-x.y.z.tar.gz ready for distribution"
          before uploading the tar file somewhere
       8. increase the version number in configure.in (see above)

Steps 1, 3 and 8 are not required if you are builing a distribution
just for fun.

One thing I've learned the hard way:

        You have to configure with ALL THE OPTIONAL SUBDIRECTORIES
        in order to build a distribution!

In short: this means you need Xpm, and a C++ compiler, AND you have to
configure using the flag --enable-extras.  The reason for this is that a
couple of subdirectories are only built when using Xpm (xpmroot, for
example) or C++ (extras/FvwmConfig).  It is fine for end users to not
build these.  However, the distribution-maker has to have all the
directories enabled, else the files don't make it into the distribution
tar file.

Similarly, you need to have actually built everything before packing the
distribution, hence step #3.  Among other things, this puts into the
Makefile.in's the proper dependency information.

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!


Modules and Extras
------------------

The "extra" modules are normally neither built nor installed.  They
are, however, autoconfigured like the regular modules.  If you just
want to build one or two extra modules, you can do:

    ./configure
    make; make install
    cd extras/foo
    make; make install

On the other hand, if you want to build & install everything, you can
arrange to treat the "extra" modules on the same footing as the
regular modules.  The configure flag "enable-extras" turns on this
behaviour.  If you do:

    ./configure --enable-extras make; make install

then all the "extra" modules are built and installed alongside the regular
ones.

There are short notes at the top of all the extras/*/Makefile.am files
about what may have differed vis-a-vis the old Imakefiles.  Some of
the modules, for example (currently fvwmpython and fvwmperl) have no
install rules at all.


