---------------- This is Electric, Version 6.02 ----------------

This README file contains installation instructions for all 3 of the platforms
supported by Electric: UNIX, Macintosh, and Windows.

---------------- Requirements:

UNIX:
  Electric runs on most UNIX variants, including SunOS, Solaris, BSD, HPUX, AIX,
  and (of course) GNU/Linux.

Macintosh:
  Macintosh users must run System 7 or later. Electric compiles best under
  Metrowerks, although it has been built with MPW and THINK_C.
  A Metrowerks "XML" file is included.

Windows:
  Electric runs under Windows 95/98, Windows NT 4.0, or Windows 2000.  The
  system compiles with Visual C++ 5.0 or later (Visual C++ 6.0 project files
  are included).

---------------- Distribution:

The Electric distribution is a single file in UNIX "tar" format, GNU-zipped
(see http://www.gzip.org for more information).
> Macintosh users: You will have to locate a program that can read this
  file ("MacGzip", available at www.gzip.org, will unzip the file; MacTar,
  available at www.strout.net/macsoft/mactar, will extract the files).
  If you use some other method of extraction, beware of Macintosh line-feed
  conventions, which are different from those on other operating systems.
  You may need to set the "Convert Newlines" option in the "tar" program
  before extracting the files.  To be sure that the extraction has worked
  properly, examine the file "cadrc", which is at the top level (just inside
  of the "Electric" directory).  This file should have about 10 lines of text.
  If the file appears as a single line, or if there are spurious unprintable
  characters at the start or end of each line, then the text conversion has
  been done incorrectly.
> Windows users: You can use "WinZip" to extract this file.  Make sure that
  the "TAR File Smart CR/LF Conversion" box is checked in the "Configuration..."
  dialog of the "Options" menu.

When extracted, there will be a directory called "electric-VERSION" (where
the VERSION is the particular version number).  This directory will have
four subdirectories: "src", "lib", "examples", and "html".

The "src" directory contains the source code.  It is hierarchically
organized by function.

The "lib" directory has library files (more on that later).

The "examples" directory has some sample files.

The "html" directory contains one subdirectory, "manual", which is
the user's manual in HTML format.  To see the document, point your
browser to the file "index.html" inside of the "manual" directory.

---------------- Building (UNIX):

To configure for your system, go into the top-level directory and type:
        ./configure
This will examine the system and create a file called "Makefile".
To build Electric you now only need to use type:
        make
This compiles Electric and creates the executable file "electric"
in the top level directory.
Type "./electric" to run the system.

To add Java, follow these instructions:
> Download the Java Development Kit (JDK) from http://java.sun.com.  Install it.
  For the purposes of these instructions, assume that it is installed into
        /usr/java/jdk
  If you install it elsewhere, adjust these instructions accordingly.
> After configuration, but before making Electric, edit the "Makefile" and
  uncomment the lines near the top that enable Java.
  Change the definition of LANGJAVA_DIR to point to the installed JDK location.
> On Solaris, add this string to the environment variable LD_LIBRARY_PATH:
        :/usr/java/jdk/jre/lib/sparc:/usr/java/jdk/jre/lib/sparc/classic:/usr/java/jdk/jre/lib/sparc/native_threads
> On GNU/Linux, add this string to the environment variable LD_LIBRARY_PATH:
        :/usr/java/jdk/jre/lib/i386:/usr/java/jdk/jre/lib/i386/classic:/usr/java/jdk/jre/lib/i386/native_threads
> Be sure to export "LD_LIBRARY_PATH" if your shell requires it.

---------------- Building (Macintosh):

The Metrowerks project can be found in "Electric.xml".  Run Metrowerks,
import the file, and save it at the top-level (alongside the "src"
directory).

Compile Electric.  This will create the application "Electric".
Double-click the "Electric" application to run the system.  Note that
the program is rather big, so you may have to increase the size of
the Metrowerks partition to get it to compile.

---------------- Building (Windows):

There are a number of binary-format files that have been text-encoded into
the file "\src\graph\graphpc.uue".  Use "WinZip" to extract the files into
the same directory (there should be 5 cursor files that end in ".cur" and
2 icon files that end in ".ico").

To add Java, follow these instructions:
> Download the Java Development Kit (JDK) from http://java.sun.com.  Install it.
  The standard location is "C:\jdk1.3", and this path will be used here.
  If you install it elsewhere, adjust these instructions accordingly.
> Use the "System" Control Panel, click on the "Environment" tab, and under
  "System variables", select "Path". In the "Value:" area, add this string to the end:
        ;C:\jdk1.3\jre\bin\classic;C:\jdk1.3\bin
  You must restart your computer after making this change.
> In Visual C++, use the "Settings" command of the "Project" menu.  Select the
  "C/C++" tab and the "Preprocessor" category.  In the "Preprocessor definitions"
  area, add this to the end:
          ,FORCEJAVA=1
  In the "Additional include directories" area, add this to the end:
          C:\jdk1.3\include,C:\jdk1.3\include\win32
  Select the "Link" tab and the "General" category.  In the "Object/library modules"
  area, enter this:
          jvm.lib
  Select the "Link" tab and the "Input" category.  In the "Additional library path"
  area, enter this:
          C:\jdk1.3\lib

Run Visual C++ and open the workspace file "Electric.dsw" (both it and the
associated file "Electric.dsp" are in the top level, alongside the "src"
directory).  If you have trouble with these files, use the MAKE file
"Electric.mak".  Compile Electric.  This will create a new directory in the
top level called "Debug", which will contain all of the object files.

Inside of the "Debug" directory, you will find the executable file "Electric".
Move this file out of the "Debug" directory and place it in the top-level
directory.  Double-click the "Electric" executable to run the system.

---------------- Installing:

Once compiled, Electric will run properly from the directory where it was
built.  However, if you wish to install the system, you must move files
carefully.  This is because Electric makes use of a collection of "support
files".  The main support file is called "cadrc" (on UNIX, it has a dot in
front: ".cadrc").  In addition, Electric needs to find the "lib" and "html"
directories.  If these support files cannot be found, Electric will not be
able to initialize its graphical user interface (just type "-quit" to exit
the program if this happens).

