                                    Install
                                   ---------
Start Date  : 04/04/2004
Last Update : 24/03/2011

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

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

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

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

                               Table of Contents

  1.  Introduction.
  2.  Requirements.
  3.  wxWidgets Library.
  4.  Build System.
  5.  Installation.
  6.  Usage.
  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    (Optional)  : gwave analogue waveform viewer.
  * Run time    (Optional)  : Gaw   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 feature this provides is the POLY() function which is used
       in many operational 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 work. (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, so it should
be straight forward. If necessary refer to the installation instructions
provided with the wxWidgets sources (in the docs directory). Do the following
in the wxWidgets base directory :

  mkdir my-build
  cd my-build
  ./configure --enable-unicode --without-subdirs --disable-compat26 --disable-xrc
  make
  su
  Password:         <-- enter root password
  make install

Note : Options which may be added to the ./configure command include :
         --enable-unicode      (Compile wxString with Unicode support)
         --without-subdirs     (Don't generate makefiles for samples/demos/...)
         --disable-compat26    (Disable wxWidgets 2.6 compatibility)
         --enable-debug_flag   (Set the __WXDEBUG__ flag)
         --enable-debug_info   (Create code with debugging information)
         --enable-debug_gdb    (Create code with extra GDB debugging info.)
         --disable-xrc         (Don't build XRC resources sub-library)

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

4.  Build System.


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.  Installation.


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/gspiceui/.

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 (or DESTDIR) in the main Makefile or by specifying it on
the command-line as the following example illustrates :

    make install INSTALLDIR=/alternative/install/directory

This applies equally for the uninstall operation :

    make uninstall INSTALLDIR=/alternative/install/directory

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

6.  Usage.


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

  Analyse a electronic circuit using a GUI to a numerical simulation engine

  USAGE   : gspiceui [-OPTION [ARG]] [FILE/S]

  OPTIONS : -h        : Print usage (this message)
            -v        : Print version information
            -r RCFILE : Specify a configuration file
                        RCFILE = ~/.gspiceui.conf (default)
            -s SIMENG : Specify the simulation engine to be used
                        SIMENG = 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.
            -w VIEWER : Specify the waveform viewer to be used
                        VIEWER = gwave (default) or gaw

  ARGS    : FILE/S    : Import schematic file/s or load a circuit description file

  NOTES   : Option -s must come before -a if both are specified

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

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 component pin
       sequence which itself must match the associated model pin sequence.
       Consequently, to use these examples the symbol file opamp-3.sym must be
       copied to your gschem symbol library. As root enter a copy command of
       the form shown below :

         cp <DIR>/gspiceui/lib/sym/opamp-3.sym /usr/share/gEDA/sym/local/

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

8.  Files.


It's worth noting that gSpiceUI can create many disk files during it's
operation. For a brief explaination of the various file types and their
purposes refer to the User Manual provided in the HTML documentation directory
ie. "<root>/html/gSpiceUI.html".

As gSpiceUI is developed the format of the configuration file evolves
(ie. ~/.gspiceui.conf). Over time it can become cluttered with superseded
variable names and/or group names. The configuration file may be partially
rebuilt using the command line option : "-c". At present the only way to ensure
that you have a pristeen configuration file is to delete it manually and allow
gSpiceUI to create a new one. Although this should not be essential, rebuilding
the configuration file will at least help with human readability.

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