%$Id: architecture.tex,v 25.95 2006/08/26 01:26:53 al Exp $ -*- LaTeX -*-
% man Tech architecture .
% 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., 51 Franklin Street, Fifth Floor, Boston, MA
% 02110-1301, USA.
%------------------------------------------------------------------------
\subsection{File organization}

Gnucap source files are organized into groups by the name prefix as follows:

\begin{description}
\item[ap] ``Argparse''.  Generic parser and lexical analysis library.
\item[bm] Behavioral modeling.
\item[c] Commands.
\item[d] Devices and models.
\item[e] Device and model base classes.  (``e'' comes from
  ``electrical'' and is retained because of inertia.)
\item[io] Input and output library, raw, generic.
\item[l] Library.  General purpose functions and classes that do not
  fit elsewhere.
\item[m] Math library.
\item[plot] Obsolete plotting that should be replaced.
\item[s] Simulation engine.
\item[u] Utility functions and classes.  Gnucap Specific.
\end{description}

The files {\tt ap\_\*}, {\tt io\_\*}, {\tt l\_\*}, {\tt m\_\*} are not Gnucap
specific.  Although they were created for Gnucap, they are public domain
and may be used by anyone for any purpose.

The remaining files {\tt bm\_\*}, {\tt c\_\*}, {\tt d\_\*}, {\tt e\_\*},
{\tt s\_\*}, {\tt u\_\*} are Gnucap specific, and reuse is subject to the
Gnu Public License.

Some of the {\tt d\_\*} files are automatically generated during
compilation.  Do not change them, because your changes may be lost in
a recompile.  For licensing and distribution legal purposes, these
files are considered to be ``object'' code, even though they are
readable C++.

The files {\tt d\_\*.model}, where present, contain the actual model
descriptions as input for {\tt modelgen}, the model compiler.
These files are the source that is used to generate the corresponding
{\tt .cc} and {\tt .h} files.  All changes should be done to the {\tt
.model} file.  For GPL purposes, these files are considered to be
``source''.
%------------------------------------------------------------------------
\subsection{Building, Makefiles}

Gnucap uses a 4 part Makefile, designed for simultaneous builds on
several systems.  A true Makefile is built by selecting and catenating
the four pieces.  A master Makefile switches to a subdirectory and
builds a specialized Makefile there.

\begin{description}
\item[Make1] The file list.  Specific to this program.
\item[Make2] Compiler and system dependencies.  Specific to the
  compiler.  In some cases, hardware dependencies are here.  There are
  several provided.  Choose the one that matches your system.
\item[Make3] Basic ``make'' targets.  Generic.
\item[Make.depend] List of dependencies.
\end{description}
%------------------------------------------------------------------------
\subsection{Program flow}

It all starts at ``{\tt main}'', in {\tt main.cc}.  The function
``{\tt main}'' has a loop that gets input and calls ``{\tt
  CMD::cmdproc}'' to dispatch the command.

Batch mode is done in ``{\tt process\_cmd\_line}'', by using ``{\tt
  CMD::cmdproc}'' to execute the commands ``{\tt get}'' or ``{\tt <}''
which is passed to ``{\tt CMD::cmdproc}'' as text.

The function ``{\tt CMD::cmdproc}'' dispatches the command to its
handler.  The handlers are located in the ``{\tt CMD}'' namespace, and
the ``{\tt c\_\*}'' files.
%------------------------------------------------------------------------
%------------------------------------------------------------------------
%------------------------------------------------------------------------
