                                    INSTALL
                                   ---------
Start Date  : 04/04/2004
Last Update : 09/10/2007

-------------------------------------------------------------------------------

gSpiceUI - A Graphical User Interface (GUI) to various freely available Spice
           electronic circuit simulators.

Author : Mike Waters
Email  : M.Waters@bom.gov.au

-------------------------------------------------------------------------------
                               Table of Contents

  1.  Introduction.
  2.  Requirements.
  3.  wxWidgets Library.
  4.  Compiling.
  5.  Installing.
  6.  Running.
  7.  Examples.
  8.  Files.

-------------------------------------------------------------------------------
1.  Introduction.


These instructions provide information required to compile and install gSpiceUI
and basic instructions on envoking gSpiceUI. For a more detailed description
refer to the HTML user manual in html/gSpiceUI.html.

-------------------------------------------------------------------------------
2.  Requirements.


There is one essential requirement for compiling gSpiceUI, three desirable
requirements for running gSpiceUI meaningfully and two optional requirement.
These are listed below :

  * Compilation (Essential) : The wxWidgets library.
  * Run time    (Desirable) : GNU-Cap  electronic circuit simulation engine.
  * Run time    (Desirable) : NG-Spice electronic circuit simulation engine.
  * Run time    (Desirable) : gWave analogue waveform viewer.
  * Schematic   (Optional)  : gNetList schematic importing tool.
  * Schematic   (Optional)  : gSchem schematic generation/viewing tool.

Note : As a minimum NG-Spice should be compiled with XSpice enhancements
       enabled. One of the things this provides is the POLY() function which is
       used in many operation amplifier models. XSpice enhancements are enabled
       via the NG-Spice configure script prior to compiling the sources, ie. :
         ./configure --enable-xspice

-------------------------------------------------------------------------------
3.  wxWidgets Library.


gSpiceUI is written in C++ and is based on the wxWidgets library. wxWidgets
offers the possibility of compiling the same source code under Linux/UNIX,
MS Windows, OSX and various other platforms. This library must be installed
before gSpiceUI can be compiled.

Many systems now come with a version of wxWidgets pre-installed. The wxWidgets
home page is :

  http://www.wxWidgets.org/

The recommended version of the wxWidgets library is v2.8.x however v2.6.x may
still be used. (Note : wxWidgets v2.6.x may generate some console spew on
standard error which may be ignored eg. "gspiceui 2>/dev/null".) The archive
file for a Linux based system is :

  wxGTK-2.8.x.tar.bz2

Untar the wxWidgets archive as follows :

  tar -jxvf wxGTK-2.8.x.tar.bz2

Installation of wxWidgets is based around autoconf and automake and so is
straight forward. Refer to the installation instructions provided with the
sources. It is recommended that Unicode support be enabled as follows :

  ./configure --enable-unicode
  make
  su  (as root)
  make install

-------------------------------------------------------------------------------
4.  Compiling.


Assuming the wxWidgets library has been installed, go to the gSpiceUI root
directory and enter the following :

    make
  OR
    gmake (for FreeBSD)

Note 1 : MAC users, enter the following before entering the above :
           make maccfg
         this creates some directories and copies some files, it only needs to
         be performed once per installation.
Note 2 : To compile against mwxWidgets v2.6.x use :
           make GSPICEUI_WXLIB=2.6

If all goes well a binary named gspiceui should have been generated in the
<ROOT>/bin directory.

-------------------------------------------------------------------------------
5.  Installing.


The application may be installed into /usr/local by entering the following
command as root :

    make install
  OR
    gmake install (for FreeBSD)

The application binary is intalled in /usr/local/bin. The documentation and any
other support files are installed in /usr/local/share/gspice.

The application may be uninstalled by entering the following command as root :

    make uninstall
  OR
    gmake uninstall (for FreeBSD)

An alternative install path may be specified by manually changing the make
variable INSTALLDIR in the main Makefile or by specifying it on the command
line as the following example illustrates :

    make install INSTALLDIR=/alternative/install/directory
    make uninstall INSTALLDIR=/alternative/install/directory

This applies equally for the uninstall operation.

-------------------------------------------------------------------------------
6.  Running.


Change to the gspiceui/bin directory and execute the binary gspiceui in
situ. Usage information is listed below :

  Usage : gspiceui [-OPTION [ARG]] [FILE/S]
  Analyse a circuit using a SPICE electronic circuit simulation.
  Options :
    -v          : Print version information.
    -h          : Print usage (this message).
    -r <RCFILE> : Specify a configuration file.
                    <RCFILE> = ~/.gspiceui.conf (default))
    -s <SIM>    : Specify the simulation engine to be used.
                    <SIM> = gnucap (default) or ngspice
    -a <ANA>    : Specify the analysis page to be displayed.
                    <ANA> = OP, DC (default), AC, TR, FO, DI, NO, PZ, SE or TF
    -g [<PROC>] : Guile procedure to import a schematic file using gNetList.
                    <PROC> = spice-sdb (default), PCB, protelII, verilog, etc.
    [FILE/S]    : Load a circuit description file or import schematic file/s.

Note: If both -s and -a options are specified the -a option must be specified
      after the -s option.

-------------------------------------------------------------------------------
7.  Examples.


The directory gspice/sch contains some example schematic files (with the file
extension .sch) which can be loaded using the Import command under the File
menu. (These schematic files have been generated using gSchem the gEDA
schematic capture application and are converted to net list format using
gNetList.)

NOTE : The schematic examples which contain an operational amplifier require a
symbol file which is not currently part of the gSchem symbol library. gNetList
uses the symbol pin sequence to generate it's SPICE component pin sequence
which itself must match the associated SPICE model pin sequence. Consequently,
to use these examples the symbol file opamp-3.sym must be copied to your gSchem
symbol library. On my system I execute the following command as root :

  cp /home/msw/gspiceui/lib/sym/opamp-3.sym /usr/geda/share/gEDA/sym/local/

-------------------------------------------------------------------------------
8.  Files.


It should be noted that gSpiceUI can create many files for various purposes
during it's operation. Refer to the documentation for details.

-------------------------------------------------------------------------------
