                                               ReadMe
                                              --------
Started : 2004-04-03
Updated : 2020-10-17
Author  : Mike Waters
Email   : mwaters517_AT_gmail_DOT_com
====================================================================================================

                                          Table of Contents

  1.  Introduction.
  2.  Documentation.
  3.  Installation.
  4.  Usage.
  5.  Examples.
  6.  Bugs / Things To Do.
  7.  MS Windows & Apple Mac OSX Support.

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

1.  Introduction.


GNU SPICE GUI provides a GUI front-end for various freely available electronic circuit simulation
engines ie. NG-SPICE and GNU-CAP. It's core function is to generate simulation engine instructions
based on user input. However, it also offers extra functionality via applications and utilities
developed by others. Electronic Design Automation (EDA) tool suites are used to provide schematic
capture and editing, and schematic to netlist conversion. Waveform data viewers are used to display
simulation results and PDF viewers to display user manuals.

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

3.  Documentation.


Refer to the PDF user manual in <GSPICEUI_DIR>/doc/gspiceui-man.pdf or within the gSpiceUI
application refer to the PDF user manual from the Help menu or toolbar icon.

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

2.  Installation.


Refer to the text file Install and the PDF user manual.

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

4.  Usage.


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

Analyse a electronic circuit using a GUI front-end to numerical simulation engines

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

  OPTIONS : -h          : Print usage information (this message) and quit
            -v          : Print version information and quit
            -c          : Rebuild/clean the configuration file and quit
            -d          : Enable debug mode (generate console spew on stderr)
            -r <RCFILE> : Specify a configuration file
                          <RCFILE> = ~/.gspiceui.conf (default)
            -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)
            -w <WAVWR>  : Specify the waveform data viewer to be used
                          <WAVWR>  = gaw ,gwave or kst
            -g [<PROC>] : Import schematic file/s and (optionally) specify the
                          Guile procedure to use
                          <PROC>   = spice-sdb (default), protelii, verilog, etc.
            -a <PAGE>   : Specify the analysis page to be displayed
                          <PAGE>   = op (default), dc, ac, tr

  FILE/S  : Load a circuit description (netlist) file or import schematic file/s

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

5.  Examples.


The directory <GSPICEUI_DIR>/sch contains various schematic files which may be used to experiment
with gSpiceUI. These examples show how to prepare a schematic for simulation, which is not always a
trivial task.

The directory <GSPICEUI_DIR>/sch/demos contains various small example schematic files which are
intended to illustrate the simulation of specific circuit elements eg. a diode. The intention is
that these schematics should all work when simulated using gSpiceUI.

The remaining schematics files in <GSPICEUI_DIR>/sch are not guaranteed to behave properly when
simulated. These files are a collection of things that have taken my interest over the years, some
work and some don't.

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

6.  Bugs / Things To Do.


Refer to the text file ToDo for a list of known bugs and features which could be added in the
future. If you have the program sources the file <GSPICEUI_DIR>/src/Version.hpp contains a list of
bugs which need addressing in the short term.

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

7.  MS Windows and Apple Mac OSX Support.


Periodically I get asked about support for MS Windows and Mac OSX. What follows provides general
information on the topic.

One of the original reasons for choosing the wxWidgets library was cross platform support. In theory
it would be possible to build and run gSpiceUI in any environment having the GNU C++ compiler and
wxWidgets support. As it turned out, some gSpiceUI users did exactly that and started using gSpiceUI
on Windows and Mac OSX. There are patches summited by these users that have already been added to
the code base so that, according to reports, gSpiceUI can be used in both environments. Although, I
haven't yet done any testing myself.

I'm an infrequent MS Windows user and practically never use Mac OSX, most of my effort goes into
maintaining gSpiceUI for Linux (which is headache enough in itself). Consequently, gSpiceUI will
likely work best on Linux, but given the number of Windows users I intend to do some testing on that
platform. Apple Mac OSX will be more difficult owing to the restrictive nature of the company (I
don't own an Apple and haven't been able to successfully virtualize OSX under Linux yet).

The Install file contains instructions on how to build gSpiceUI for Windows but there are currently
no such instructions for OSX however. Based on user reports I believe it can be done. If anyone
would like to provide build instructions for OSX I'd be glad to add them to the gSpiceUI
documentation.

gSpiceUI has been developed under Linux using the GNU GCC compiler and Makefiles. Using another
compiler and build system is no doubt possible but it will would require some work. Since the GNU
development tools are available for Windows and OSX it would seem wiser to use them.

Keeping in mind that gSpiceUI is only useful in concert with other applications (eg. gEDA-gaf,
Lepton-EDA, NG-SPICE, GNU-CAP, Gaw, etc.), it is just a graphical front end and doesn't do any of
the heavy lifting. Consequently at least some of these other applications will also need to be built
for Windows and/or OSX.

Many programmers use an IDE to take care the build system for a project. Years ago I decided to go
IDE independent and started using the 'make' utility and hand crafting Makefile's. One of the many
reasons for this decision was the belief that understanding the build system is as important as
understanding the programming language. Using Makefile's forces me to understand the build system.
There are no IDE specific project files in the gSpiceUI code base so any IDE could be used to
develop gSpiceUI.

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