Things you should do when developing:

   - Configure with --enable-maintainer-mode. (See install.txt.)

   - Set up both a native and a Windows build tree.

   - Create a directory "bin" under the top level of the source tree,
     and copy a known working version of agcl there. (See below.)

Useful make targets and options:

	all		Compile everything.
	rules		Update the make rules.
	agfiles		Generate AG output from syntax files.
	agclean		Remove AG output files.
	clean		Remove object files and executables.
	distclean	Remove all compiler-generated material.
	install		Install everything.

	SAFE=1		Compile with "safe" AnaGram (see below)
	UNSAFE=1	Compile with "unsafe" AnaGram (see below)
	AGFORCE=1	Force the agfiles target to rebuild.

If you add a file to the build, rerun "make rules" in the affected
build directories. If you add a whole directory, you need to rerun the
configure script to generate the new makefile. You can do this in an
existing build directory by running "./config.status", which remembers
the options you gave to configure.

Dependency tracking for header files is automatic.

If you want to remove a header file from the build, the easiest way is
to make sure it isn't used (e.g., by putting an #error in it and
building) before actually deleting it. Otherwise you may need to blow
away the depend files (depend.mk and *.u or *.d) to keep make from
complaining that it doesn't exist.

Note that the 'agfiles' target will only rebuild the AnaGram output if
it appears to be out of date, unless you specify AGFORCE=1. If you
aren't certain whether it really rebuilt, check the date stamp in the
output header file.


Bootstrapping notes:

AnaGram is partly written using itself. This creates the potential for
various kinds of problems. 

The distribution archives ship with up-to-date versions of the
generated code; if you aren't developing, you should be able to just
use those and everything should be ok.

If you *are* developing, the following precautions are taken:

   - By default, the build runs $(TOP)/bin/agcl, which you should
     update by hand as you see fit. Note: update it from the copy
     the build produces in anagram/run, not the one in anagram/agcl.
     The latter doesn't have the checksums in it and won't run.

   - If you set SAFE (e.g., make SAFE=1) the build system will run
     $(TOP)/bin/safe-agcl instead, the idea being that you can be
     be very conservative about updating this and use it as a 
     fallback if you manage to delete or break $(TOP)/bin/agcl.

   - If you set UNSAFE (e.g., make UNSAFE=1) the build system will
     run the most recent native agcl right out of the build tree.
     Use with due caution.

   - The AG-generated code used in the build is kept in source
     control, so if all else fails you can revert to a clean version
     that way.  Be sure to revert matching .cpp and .h files, or the
     build will fail.

Note that $(TOP)/bin is neither created nor populated by default;
if developing you should set it up yourself with a suitable agcl
executable.

Also note that if you are developing you should always configure with
--enable-maintainer-mode, and this *requires* $(TOP)/bin/agcl to
exist. This also creates a minor bootstrap problem: if you don't
already have an agcl to place in $(TOP)/bin, you have to compile
one. The easiest way is as follows:

   path-to-source/configure native
   make rules
   make
   mkdir path-to-source/bin
   cp anagram/run/agcl path-to-source/bin/agcl
   ./config.status --enable-maintainer-mode
   make rules
   make

And finally, note that the 'agfiles' target depends make-style, that
is, by timestamp, on the agcl executable selected. If reverting to an
older version, including via SAFE=1, it is a good idea to also
AGFORCE=1 on the make command line, or run the 'agclean' target
first. (There is also no such dependency when maintainer mode is not
enabled, because that would preclude building from scratch.)

The premise is that changes to the sources are much more common than
material changes to the output that require rebuilding the parsers
used in AnaGram itself.