Install
                                              ---------
Start Date  : 2004-04-04
Last Update : 2016-10-26
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.
   9.  Microsoft Windows Support.
  10.  Apple Mac OSX Support.

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

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 and this is the preferred option.

If however you are determined to build the wxWidgets library yourself then the following instruction
should help. The home page is :

  http://www.wxWidgets.org/

The recommended version of the wxWidgets library is v3.0.x however v2.8.x should still work. The
archive file for a Linux based system is :

  wxWidgets-3.0.x.tar.bz2

Untar the wxWidgets archive as follows :

  tar -jxvf wxWidgets-3.0.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 --without-subdirs --disable-compat28
  make
  su
  Password:         <-- enter root password
  make install

Note : Options which may be added to the ./configure command include :

         --without-subdirs     (Don't generate makefiles for samples/demos/...)
         --disable-compat28    (Disable wxWidgets 2.8 compatibility)
         --disable-debug_flag  (Disable all debugging support ie. unset the __WXDEBUG__ flag)
         --enable-debug_info   (Create code with debugging information)
         --enable-debug_gdb    (Create code with extra GDB debugging info.)
         --with-gtk[=VERSION]  (Use GTK+, VERSION can be 3, 2 (default), 1 or "any")

       At the time of writing there appear to be display problems when wxWidgets is compiled against
       GTK3, so building against GTK2 is recommended.

       To view all available options to the configure script enter :

         ./configure --help

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

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.8.x use :
           make GSPICEUI_WXLIB=2.8

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 (generate 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 = ngspice or gnucap
          -a ANA    : Specify the analysis page to be displayed
                      ANA    = op, dc, ac, tr
          -g [PROC] : Guile procedure for importing a schematic file with gnetlist
                      PROC   = spice-sdb, pcb, protelii, verilog, etc.
          -w VIEWER : Specify the waveform data viewer to be used
                      VIEWER = gaw or gwave

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

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

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.

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

9.  Microsoft Windows Support.


This section provides a broad outline of how to build gSpiceUI on MS Windows. The methodology has
been developed and tested on Windows 7 but should work on other releases. Detailed instructions are
not provided since this information can change and so is best sourced from the Web sites for the
required packages ie. MinGW / MSYS and wxWidgets.

MinGW ("Minimalist GNU for Windows") is a minimalist development environment for native Microsoft
Windows applications. MSYS ("Minimal SYStem") is a Bourne Shell command line interpreter system.
It's an alternative to Microsoft's cmd.exe providing a general purpose command line environment
particularly suited to use with MinGW.

wxWidgets is a C++ library that lets developers create applications for Windows, Mac OS X, Linux and
other platforms with a single code base.

There is an article which was very helpful in formulating these instructions, by Oliver Kohl "Using
wxWidgets under Windows", it can be found at :
  http://www.codeproject.com/Tips/630542/Using-wxWidgets-under-Windows

The steps to building gSpiceUI for Windows are as follows :

  1. Install MinGW and MSYS :
      * Go to http://www.mingw.org/ and retrieve the MinGW installer "mingw-get-setup.exe".
      * Run the installer and select at least the following packages : C & C++ compilers and MSYS.
        (If MinGW is installed in the root of your system drive (eg. C:\MinGW) you'll have no
        problems with navigation and paths.)
      * The installer will retrieve the selected packages from the Web and install them.
      * Ensure that the file C:\MinGW\msys\1.0\etc\fstab and contains at least the following line
        itself followed by an empty line :
          C:\MinGW   /mingw
      * Now navigate to C:\mingw\msys\1.0 and run msys.bat, this creates your home folder.
      * It is worth creating a start menu item and/or a desktop icon for msys.bat.
  2. Install the wxWidgets sources :
      * Go to http://www.wxwidgets.org/ and retrieve the wxWidgets sources eg. wxWidgets-3.0.2.zip.
      * Create a folder (eg. C:\wxWidgets) and unpack the wxWidgets sources archive into it.
  3. Build wxWidgets using MinGW :
      * Open MSYS and go to the wxWidgets sources root directory eg. :
          cd c:\wxWidgets\wxWidgets-3.0.2
      * Create the build folder and navigate into it eg. :
          mkdir build-msw
          cd build-msw
      * Run the wxWidgets configure script which creates the make files and sets system-dependent
        variables :
          ../configure --build=x86-winnt-mingw32 --disable-shared --disable-threads
      * Build wxWidgets :
          make MONOLITHIC=1 SHARED=0 UNICODE=1 BUILD=release DEBUG_FLAG=0
      * Install the wxWidgets libraries :
          make install
  5. Build gSpiceUI using MinGW :
      * Unpack the gSpiceUI sources within the MSYS file system eg. C:\MinGW\msys\1.0\home\user.
        (This isn't essential since you can navigate anywhere within MSYS, it just makes it easier.)
      * Open MSYS and go to the wxWidgets sources root directory eg. :
          cd ~/gspiceui-v1.1.00
      * Build the gSpiceUI sources (the same as for Linux) :
          make
      * If all goes well you can now run gSpiceUI under Windows :
          bin/gspiceui.exe

Note : There will be things that don't work in gSpiceUI under Windows eg. opening the online manual.
       The Windows setup seems to be a bit different from Linux but it's start (for someone else).

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

10.  Apple Mac OSX Support.


The good news is that gSpiceUI can be installed and run under OSX (based on user reports). The bad
news is that I don't have any instructions on how to do it since I don't have access to an OSX
system. I've added patches to the code base provided by OSX user who are running gSpiceUI on OSX.
I've tried to run a OSX client under Qemu but without success so far. If anyone wants to provide
some instructions I'm happy to insert them here.

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