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 GUI 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 Wine 1.0 or later. See below.

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 uses these LaTeX packages:

   comment courier graphicx helvet ifpdf ifthen
   palatino parskip sectsty ragged2e url

These all come with teTeX, so no unusual steps should be necessary.


1a. Notes on Wine (Windows build only)

The Windows build requires version 3.5 of the IBM Visual Age for C++
compiler, and Wine to run it.

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, long before Wine 1.0, 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.


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.