--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/devel/make.txt	Sat Dec 22 17:52:45 2007 -0500
@@ -0,0 +1,83 @@
+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)
+
+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.
+
+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.
+
+   - 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 CVS, 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
+in order to test-compile the examples. 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
+