%$Id: install.tex,v 1.2 96/03/30 18:02:50 al Exp $
% man install .
%------------------------------------------------------------------------
\chapter{Installation}

Most of the development of ACS was done on a NeXT with Gnu C++.
I have also compiled it successfully on several other
systems, listed at the end of this file.  Other users have ported
ACS to several other systems.  Some of the files are included in
the distribution.  They may not have been tested in the latest
release.  It should compile with any "standard" C++ compiler.  It
should produce no warnings when compiled with the switches in the
supplied makefiles and g++, except those due to the system supplied
header files being defective.  It requires templates, but not
exceptions.

All source files are in the src directory.  I use subdirectories
for the .o files each supported machine.  This makes it possible
to install it on several different machines all sharing the same
file system.

To avoid maintaining multiple versions of Makefiles, I have broken
them up to parts that must be concatenated: Make1.*, Make2.*,
Make3.*.  In general, to make a Makefile for your system, cat one
of each.  See the Makefile for details.  I have automated this for
some systems.  Just "make your-machine", if it is one that is
supported.  This will make the appropriate Makefile, cd to where
the .o's go and run make from there.  For porting information for
specific machines, read its "Make2.*" file.

To help the porting to MSDOS and VMS, you should first "make
makefiles" on a unix system, which will make the subdirectories
and the Makefiles.  Then transfer the files.  Someday I may come
up with a better way.  A pre-compiled executable may be available at
the primary ftp site (www.rochester.r1.ieee.org).

We assume that make will follow "VPATH" to find the sources.  This
system makes it possible to manage several platforms on a single
file system which may be NFS mounted to all the supported machines.
If your make does not support VPATH, there are three options.  The
preferred method on unix based systems is to cd to where the
.o's go and type "ln -s ../*.cc ../*.h .".  This will set up links
so the Makefiles will work as intended.  In some cases we have set
up the Makefile to do this automatically.  The second method, which
may be needed on systems like MSDOS that don't have symbolic links
is to copy the .c and .h files to satisfy make.  The third option,
where you have only one computer, is to move the machine
specific Makefile to the src directory and run make from there.

If you have g++ on a unix type system that is not directly supported,
try to compile it by just typing "make".  In most cases this will
do it, but you may get a few warnings.  If it doesn't work, look
in the file md\_unix.h for hints.  Just plain "make" will build a
development version with additional debugging enabled.  This results
in a significant speed penalty.

The make the installation version, select the machine you have from
the make file and make that.  The machine specific versions will
build in their own directory, have debugging code disabled, and
options are set for best speed.  The general purpose "make g++"
builds a version that is optimized as much as it can be in the
general case.

If you have a cfront-type compiler, called "CC", and your system
is not directly supported, try it first by typing "make CC".  Again,
you may get a few warnings but it should work.  Look in the file
md\_unix.h for hints, if it doesn't work, or if the warnings look
serious.

Since C++ is an evolving language, there are some known portability
problems:

\begin{description}

\item[bool] The C++ language includes a type "bool", which is not
implemented in older compilers.  By defining BAD\_BOOL creates the
"bool" type, which must be done in a roundabout way because the
boolean operators may return int, which in some cases cannot be
assigned to bool.

\item[const] C++ uses an abstract notion of constant, meaning that
the external appearance of an object declared const must not change,
but there can be internal changes like reference counters.  The
keyword "mutable" means that a member variable can change even if
it is declared const.  As a work around, ACS uses CONST, which is
either defined to nothing or const.  Defining NO\_ABSTRACT\_CONST
defines out the CONST, making it work on older compilers.  A related
problem is that the header files supplied with some compilers do
not implement const correctly.

\item[complex] The evolving standard shows complex to be a template
class, so instead of having a type "complex", there is "complex<double>",
"complex<float>", and so on.  Older compilers have only "complex".
The compiler should automatically define \_\_STD\_COMPLEX to indicate
that it has the template, so selecting the proper mode should be
automatic.

\item[templates] There are three common ways to instantiate templates
in common use.  Unfortunately, they are incompatible and none of
the methods are available in all compilers.  ACS requires templates,
so will not work with many older compilers.

\begin{description}

\item[Link time] The entire program is compiled and linked without
templates, resulting in some unresolved externals.  The files
defining the templates are compiled again to fill the need.  This
is the preferred way, if you have it.  It is supported by CFRONT
derivatives such as the Sun CC compiler.  Define LINK\_TEMPLATES to
force it.  This is the default, unless you are using the GNU
compiler.

