---------------- This is Electric, Version 6.04 ----------------

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, Windows 2000, or Windows XP.
  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.

Electric has the option of using TrueType fonts.  If you want this, follow these instructions:
> Obtain Rainer Menzner's "T1Lib".  It is described here:
    http://www.neuroinformatik.ruhr-uni-bochum.de/ini/PEOPLE/rmz/t1lib/t1lib_doc/t1lib_doc.html
  and version 1.1.0 can be obtained here:
    ftp://sunsite.unc.edu/pub/Linux/libs/graphics/t1lib-1.1.0.tar.gz
  or here:
    ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/t1lib-1.1.0.tar.gz
  Once you have it, unpack it (it will create a directory called "T1-1.1.0"), go into that
  directory, type "./configure" and then type "make".  You can then install with "make install".
> Now go to the Electric directory and edit the "Makefile".  Near the top are comments labeled
  "T1LIB TRUETYPE".  Uncomment the two lines (remove the "#" from the beginning of the lines)
  and change the lines so that they point into the T1Lib folder that you have just installed.
  For example, if the T1Lib libraries installed into "/usr/local/lib" and the T1Lib headers
  installed into "/usr/local/include", then you want these lines to read:
    TRUETYPE_LIBS = /usr/local/lib/libt1.a
    TRUETYPECFLAGS = -DTRUETYPE=1 -I/usr/local/include
> Next (this is the most painful part), you have to set the environment variable T1LIB_CONFIG
  to point to the file "t1lib.config".  This file may be installed in "/usr/local/share/t1lib".
  There will certainly be a copy in the "examples" folder of the distribution.  The catch here is that
  this file has relative path names in it which must be converted to absolute.  So, if you have
  extracted the T1Lib distribution into the folder "/home/strubin/T1-1.1.0", then the file should
  look like this:
    This is a configuration file for t1lib
    FONTDATABASE=/home/strubin/T1-1.1.0/examples/FontDataBase
    ENCODING=/home/strubin/T1-1.1.0/Fonts/enc:.
    AFM=/home/strubin/T1-1.1.0/Fonts/afm:.
    TYPE1=/home/strubin/T1-1.1.0/Fonts/type1:.
> Finally, rebuild Electric with the TrueType library.  When you run it, you will get a warning if
  any of the TrueType initialization fails (in which case it will revert to the non-TrueType code).
  Otherwise, you have it.
> Note that Electric uses the first font in the database by default.  To change the font that
  Electric uses, set the environment variable ELECTRIC_TRUETYPE_FONT to the desired font name.
  You can see a list of available fonts by setting this environment variable to an unknown name,
  in which case Electric will show all fonts in its error message.

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):

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.

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" (or whatever the version is), and this path
  will be used here.  If you install it elsewhere, adjust these instructions accordingly.

> Edit the environment variables in the "System" Control Panel.
  On some systems, you click on the "Environment" tab; on others, click on the "Advanced"
  tab and then click the "Environment Variables" button.
  Under "System variables", select "Path" and 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

---------------- 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).
You can use LessTif (see http://www.lesstif.org), but has some bugs (you will
have to remove the "XtDestroyWidget()" call in "DiaDoneDialog()").  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 (on AIX use LIBPATH and on HP-UP use SHLIB_PATH).  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, 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.

If you have trouble reading the cursor or icon files (".cur" or ".ico") you can
find a text-encoded version of these binary files in \src\graph\graphpc.uue.
Use "WinZip" to extract the files into the same directory.

---------- Internationalizing Electric:

Electric is able to interact in other languages than English.
Currently, there is a French translation.

To use this facility on GNU/Linux, edit the "Makefile" and follow the instructions for
"Internationalization".  You must then set the environment variable "LANGUAGE" to the
proper language ("fr" for French).

To use this facility on Windows or the Macintosh, you must obtain the Static Free Software
extensions and build the "International" version of Electric.  Before compiling, set the
desired language by changing the routine "elanguage()" (on Windows, it is in
"graph/graphpccode.cpp"; on the Macintosh it is in "graph/graphmac.c").

At any time, you can disable the foreign language and return to English by moving the
translation files.  These files are in the "lib/international" folder, with a subfolder
that has the language name (for example, French translations are in "lib/international/fr").
Beneath that is a folder called "LC_MESSAGES" and inside of that are the translation files.


If you wish to translate Electric yourself, look in the appropriate folder for that
language.  There you will find two types files: the translation file and its binary equivalent.
The binary file is named "electric.mo" and the translation file ends in the language name
("electric.fr" for French).
Note also that the Macintosh uses different characters than UNIX and Windows, so there
will also be a second set of files ("macelectric.mo" and "macelectric.fr").

When repairing or augmenting a translation, edit the appropriate translation file.  It must
then be converted to/from Macintosh encoding, and then both files must be converted to the
binary format.

When creating a new translation, you can start with the file "lib/international/messages.po"
which has all of Electric's messages but no translations.  Rename this file appropriately
and edit it.


