                                               Install
                                              ---------
Start Date  : 2004-04-04
Last Update : 2015-04-04
Author      : Mike Waters
Email       : mwaters517_AT_gmail_DOT_com
====================================================================================================

                                          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)  : Gaw   analogue waveform viewer.
  * Run time    (Optional)  : 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 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
            -d        : Enable debug mode (generates console spew on standard error)
            -r RCFILE : Specify a configuration file
                        RCFILE = ~/.gspiceui.conf (default)
            -c        : Rebuild/clean the configuration file
            -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 for importing a schematic file with gnetlist
                        PROC   = spice-sdb (default), pcb, protelii, verilog, etc.
            -w VIEWER : Specify the waveform viewer to be used
                      VIEWER = gaw (default), gwave or gwave2

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

  NOTES   : Option -s should 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.

====================================================================================================
