                                               Install
                                              ---------
Start Date  : 2004-04-04
Last Update : 2018-10-24
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 makes use of 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 or provide it as an pre-built
package, this is the preferred option. There are circumstances however where building the wxWidgets
library yourself may be necessary. One such instance is when the ABI (Application Binary Interface)
of the pre-built package differs from the compiler used to build the target application ie.
gSpiceUI. The following instructions should be helpful.

The wxWidgets home page is :

  http://www.wxWidgets.org/

The recommended version of the wxWidgets library is v3.0.x although 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 the root password
  make install

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

         --prefix=<DIR>        (Installation directory, default /usr/local)
         --without-subdirs     (Don't generate makefiles for samples/demos/...)
         --disable-compat28    (Disable wxWidgets 2.8 compatibility)
         --enable-debug        (Build the library for debugging)
         --enable-debug_info   (Create code with debugging information)
         --enable-debug_gdb    (Create code with extra GDB debugging information)
         --disable-debug_flag  (Disable all debugging support ie. unset the __WXDEBUG__ flag)
         --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. Alternatively some distributions offer a
       compatibility layer eg. on Fedora there is a package called "compat-wxGTK3-gtk2".

       To view all available options to the configure script enter :

         ./configure --help

Note : If building wxWidget-2.8.x change the configure script line to :
         ./configure --without-subdirs --disable-compat26 --enable-unicode

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

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 the binary file "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
            -e EDA    : Specify the EDA tool suite to be used
                        EDA    = lepton (Lepton-EDA) or geda (gEDA / GAF)
            -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 and may 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

Note : The MinGW environment can be accessed from Windows, outside of the MSYS shell. Paths
       containing forward slashes ('/') are from within MSYS and paths containing back slash ('\')
       are from Windows. Eg. the path to my home directory within MSYS is /home/msw, whereas from
       Windows it's C:\MinGW\msys\1.0\home\msw.

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 exists and contains at least the following
        line, 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.3.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.3
      * 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
        Notes : 1. My AVG virus scanner breaks the configuration process when the TIFF library is
                   processed. There are two solutions : disable the TIFF library by adding the
                   option "--without-libtiff" to the above command line or temporarily disable the
                   AVG Resident Shield component.
                2. The build process can be sped up if the wxWidgets samples and demos are skipped.
                   Add the option "--without-subdirs" to the above command line.
      * Build wxWidgets :
          make MONOLITHIC=1 SHARED=0 UNICODE=1 BUILD=release DEBUG_FLAG=0
      * Install the wxWidgets libraries :
          make install

  4. Build gSpiceUI using MinGW :
      * Retrieve the gSpiceUI sources and store them in eg. your MinGW home directory.
      * Open MSYS and unpack the gSpiceUI sources eg. :
          tar -zxvf gspiceui-v1.2.00.tar.gz
      * Enter to the wxWidgets sources root directory eg. :
          cd ~/gspiceui-v1.2.00
      * Build the gSpiceUI sources (the same as for Linux) :
          make GSPICEUI_MSWIN=1
      * 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 a start (for someone else
       to build on).

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

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.

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