If you are using GNU/Linux, you can edit this file with EMACS and use "po-mode", which
assists in translation.  If you do not have access to this, you can use Electric's built-in
translation editor.  Use the "General Options" subcommand of the "User Interface" command of
the "Info" menu; click "Advanced" and then click "Language Translation".


If you edit the translation file by hand, you will see groups of lines that look like this:
	#: src/usr/usrcomtv.c:233
	#, c-format
	msgid "Technology %s is still in use"
	msgstr ""
The line that begins with "#:" is the location in the source code of the string.
The line that begins with "#," contains flags that are unimportant.
The line that begins with "msgid" is the string in English.
The line that begins with "msgstr" is an empty string, and it is where you type the translation.


In some cases, the first line is many lines (if the string appears in many places in the code).
For example:
	#: src/io/iocifin.c:208 src/io/iodefi.c:117 src/io/iodxf.c:487
	#: src/io/ioedifi.c:810 src/io/iogdsi.c:1955 src/io/iolefi.c:113
	#: src/io/iosdfi.c:157 src/io/iosuei.c:238 src/io/iotexti.c:375
	#: src/io/iovhdl.c:57
	#, c-format
	msgid "File %s not found"
	msgstr ""


Be aware that many of these strings have formatting control in them.  An example is shown above.
The string is "File %s not found", and the "%s" part of the string will be replaced with the
name of a file.  When you translate it, leave the "%s" so the substitution will work.
In French, that string will be "Fichier %s introuvable".

The common substitutions that you will find are "%s" for string and "%d" or "%ld" for numbers.
There might even be a substitution that has digits in it such as "%3d"  Be warned that the
order of the substitutions must be preserved, and so must the exact sequence of characters in
the substitution.  For example, the string:
    "Unknown section name (%s) at line %ld"
has two substitutions, and the translation must have the "%s" before the "%ld"
(even if the sentence is awkward).


At some point in the translation process, you may see the keyword "fuzzy" on the flags line
(the line that begins with "#,").  This indicates that some program guessed at the translation
because of similarity.  No human did a translation for this string, and it may be wrong.
Verify the translation and remove the word "fuzzy".


Some lines begin with "#~", for example:
	#~ msgid "File Format:"
	#~ msgstr "Format fichier"
This indicates messages that were translated but are no longer used in Electric.  The
translations are kept around in case the messages reappear in a later version of Electric.
None of the lines that begin with "#~" should require translation, so you can safely ignore them.


Some translations span two lines, for example:
	#: src/db/dbchange.c:1114
	#, c-format
	msgid "Warning: Could not find index %ld of attribute %s on object %s"
	msgstr ""
	" Attention: Impossible de trouver l'index %ld de l'attribut %s de l'objet %s"
This is standard format for the translation package.  It is permitted for the translation
to span more than 1 line in the file, but in all cases these strings are concatenated together
to form 1 string.


Sometimes the English contains the character "&" where it makes no sense (for example, the
word "P&rint").  These are markers for "quick keys" in pulldown menus.  When the "&" is in
front of the letter "X", it means that typing "X" will invoke that menu entry.  However, each
menu must have the "&" in front of a unique letter.  And since you cannot tell, when you are
translating, which strings are grouped into a single menu, it is best if you simply ignore the
"&" character and translate the string without it.  Note, however, that the character should
be preserved where it makes sense, such as in the expression "black&white".


An alternate "quick key" marker is the string "/X" at the end of a phrase.  This indicates that
the Control-X key will invoke that menu entry.  These letters are not part of the phrase, and
so they do not need to be translated (just left alone).  Ambitious translators will want to
rearrange these control-keys so that they make sense for the language.


Some phrases end with an elipsis ("...").  These are used in pulldown menu entries that
invoke dialogs.  Keep the elipses when translating.


Here are some terms that may be confusing:
	"jog" describes a wire that makes two bends.  Like a "Z", it turns in one direction
		and then back again.  Also called a "zig-zag" in English.
	"R-Tree" is a technical term...you can translate "tree" (as in "tree structure",
		something that branches), and leave the letter "R".
	"high" refers to a signal level (high voltage, low voltage).
	"trans" is an abbreviation for "transistor"
	"diff" is an abbreviation for "diffusion" (the active layer on an IC).
	"gate" is the polysilicon layer on a chip that "gates" (controls) the transistor.
	"deck" refers to a disk file with netlist information.
	"prim" is an abbreviation for "primitive", a type of node (the other type
		of node is the facet instance).
	"serpentine" describes a transistor with a complex gate path, winding its way through
		the active region.  Thus, it looks like a serpent.
	"arch" is an abbreviation for Architecture, and is used to describe FGPAs.
	"pip" is another FPGA term: it is a "program point" on the chip.
	"block" refers to a main section of a FPGA chip, similar to a "cell" or "facet".
		The "block net" is a network in a block.  A "block net segment" is a part of that network.
	"well" refers to an implant layer on a chip (p-well and n-well are the two types).
	"negated arc" is one with a negating bubble on it.
	"reversed arc" is one where the head and tail are swapped.

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