--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/install/install.txt	Sat Dec 22 17:52:45 2007 -0500
@@ -0,0 +1,262 @@
+Installing AnaGram 2.40 from source
+-----------------------------------
+
+1. Requirements
+
+You must compile on Unix. (Windows using Cygwin is not presently
+supported, but suitable patches will be accepted. Windows without
+Cygwin or equivalent is too crippled to be useful.) Any reasonably
+modern Unix should work, even Solaris, although this has probably not
+been tested. (Linux, NetBSD, and perhaps MacOS X are tested.)
+
+The makefiles have been arranged such that even the antiquated
+dialects of System V make shipped by Sun and other old-line Unix
+vendors should work; if you find that you need GNU make please file a
+bug report.
+
+There are essentially two supported builds: the Unix command-line-only
+build and the Windows GUI build.
+
+The Unix build currently requires gcc 3.x or 4.x. Reasonable patches
+for other Unix compilers (e.g. the Intel compiler on Linux, or Sun's
+payware compiler) will probably be accepted. If you have gcc set up as
+a cross-compiler, you can cross-compile AnaGram. See below.
+
+The Windows build requires IBM Visual Age for C++ version 3.5, because
+the GUI uses that compiler's semi-proprietary GUI class library. You
+also need a recent version of Wine.
+
+Wine must be configured such that I:\\IBMCPPW\\BIN\\ICC.EXE is the
+main compiler executable. (To arrange this, create a suitable symbolic
+link named "i:" in ~/.wine/dosdevices.) Note that while it would not
+be difficult to make this more flexible, migrating away from this
+compiler is a better use of time.
+
+The source tree must also be accessible to Wine somehow; it doesn't
+matter what the specific drive or path mapping is.
+
+At one time it was necessary to use patchlevel 354 (neither newer nor
+older) of ILINK.EXE, which you can get from IBM support. This version
+is 188928 bytes long and has md5sum f48f0aace7c6f247bae015b43f16969a.
+Wine has improved a good deal since then, however, and this may no
+longer be necessary.
+
+Because of problems with Wine on NetBSD, you can only compile the
+Windows build on NetBSD with some combinations of versions of NetBSD
+and of Wine. Linux works, however.
+
+Note that the source, though not the build system, has some support
+for a number of other Windows compilers (including Borland, Watcom,
+and Microsoft) and you may be able to get these to work to build the
+command-line-only version. Building a Windows command-line only
+version using a Cygwin gcc may also be possible. These builds,
+however, are unsupported and you will have to fiddle with the
+configure script and/or the makefiles. (Appropriate patches will
+probably be accepted though.)
+
+Building the manual requires LaTeX. It doesn't require anything that
+doesn't come with teTeX, so no unusual steps should be necessary.
+
+
+2. Configuring
+
+AnaGram comes with a "configure" script that sets up the build
+environment. This is *not* a GNU autoconf script, although it looks
+superficially like one.
+
+It accepts the following options:
+
+   --destdir=DIR
+
+	Set the "destination directory" to DIR. This names a chroot
+	area or other subtree within which the installation prefix
+	will be found. The idea is that the destination directory will
+	end up being the root directory at the time AnaGram is run.
+	This is potentially useful for cross-compiling and for
+	building binary packages.
+
+	Note: this applies only to Unix builds.
+
+   --prefix=DIR
+
+	Set the installation prefix to DIR. Defaults to /usr/local.
+	The AnaGram executables, documentation, and examples will be
+	installed in suitable places under this directory by default.
+
+	AnaGram does not (at present) compile in the installation
+	prefix.
+
+	Note: this applies only to Unix builds.
+
+   --bindir=DIR
+   --libdir=DIR
+   --mandir=DIR
+   --docdir=DIR
+   --examplesdir=DIR
+
+	Set the exact places where things will be installed. If these
+	are not provided, suitable defaults under the installation
+	prefix are chosen. Note that depending on the build and other
+	circumstances some of these directories may not actually be
+	used.
+
+	Note: these options apply only to Unix builds.
+
+   --with-compiler=COMPILER
+
+	Specify which compiler to use. This controls the selection of
+	compiler command-line options, C++ dialect, and other such
+	issues. It also controls how the compiler is invoked.
+
+	COMPILER may be "gcc" for gcc or "vacpp" for the IBM Visual
+	Age compiler.
+
+	The default compiler is gcc for Unix builds and vacpp for
+	Windows builds.
+
+   --with-ptests=DIR
+
+	If you have a copy of the private test suite, use this
+	argument to tell the build system where to find it. The
+	private test suite contains tests that for one reason or
+	another cannot be released to the public.
+
+   --enable-gui=GUI
+   --disable-gui
+
+	Select the graphical user interface to use. The only GUI
+	currently supported by AnaGram is "vaclgui", the GUI using the
+	Visual Age class library. Enabling "dummygui" is equivalent to
+	selecting --disable-gui.
+
+	"vaclgui" is the default for Windows builds. "dummygui" is the
+	default for Unix builds.
+
+   --enable-maintainer-mode
+
+	Turn this on if you are intending to work on the AnaGram
+	source code. It enables compiler flags that developers should
+	use. It also enables certain crosschecks, and compilation and
+	testing of the examples. Note that to use this you must
+	populate your tree with a known clean copy of the agcl
+	executable. See doc/devel/make.txt for more information.
+
+   --enable-debug
+
+	Compile with debug information. The default is to compile with
+	optimization.
+
+   --enable-prof
+
+	Compile with profiling support. This will not work at present
+	with the IBM compiler because I don't know what compiler
+	switches to use. (Patches/information welcome.)
+
+In addition to options, the configure script accepts an argument
+naming the platform to compile for. This can be one of the following:
+
+   native
+
+	Build for Unix, and don't cross-compile.
+
+   windows
+
+	Cross-compile for Windows.
+
+   mips-linux
+
+	Cross-compile for some other Unix type. The string provided
+	should be the GNU machine type name for a cross-compiling gcc
+	you have previously installed. See below.
+
+The default is "native".
+
+It is recommended that you not compile directly in the source tree.
+Make a directory to build in, and run the "configure" script from that
+directory, giving the path to the source, such as like this:
+
+	mkdir build-windows
+	cd build-windows
+	../configure windows
+
+The build directory can be put anywhere, and you can use multiple
+build directories with the same source directory. If you intend to
+work on the AnaGram source code, you should generally set up one build
+directory each for Unix and Windows, and of course use the
+--enable-maintainer-mode option.
+
+
+3. Compiling
+
+In the same directory you ran the configure script, do this:
+
+	make rules
+	make
+
+If you do not do "make rules" first the build will bomb out very
+quickly.
+
+(Why is "make rules" not automatically invoked by the configure
+script? Because it creates a lot of scroll, particularly with GNU
+make, and would obscure possibly important messages issued by the
+configure script.)
+
+Do not do parallel builds (make -j3 or similar) -- it will not work.
+Note that GNU make is incapable of handling this correctly in any
+event, so support is not likely to be forthcoming in the future.
+Flames to /dev/null.
+
+
+4. Testing
+
+To run the test suite, do this:
+
+	make test
+
+(Note that "make tests" will do nothing, because there's a directory
+named "tests".)
+
+If everything is working correctly, there should be no diffs printed.
+
+As of this writing, if you run the test suite for the Windows build,
+you will get various test diffs because of messages issued by Wine, as
+well as some changes in diagnostic messages caused by the different
+end-of-line markers. These diffs appear to be benign, although it
+would be better if they didn't happen at all.
+
+Also note that you need to have an X display to run the test suite
+under Wine, even though the test suite only tests the command-line
+AnaGram executable. It is not immediately clear why this is.
+
+
+5. Installing
+
+To install, do this:
+
+	make install
+
+For the Unix build this will install in the places selected at
+configure time.
+
+For the Windows build it will create a directory called "install"
+containing a binary release comparable to the historic binary releases
+of AnaGram. You can copy this to a suitable place on your Windows
+machine however you see fit.
+
+
+6. Running AnaGram
+
+For the command-line version, run "agcl". For the GUI version, run
+"ag". For further information, please consult the main AnaGram manual,
+or the additional HTML documentation found in doc/misc; the latter
+includes a Getting Started guide.
+
+Note that the Visual Age for Windows GUI version does not work all
+that well in Wine; it seems to have various problems updating the
+screen and seems unable to select fonts properly. (This makes the
+Grammar Trace and related functionality very difficult to use.) It
+does not run at all in Wine on NetBSD, either. Fixes will probably be
+accepted - but keep in mind that the Visual Age class library is
+orphaned and time would be better spent migrating to a new GUI using
+some other GUI toolkit.
+