%$Id: install.tex,v 24.14 2004/01/09 05:27:01 al Exp $
% man install .
% Copyright (C) 2001 Albert Davis
% Author: Albert Davis <aldavis@ieee.org>
%
% This file is part of "Gnucap", the Gnu Circuit Analysis Package
%
% This program is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2, or (at your option)
% any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
% 02111-1307, USA.
%------------------------------------------------------------------------
\chapter{Installation}

%HEVEA\cutdef[0]{section}

\section{The easy way}

For this version, you can use either the GNU style "configure;make"
style build process, or the old ACS style.  If it works for you, use
the GNU style.

For the GNU style build, just type "./configure" then "make" from the
project's root directory.  This will configure both the model compiler
and the simulator, and then build the model compiler first, then use
it to build the simulator.  That should be all that is needed.  You do
not to read any further.

\section{If that doesn't work}

This version requires a two-step build.  First you build the model
compiler, then you build the simulator.  You can usually get away with
only building the simulator.

So ..
cd to modelgen, type make (as below)
then go back down and cd to src, type make (as below)

If it fails, go into its build directory (the one containing the .o
files) and manually create a symbolic link to the model compiler.


"Type make" really means ......

Usually, you can just type "make".  This will make a "release"
version, with optimization on and extra debug code out.  It will build
in the O subdirectory.  This assumes you have g++ in a reasonable
configuration.

To make a "debug" version (slow, with additional error checking), type
"make debug".  If you have a recent g++ compiler, this should build it
in the O-DEBUG subdirectory.

If your compiler is not g=++, but called by "CC", try "make CC".  This
is believed to work with some compilers.  Some of them do not
implement the full language, so they cannot be used.  Try it.  There
is a special one "sun4-CC" for a Sun running Solaris with the most
recent version of Sun's compiler.  It will not work with older
versions.

To make a "release" version for a particular system, type make
followed by your system type, such as "make linux".  This will build
it in a subdirectory (in this case LINUX).  With this method, you can
build for multiple systems in the same directory.

Look at "Makefile" for a list of supported systems, and clues of how
to do it on others.  Most of them have not been tried in years.

If it doesn't work, edit only a "Make2.*" file, and possibly {\tt md.h} or
{\tt md.cc}.  All nonportabilities are confined to these files.

It does require a recent and proper C++ compiler with a proper
library, including STL.  Gnu compilers older than 2.8 will probably
not work.  Anything else that old will also probably not work.  Any
high quality C++ compiler available today should work.

To install ....

Just move or copy the executable to where you want it.

\section{Details, custom compilation}

Read this section if you have problems or want to know more.  It is
not necessary most of the time.

Most of the development of Gnucap was done on a PC running Linux.  I have
also compiled it successfully on several other systems, listed at the
end of this file.  Other users have ported it 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 and modelgen directories.  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.  In some
cases, the Makefile will compile both a ``release'' and ``debug''
version.  In these cases, type ``make your-machine-release'' or ``make
your-machine-debug'' depending on which you want.  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 {\tt Make2.*}
file.

I 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 {\tt ln -s ../*.cc ../*.h .}.  (The command ends with a dot.)
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 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 {\tt make}.  In most cases this will
do it, but you may get a few warnings.  If it doesn't work, look in
the file {\tt md.h} for hints.  Just plain {\tt make} will build a
guess at a release version, assuming a Linux-like system with GNU
tools.

If you want a development version with additional debugging enabled,
type {\tt make debug}.  This results in a significant speed penalty.

Then 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 {\tt 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 {\tt CC}, and your system
is not directly supported, try it first by typing {\tt make CC}.  Again,
you may get a few warnings but it should work.  Look in the file
{\tt md.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.  All of them are due to compilers that do not implement the
standard correctly.  Since the problems will go away in time, I have
chosen either not to burden the code with them, except where a few
mainstream systems fail.  All dependencies should be confined to the
two files {\tt md.h} and {\tt md.cc}, if possible.

Here are some possible problems that are no longer supported:

\begin{description}

\item[bool] The C++ language includes a type {\tt bool}, which is not
implemented in older compilers.  Older compilers just use {\tt int},
and fake it with a {\tt typedef} or {\tt \#define}, neither of which
work correctly.

\end{description}

Here are some problems that you will need to deal with creatively:

\begin{description}

\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 {\tt 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
{\tt md.h} and {\tt md.cc} as appropriate.  You should not use any
{\tt \#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}

Here are some problems that have work-arounds:

\begin{description}

\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 {\tt mutable} means that a member variable can change even if it
is declared const.  As a work around, we use CONST, which is either
defined to nothing or const.  For any good compiler, the line {\tt
\#define CONST const} will give correct behavior.  For a bad compiler,
the line {\tt \#define CONST} will turn it off.  There is no harm in
treating all compilers as ``bad'' except for the loss of compile
diagnostics.

\item[complex] The evolving standard shows complex to be a template
class, so instead of having a type {\tt complex}, there is {\tt
complex<double>}, {\tt complex<float>}, and so on.  Older compilers
have only {\tt complex}.  The line {\tt typedef std::complex<double>
COMPLEX;} in {\tt md.h} works for a correct compiler.  You may need to
change it of an older one.

\item[template instantiation] 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.
Gnucap 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 {\tt LINK\_TEMPLATES} to
force it. 

\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 must 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.  Since no mainstream compiler requires this, and it is inefficient, it is no longer supported.

\item[manual] Templates must be instantiated manually.  This is
the preferred way for the GNU and Microsoft compilers.  It is a
nuisance, but it generates the best code.  Define {\tt MANUAL\_TEMPLATES} to
force it.

\end{description}

\item[template resolution] The second inconsistency with templates
is how the type matching is resolved.  Some compilers require an exact
match.  Some will make trivial conversions, such as int to const int.
The language definition allows for templates to be ``specialized'' by
providing a specific implementation for a specific type, resorting to
the template for others.  Some compilers (Sun) do not support this.
Since this is common, there are work arounds in the code for it in the
simulator but not the model compiler.  If you want to compile the
model compiler, you will need to get a better C++ compiler.

\end{description}

The files starting with {\tt plot} contain plotting drivers are
generally bogus.

There should be NO non-portable code anywhere but the {\tt md\_*}
files.  If a fix is absolutely necessary elsewhere, {\tt \#define} some
symbol in {\tt md.h} and refer to it elsewhere.  Then consider it to
be temporary.

%HEVEA\cutend
%----------------------------------------------------------------------------
%----------------------------------------------------------------------------