On Windows and the Macintosh, it is sufficient to move the support files,
along with the executable, to a public location.  Then make an alias
(shortcut) to the executable and place that anywhere you like.  When the
alias is run, the directory with the executable will become the current
directory, and all of the needed support files will be found.

On UNIX, the "make install" command will place the executable and the support
files in a public location, but they may not be together.  For example, it is
not uncommon for the executable to be placed in "/usr/local/bin", but the
support files in "/usr/local/lib/electric".  When this happens, the executable
needs to know where the support files are located.  There are three ways to
do this:
 (1) You can set the ELECTRIC_LIBDIR environment variable to point to the
     location of the support files.
 (2) You can change the #define of "LIBDIR" in "src/include/config.h" to point
     to the location of the support files.
 (3) You can keep a local copy of ".cadrc" file (this file can be in your
     home directory or in the current directory).  Inside of the ".cadrc"
     file, change the "electric library default-path" command to point to the
     remaining support files (the "lib" and "html" directories).

UNIX systems also offer "make install.html" which installs the online manual
into a public place (typically "/usr/local/share/doc/electric/html").  Be sure
that the #define of "DOCDIR" in "src/include/config.h" agrees with this path
or else the "See Manual" command will not work.

---------- Additional Details (UNIX):

Electric uses "widget libraries" to control the windows on the display.
The default widget library is Motif (see http://www.opennc.org/openmotif) or
LessTif (see http://www.lesstif.org).  When installing these packages on your
system, be sure to get both the libraries and the "devel" package that contains
the compiler header files.  Also note that many systems use shared libraries for
these widget packages, and this may require some additional steps when installing.
This is because the libraries get installed in a place that the shared library
system doesn't know about.  If you have superuser access, you can use "ldconfig"
to tell the system where to find the libraries.  Otherwise, you can use
the LD_LIBRARY_PATH environment variable.  This variable is a colon-
separated list of paths to be searched for shared libraries.  For example,
this setting will work on many systems:
   LD_LIBRARY_PATH = /usr/X11R6/lib/
   export LD_LIBRARY_PATH

Besides Motif/Lesstif, users of Electric can also choose to use the
MIT Athena widget library.  The Athena Widgets are not only free, but usually
installed on every machine (HP UNIX users may have to install it specially
and modify the "Makefile" to locate it).  To switch to one of these
alternate widget libraries, edit the "Makefile" after running "configure"
(comments near the top explain what to do).

Electric two ways to control the display.  By default, the system runs
on any depth monitor, but is slow on older machines and must be run
locally (that is, the client and the server must be on the same computer).
The alternate method of display is faster and can run over the network,
but it can only support displays that are set to 8bpp (8 bits per pixel).
In addition, this alternate method will suffer from "colormap flashing"
when the cursor enters and leaves the Electric windows.  To switch to
this alternate method, edit the "Makefile" after running "configure"
(comments near the top explain what to do).  Note also that Motif and
Lesstif do not work well with this alternate display method, so you will
also have to switch to using the Athena widgets.

Electric makes use of external programs for simulation.  The location of
these programs can be found in the various #defines in the file
"src/include/config.h", which can be overridden with the following
variables in your ".cshrc" file:
   setenv ELECTRIC_SPICELOC   /usr/local/bin/spice
   setenv ELECTRIC_ESIMLOC    /usr/local/bin/esim
   setenv ELECTRIC_RSIMLOC    /usr/local/bin/rsim
   setenv ELECTRIC_PRESIMLOC  /usr/local/bin/presim
   setenv ELECTRIC_RNLLOC     /usr/local/bin/rnl

There are two command-line arguments that can be given which will control
the X-windows display.  If you use the "-f" option, Electric
will start with a full-screen graphics window.  If you use the
"-geom WxH+X+Y", it will set the graphics window to be "W" wide,
"H" high, and with its corner at (X, Y).  Additional X-Windows options
can be typed into the file ".Xdefaults".  The resources "Electric.font0"
through "Electric.font8" set the font to use for point sizes 4, 6, 8, 10,
12, 14, 16, 18, and 20.  The resource "Electric.fontmenu" controls the
text used in the component menu, and the resource "Electric.fontedit"
controls the text used in the text editor.  Here is a sample line from
the file:
   Electric.font5: -misc-fixed-medium-r-normal-*-*-140-*-*-*-*-*-*
To see what all of these fonts look like, load the library "samples.txt"
(with the "Readable Dump" subcommand of the "Import" command of the "File"
menu) and edit the facet "tech-Artwork".  The top part of the facet shows
text in sizes 4 through 20.

---------- Additional Details (Windows):

Electric must be run with the Display Settings set to "65536 Colors" or
"True Color".  Anything less will cause the colors to appear wrong.

---------------- Discussion:

There are two GNU mailing lists devoted to Electric:
    bug-gnu-electric
	discuss-gnu-electric
To subscribe to them, send mail to
	bug-gnu-electric-request@gnu.org
	discuss-gnu-electric-request@gnu.org
with the subject "subscribe".  You can then send messages to
	bug-gnu-electric@gnu.org
	discuss-gnu-electric@gnu.org

In addition, you can send mail to:
	info@staticfreesoft.com


