                                               Install
                                              ---------
Started : 2004-04-04
Updated : 2020-10-17
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.  Examples.
  7.  Microsoft Windows Support.
  8.  Apple Mac OSX Support.

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

1.  Introduction.


The best and easiest option for installing gSpiceUI is to use pre-built packages for your operating
system, including the applications gSpiceUI depends on. However, if gSpiceUI must be built from
it's sources this file contains instructions and information to assist in the process.

These instructions provide information required to compile and install gSpiceUI in the most common
and simplest cases. For a more detailed instructions refer to the gSpiceUI PDF user manual found in
the documentation directory ie. "<GSPICEUI_DIR>/doc/gspiceui-man.pdf".

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

2.  Requirements.


There are various requirements for building gSpiceUI and running it in a meaningful way. The
different requirements 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.
  * Run time    (Optional)  : Kst   analogue waveform viewer.
  * EDA         (Optional)  : gEDA-gaf   EDA (Electronic Design Automation) tool suite.
  * EDA         (Optional)  : Lepton-EDA EDA (Electronic Design Automation) tool suite.
  * User Manual (Optional)  : NG-SPICE installed as /usr/share/doc/ngspice/manual.pdf
  * User Manual (Optional)  : GNU-CAP  installed as /usr/share/doc/gnucap/gnucap-man.pdf

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

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 a pre-built
package, this is the preferred option. There are circumstances however where building the wxWidgets
library yourself may be necessary. Refer to the gSpiceUI PDF user manual for detailed instructions.

One instance where building gSpiceUI from it's sources might be necessary is when the ABI
(Application Binary Interface) of the pre-built library (wxWidgets) differs from the compiler used
to build the target application (gSpiceUI). Under these circumstance a warning message is displayed
when gSpiceUI is started stating that the ABI of gSpiceUI doesn't match that of the wxWidgets
library. To date this hasn't been a problem other than it is annoying.

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

4.  Build System.


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

    make
  OR
    gmake         (for FreeBSD)
  OR
    make          (for MAC OSX)
    make maccfg

If all goes well the binary file "gspiceui" should have been generated in the directory
<INSTALL_DIR>/bin.

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

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 the directory /usr/local/bin/ and the documentation and other
supporting files are installed in the directory /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 DESTDIR in the
main Makefile or by specifying it on the command-line as the following example illustrates :

    make install DESTDIR=/alternative/install/directory

This applies equally for the uninstall operation :

    make uninstall DESTDIR=/alternative/install/directory

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

6.  Examples.


The directory <GSPICEUI_DIR>/gspice/sch contains some example schematic files (all having the file
extension .sch) which can be loaded into gSpiceUI using the Import command under the File menu.

Note : The schematic examples which contain an operational amplifier require a symbol file which is
       not currently part of the schematic capture (eg. gschem) symbol library. The netlister (eg.
       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 the schematic capture symbol library. Eg. for gEDA-gaf and
       gschem, as root enter a copy command of the form shown below :

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

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

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

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 providing
the required packages which are outline below :

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

An article written by Oliver Kohl "Using wxWidgets under Windows" was very helpful in formulating
these instructions. The article 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".

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

8.  Apple Mac OSX Support.


The good news is that gSpiceUI can be installed and run on 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.

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