\item[Compile time] All parts of templates must be compiled as if
in-line, requiring all code to be in the .h file, or included by
the .h file.  Header files include .cc files.  The duplicates are
supposed to be thrown away by the linker.  This is the only style
supported by Borland 3.1 or 4.0.  It is supported inefficiently by
the GNU compiler starting at version 2.6.  Define COMPILE\_TEMPLATES
(or ComTemP) to force it.

\item[manual] Templates must be instantiated manually.  This is
the preferred way for the GNU compiler.  It is not supported by
CFRONT or Borland.  Define MANUAL\_TEMPLATES to force it.

\end{description}

The second inconsistency with templates, is what type conversions
are allowed.  Some compilers require an exact match.  Some will
make trivial conversions, such as int to const int.  If yours has
a problem, define PEDANTIC\_TEMPLATES (or PedTemP).  Defining
PEDANTIC\_TEMPLATES when it is not needed may produce duplicates,
so it MUST be one way or the other,

\item[missing files or functions] Another cause of a port to fail
is missing header files or missing function prototypes.  Sometimes
missing functions can be a problem.  The solution to these problems
is to supply what is missing.  The "md\_*" files exist for this
purpose.  You should make a copy of the appropriate Make2.\_\_\_
file, patch it to define something to identify the system, then
patch the md\_(whatever).h and md\_(whatever).cc as appropriate.
You should not use any \#ifdef's except in these file.

\item[bad header files] In some cases, the header files that come
with the system or compiler are defective and generate warnings
without anything wrong with the program being compiled.  This slips
by in the distribution because most developers compile with warnings
off.  Usually, these can be ignored.

\end{description}

If a port doesn't work, probably there is a missing header file,
prototype, or function.  You need to supply what is missing.
Suppose you have a "foobiac" computer.  You should make a new file
"Make2.foobiac" that defines the compiler switches.  In CFLAGS,
you should define "FOOBIAC" to select your patches.  You should
change "Makefile" to make the directory "FOOBIAC" for the .o files
and the special "Makefile".  You should also add a few lines so
when you type "make foobiac" in the "src" directory it builds the
special "Makefile" then does (cd FOOBIAC; make -k) to make the
program.  Then you should edit the md\_unix.h file to make the
appropriate includes and prototypes for your system.  Look at the
files to see how we handle the other systems.  If you do a port
please share your patches so I can add it to the distribution.

If you have a non-unix system you may also need to change "md.cc"
and "md.h" and make some new files "md\_foobiac.cc" and "md\_foobiac.h".
Look at the files for other systems for a guide to what should be
there.  How you handle the "makefile" will depend on the tools
you have.

Some files starting with "plot" contain plotting drivers are may
also need customization if you want a graphic display.  They are
all essentially non-working, but plotibm does work for most PC
video cards.  If all you want are ASCII plots the files should be
suitable as they are.

On a PC, you should have some version of "make".  For Borland C,
concatenate the files "Make1", "Make2.bc", and Make.depend to
"makefile".  Then change all ".o" extensions to ".obj".  The program
"sed" on unix systems will do this.  Type "make" from the directory
containing the sources.  Since I use SoftPC on a unix system for
this, I make links (in unix) from the MSDOS directory to the src
directory (..) to work around the fact that my PC make does not
support VPATH.  You may need to get a few unix style utility programs
if you don't have them already.  Probably the best approach for a
PC is to use the pre-compiled executable we supply.

You should place the file "acs.hlp" in any directory in PATH.
ACS uses the environment variable PATH to find it.  Usually the
best place is the same directory as the executable.

There should be NO non-portable code anywhere but the md\_* files
and plot files.  The use of \#ifdef to patch portability problems
should be restricted to the md\_* and plot files.

ACS (this release, 0.21) is known to work on ...
\begin{itemize}
\item NeXT (Motorola), NextStep 3.2, g++ 2.7.1
\item Sun Sparc-2, Sun-OS 4.1.3, g++ 2.6.3 or CC 3.?
\item SGI Indy, Irix 5.2, g++ 2.6.3 or NCC (CC)
\item 286 PC, MSDOS 5.00, Borland C++ 3.1
\item Linux, (pentium) g++ 2.7.2
\item Dec Alpha, Digital UNIX V3.2C, g++ 2.7.2
\item HP 700, g++ 2.7.0
\end{itemize}