1---------------- This is Electric, Version 7.00 ---------------- 2 3This README file contains installation instructions for all 3 of the platforms 4supported by Electric: UNIX, Macintosh, and Windows. 5 6---------------- Requirements: 7 8UNIX: 9 Electric runs on most UNIX variants, including SunOS, Solaris, BSD, HPUX, AIX, 10 and (of course) GNU/Linux. 11 12Macintosh: 13 Macintosh users must run System 7 or later. Electric compiles best under 14 Metrowerks, although it has been built with MPW and THINK_C. 15 16Windows: 17 Electric runs under Windows 95/98/ME, NT 4.0, 2000, or XP. 18 The system compiles with Visual C++ 5.0 or later. 19 20---------------- Distribution: 21 22The Electric distribution is a single file in UNIX "tar" format, GNU-zipped 23(see http://www.gzip.org for more information). 24> Macintosh users: You will have to locate a program that can read this 25 file ("MacGzip", available at www.gzip.org, will unzip the file; MacTar, 26 available at www.strout.net/macsoft/mactar, will extract the files). 27 If you use some other method of extraction, beware of Macintosh line-feed 28 conventions, which are different from those on other operating systems. 29 You may need to set the "Convert Newlines" option in the "tar" program 30 before extracting the files. Also, if you use "Internet Config", check 31 to be sure its "Change Newline" setting set. 32 To be sure that the extraction has worked properly, examine the file "cadrc", 33 which is at the top level (just inside of the "Electric" directory). 34 This file should have about 10 lines of text. If the file appears as a 35 single line, or if there are spurious unprintable characters at the start 36 or end of each line, then the text conversion has been done incorrectly. 37> Windows users: You can use "WinZip" to extract this file. Make sure that 38 the "TAR File Smart CR/LF Conversion" box is checked in the "Configuration..." 39 dialog of the "Options" menu. 40 41When extracted, there will be a directory called "electric-VERSION" (where 42the VERSION is the particular version number). This directory will have 43four subdirectories: "src", "lib", "examples", and "html". 44 45The "src" directory contains the source code. It is hierarchically 46organized by function. 47 48The "lib" directory has library files (more on that later). 49 50The "examples" directory has some sample files. 51 52The "html" directory contains one subdirectory, "manual", which is 53the user's manual in HTML format. To see the document, point your 54browser to the file "index.html" inside of the "manual" directory. 55 56---------------- Building (UNIX): 57 58To configure for your system, go into the top-level directory and type: 59 ./configure 60This will examine the system and create a file called "Makefile". 61To build Electric you now only need to use type: 62 make 63This compiles Electric and creates the executable file "electric" 64in the top level directory. 65Type "./electric" to run the system. 66 67On Solaris, when using the Forte C compiler, uncomment the line that starts with "FORTECFLAGS" 68in "Makefile". 69 70Electric has the option of using TrueType fonts. If you want this, follow these instructions: 71> Obtain Rainer Menzner's "T1Lib" here: 72 ftp://sunsite.unc.edu/pub/Linux/libs/graphics 73 Once you have it, unpack it (it will create a directory called "T1-1.1.0"), go into that 74 directory, type "./configure" and then type "make". You can then install with "make install". 75> Now go to the Electric directory and edit the "Makefile". Near the top are comments labeled 76 "T1LIB TRUETYPE". Uncomment the two lines (remove the "#" from the beginning of the lines) 77 and change the lines so that they point into the T1Lib folder that you have just installed. 78 For example, if the T1Lib libraries installed into "/usr/local/lib" and the T1Lib headers 79 installed into "/usr/local/include", then you want these lines to read: 80 TRUETYPE_LIBS = /usr/local/lib/libt1.a 81 TRUETYPECFLAGS = -DTRUETYPE=1 -I/usr/local/include 82> Next (this is the most painful part), you have to set the environment variable T1LIB_CONFIG 83 to point to the file "t1lib.config". This file may be installed in "/usr/local/share/t1lib". 84 There will certainly be a copy in the "examples" folder of the distribution. The catch here is that 85 this file has relative path names in it which must be converted to absolute. So, if you have 86 extracted the T1Lib distribution into the folder "/home/strubin/T1-1.1.0", then the file should 87 look like this: 88 This is a configuration file for t1lib 89 FONTDATABASE=/home/strubin/T1-1.1.0/examples/FontDataBase 90 ENCODING=/home/strubin/T1-1.1.0/Fonts/enc:. 91 AFM=/home/strubin/T1-1.1.0/Fonts/afm:. 92 TYPE1=/home/strubin/T1-1.1.0/Fonts/type1:. 93> Finally, rebuild Electric with the TrueType library. When you run it, you will get a warning if 94 any of the TrueType initialization fails (in which case it will revert to the non-TrueType code). 95 Otherwise, you have it. 96> Note that Electric uses the first font in the database by default. To change the font that 97 Electric uses, set the environment variable ELECTRIC_TRUETYPE_FONT to the desired font name. 98 You can see a list of available fonts by setting this environment variable to an unknown name, 99 in which case Electric will show all fonts in its error message. 100 101To add Java, follow these instructions: 102> Download the Java Development Kit (JDK) from http://java.sun.com. Install it. 103 For the purposes of these instructions, assume that it is installed into 104 /usr/java/jdk 105 If you install it elsewhere, adjust these instructions accordingly. 106> After configuration, but before making Electric, edit the "Makefile" and 107 uncomment the lines near the top that enable Java. 108 Change the definition of LANGJAVA_DIR to point to the installed JDK location. 109> On Solaris, add this string to the environment variable LD_LIBRARY_PATH: 110 :/usr/java/jdk/jre/lib/sparc:/usr/java/jdk/jre/lib/sparc/classic:/usr/java/jdk/jre/lib/sparc/native_threads 111> On GNU/Linux, add this string to the environment variable LD_LIBRARY_PATH: 112 :/usr/java/jdk/jre/lib/i386:/usr/java/jdk/jre/lib/i386/classic:/usr/java/jdk/jre/lib/i386/native_threads 113> Be sure to export "LD_LIBRARY_PATH" if your shell requires it. 114 115To add the TCL interpreter, download ActiveTcl from "http://www.tcl.tk" and install it. 116Then edit "Makefile" and you will find the instructions necessary to enable the interpreter. 117 118---------------- Building (Macintosh): 119 120For System 7, 8, and 9, there is a Metrowerks project (called "Electric.xml"). 121Run Metrowerks, import this file, and save it in the top level, 122alongside the "src" directory. Due to the size of the code that is being built, 123you may have to increase the size of the Metrowerks partition. 124 125For System 10, there are two ways to go: Qt or ProjectBuilder. Qt is the only fully-working 126solution, but unfortunately it is not free on the Macintosh (it is actually quite expensive). 127Also, you need Qt release 3.1.0 or later. 128 129To build with "Qt", use a terminal window and type "./configure" to generate a "Makefile". 130Edit the "Makefile" and switch to Qt widgets (uncomment the Qt part, comment the Motif part, 131and in the Qt section, change comments to switch to "Qt on Macintosh"). 132 133The alternative to Qt is ProjectBuilder (the files "Electric.pbproj" and "English.lproj" are included). 134Note that the ProjectBuilder solution is not fully debugged, so use with care. 135 136After compilation, you will have the application "Electric". Double-click it to run the system. 137 138To add the TCL interpreter, follow these instructions: 139> Download ActiveTcl from "http://www.tcl.tk" and install it. 140> If using Qt/System 10, edit "Makefile" and add TCL. Otherwise: 141 > In the compiler, add an include path to the installed TCL "include" directory. 142 > Also in the compiler, add the appropriate TCL library to the project. 143> Edit the appropriate "mac" include file in "src/include" (for example, "macsfsheaders.h") 144 and uncomment the definition of "FORCETCL". 145 146To add a Java interpreter (System 10 only) follow these instructions: 147> Download Java from "http://java.sun.com" and install it. 148> If using Qt, edit "Makefile" and add Java. Otherwise: 149 > In the compiler, add an include path to the installed Java "include" directory. 150 > Also in the compiler, add the appropriate Java library to the project. 151> Edit the appropriate "mac" include file in "src/include" (for example, "macsfsheaders.h") 152 and uncomment the definition of "FORCEJAVA". 153 154---------------- Building (Windows): 155 156For users of Visual C++ 5.0 or 6.0, open the workspace file "Electric.dsw" 157(both it and the associated file "Electric.dsp" are in the top level, alongside 158the "src" directory). Visual Studio .NET users can open "Electric.vcproj". 159If you have trouble with any of these files, use the MAKE file 160"Electric.mak". Compile Electric. This will create a new directory in the 161top level called "Debug", which will contain all of the object files. 162 163Inside of the "Debug" directory, you will find the executable file "Electric". 164Move this file out of the "Debug" directory and place it in the top-level 165directory. Double-click the "Electric" executable to run the system. 166 167To add the Java interpreter, follow these instructions: 168> Download the Java Development Kit (JDK) from http://java.sun.com. Install it. 169 The standard location is "C:\Program Files\JavaSDK" (or whatever the version is), and this path 170 will be used here. If you install it elsewhere, adjust these instructions accordingly. 171> Edit the environment variables in the "System" Control Panel. 172 On some systems, you click on the "Environment" tab; on others, click on the "Advanced" 173 tab and then click the "Environment Variables" button. 174 Under "System variables", select "Path" and in the "Value:" area, 175 add this string to the end: 176 ;C:\Program Files\JavaSDK\jre\bin\classic;C:\Program Files\JavaSDK\bin 177 On some newer versions of the Java Development Kit, you may also have to include this path: 178 ;<CODE>;C:\Program Files\JavaSDK\bin\client 179 On Windows 95 and Windows 98 systems, you may have to edit C:\AUTOEXE.BAT and append 180 this to the PATH variable. You must restart your computer after making this change. 181> In Visual C++ 5.0 or 6.0, use the "Settings" command of the "Project" menu. Select the 182 "C/C++" tab and the "Preprocessor" category. In the "Preprocessor definitions" 183 area, add this to the end: 184 ,FORCEJAVA=1 185 In the "Additional include directories" area add this to the end: 186 ,C:\Program Files\JavaSDK\include,C:\Program Files\JavaSDK\include\win32 187 Select the "Link" tab and the "General" category. In the "Object/library modules" 188 area, enter this: 189 jvm.lib 190 Select the "Link" tab and the "Input" category. In the "Additional library path" 191 area, enter this: 192 C:\Program Files\JavaSDK\lib 193> In Visual Studio .NET, right-click on the "Electric" solution and choose "Properties". 194 Select "C/C++" on the left and choose the "General" category under it. 195 In the "Additional Include Directories" area, add this to the end: 196 ;C:\Program Files\JavaSDK\include,C:\Program Files\JavaSDK\include\win32 197 Next choose the "Preprocessor" category of "C/C++" and in the "Preprocessor Definitions" 198 area add this to the end: 199 ;FORCEJAVA=1 200 Select "Linker" on the left and choose the "General" category under it. 201 In the "Additional Library Directories" area, enter this: 202 ;C:\Program Files\JavaSDK\lib 203 Next choose the "Input" category of "Linker" and in the "Additional Dependencies" area 204 enter this: 205 jvm.lib 206> Once Java is installed, you must compile the ROM generator. In a command window, change 207 directories to the "lib\java" directory and run the command: 208 javac romgen.java 209 210To add the TCL interpreter, follow these instructions: 211> Download ActiveTcl from "http://www.tcl.tk" and install it. 212> In the compiler, edit the Project Settings and find the field "Additional include directories" 213 (under "C/C++"). Add a new path to the installed TCL Includes 214 (typically "C:\Program Files\Tcl\include"). 215> Also in the compiler, edit the Project Settings and find the field "Additional library path" 216 (under "Linker"). Add a new path to the installed TCL Libraries 217 (typically "C:\Program Files\Tcl\lib"). 218> Edit the file "src/include/config.h" and make sure that the constant "TCLLIBDIR" points 219 to the proper location of the initialization files ("init.tcl" and others). 220 This is typically "C:\Program Files\Tcl\lib\tcl8.3" 221 (note that each backslash is doubled in this file, and you should follow this convention). 222 223---------------- Installing: 224 225Once compiled, Electric will run properly from the directory where it was 226built. However, if you wish to install the system, you must move files 227carefully. This is because Electric makes use of a collection of "support 228files". The main support file is called "cadrc" (on UNIX, it has a dot in 229front: ".cadrc"). In addition, Electric needs to find the "lib" and "html" 230directories. If these support files cannot be found, Electric will not be 231able to initialize its graphical user interface (just type "-quit" to exit 232the program if this happens). 233 234On Windows and the Macintosh, it is sufficient to move the support files, 235along with the executable, to a public location. Then make an alias 236(shortcut) to the executable and place that anywhere you like. When the 237alias is run, the directory with the executable will become the current 238directory, and all of the needed support files will be found. 239 240On UNIX, the "make install" command will place the executable and the support 241files in a public location, but they may not be together. For example, it is 242not uncommon for the executable to be placed in "/usr/local/bin", but the 243support files in "/usr/local/lib/electric". When this happens, the executable 244needs to know where the support files are located. There are three ways to 245do this: 246 (1) You can set the ELECTRIC_LIBDIR environment variable to point to the 247 location of the support files. 248 (2) You can change the #define of "LIBDIR" in "src/include/config.h" to point 249 to the location of the support files. 250 (3) You can keep a local copy of ".cadrc" file (this file can be in your 251 home directory or in the current directory). Inside of the ".cadrc" 252 file, change the "electric library default-path" command to point to the 253 remaining support files (the "lib" and "html" directories). 254 255UNIX systems also offer "make install.html" which installs the online manual 256into a public place (typically "/usr/local/share/doc/electric/html"). Be sure 257that the #define of "DOCDIR" in "src/include/config.h" agrees with this path 258or else the "See Manual" command will not work. 259 260---------- Additional Details (UNIX): 261 262Electric uses "widget libraries" to control the windows on the display. 263The default widget library is Motif (see http://www.opennc.org/openmotif). 264You can use LessTif (see http://www.lesstif.org), but has some bugs (you will 265have to remove the "XtDestroyWidget()" call in "DiaDoneDialog()"). 266You can also use Qt (see http://www.trolltech.com) by editing the "Makefile" 267after running "configure" (comments near the top explain what to do). 268When installing these packages on your system, be sure to get both the libraries 269and the "devel" package that contains the compiler header files. Also note that 270many systems use shared libraries for these widget packages, and this may require 271some additional steps when installing. This is because the libraries get 272installed in a place that the shared library system doesn't know about. 273If you have superuser access, you can use "ldconfig" to tell the system where 274to find the libraries. Otherwise, you can use the LD_LIBRARY_PATH environment 275variable (on AIX use LIBPATH and on HP-UP use SHLIB_PATH). This variable is 276a colon-separated list of paths to be searched for shared libraries. For example, 277this setting will work on many systems: 278 LD_LIBRARY_PATH = /usr/X11R6/lib/ 279 export LD_LIBRARY_PATH 280 281Electric has two ways to control the display. By default, the system runs 282on any depth monitor, but is slow on older machines and must be run 283locally (that is, the client and the server must be on the same computer). 284The alternate method of display is faster and can run over the network, 285but it can only support displays that are set to 8bpp (8 bits per pixel). 286In addition, this alternate method will suffer from "colormap flashing" 287when the cursor enters and leaves the Electric windows. To switch to 288this alternate method, edit the "Makefile" after running "configure" 289(comments near the top explain what to do). Note also that Motif and 290Lesstif do not work well with this alternate display method, so you will 291also have to switch to using the Athena widgets. 292 293Electric makes use of external programs for simulation. The location of 294these programs can be found in the various #defines in the file 295"src/include/config.h", which can be overridden with the following 296variables in your ".cshrc" file: 297 setenv ELECTRIC_SPICELOC /usr/local/bin/spice 298 setenv ELECTRIC_ESIMLOC /usr/local/bin/esim 299 setenv ELECTRIC_RSIMLOC /usr/local/bin/rsim 300 setenv ELECTRIC_PRESIMLOC /usr/local/bin/presim 301 setenv ELECTRIC_RNLLOC /usr/local/bin/rnl 302 303There are two command-line arguments that can be given which will control 304the X-windows display. If you use the "-f" option, Electric 305will start with a full-screen graphics window. If you use the 306"-geom WxH+X+Y", it will set the graphics window to be "W" wide, 307"H" high, and with its corner at (X, Y). Additional X-Windows options 308can be typed into the file ".Xdefaults". The resources "Electric.font0" 309through "Electric.font8" set the font to use for point sizes 4, 6, 8, 10, 31012, 14, 16, 18, and 20. The resource "Electric.fontmenu" controls the 311text used in the component menu, and the resource "Electric.fontedit" 312controls the text used in the text editor. Here is a sample line from 313the file: 314 Electric.font5: -misc-fixed-medium-r-normal-*-*-140-*-*-*-*-*-* 315To see what all of these fonts look like, load the library "samples.txt" 316(with the "Readable Dump" subcommand of the "Import" command of the "File" 317menu) and edit the cell "tech-Artwork". The top part of the cell shows 318text in sizes 4 through 20. 319 320---------- Additional Details (Windows): 321 322Electric must be run with the Display Settings set to "65536 Colors" or 323"True Color". Anything less will cause the colors to appear wrong. 324 325If you have trouble reading the cursor or icon files (".cur" or ".ico") you can 326find a text-encoded version of these binary files in \src\graph\graphpc.uue. 327Use "WinZip" to extract the files into the same directory. 328 329---------- Internationalizing Electric: 330 331Electric is able to interact in other languages than English. 332Currently, there is a French translation. 333 334To use this facility on GNU/Linux, edit the "Makefile" and follow the instructions for 335"Internationalization". You must then set the environment variable "LANGUAGE" to the 336proper language ("fr" for French). On Solaris, you must also set the environment variable 337"NLSPATH" to point to Electric's "lib/international" directory. 338 339To use this facility on Windows or the Macintosh, you must obtain the Static Free Software 340extras and build the "International" version of Electric. Before compiling, set the 341desired language by changing the routine "elanguage()" (on Windows, it is in 342"graph/graphpccode.cpp"; on the Macintosh it is in "graph/graphmac.c"). 343 344At any time, you can disable the foreign language and return to English by moving the 345translation files. These files are in the "lib/international" folder, with a subfolder 346that has the language name (for example, French translations are in "lib/international/fr"). 347Beneath that is a folder called "LC_MESSAGES" and inside of that are the translation files. 348 349 350If you wish to translate Electric yourself, look in the appropriate folder for that 351language. There you will find two types files: the translation file and its binary equivalent. 352The binary file is named "electric.mo" and the translation file ends in the language name 353("electric.fr" for French). 354Note also that the Macintosh uses different characters than UNIX and Windows, so there 355will also be a second set of files ("macelectric.mo" and "macelectric.fr"). 356 357When repairing or augmenting a translation, edit the appropriate translation file. It must 358then be converted to/from Macintosh encoding, and then both files must be converted to the 359binary format. 360 361When creating a new translation, you can start with the file "lib/international/messages.po" 362which has all of Electric's messages but no translations. Rename this file appropriately 363and edit it. 364 365 366If you are using GNU/Linux, you can edit this file with EMACS and use "po-mode", which 367assists in translation. If you do not have access to this, you can use Electric's built-in 368translation editor. Use the "General Options" subcommand of the "User Interface" command of 369the "Info" menu; click "Advanced" and then click "Language Translation". 370 371 372If you edit the translation file by hand, you will see groups of lines that look like this: 373 #: src/usr/usrcomtv.c:233 374 #, c-format 375 msgid "Technology %s is still in use" 376 msgstr "" 377The line that begins with "#:" is the location in the source code of the string. 378The line that begins with "#," contains flags that are unimportant. 379The line that begins with "msgid" is the string in English. 380The line that begins with "msgstr" is an empty string, and it is where you type the translation. 381 382 383In some cases, the first line is many lines (if the string appears in many places in the code). 384For example: 385 #: src/io/iocifin.c:208 src/io/iodefi.c:117 src/io/iodxf.c:487 386 #: src/io/ioedifi.c:810 src/io/iogdsi.c:1955 src/io/iolefi.c:113 387 #: src/io/iosdfi.c:157 src/io/iosuei.c:238 src/io/iotexti.c:375 388 #: src/io/iovhdl.c:57 389 #, c-format 390 msgid "File %s not found" 391 msgstr "" 392 393 394Be aware that many of these strings have formatting control in them. An example is shown above. 395The string is "File %s not found", and the "%s" part of the string will be replaced with the 396name of a file. When you translate it, leave the "%s" so the substitution will work. 397In French, that string will be "Fichier %s introuvable". 398 399The common substitutions that you will find are "%s" for string and "%d" or "%ld" for numbers. 400There might even be a substitution that has digits in it such as "%3d" Be warned that the 401order of the substitutions must be preserved, and so must the exact sequence of characters in 402the substitution. For example, the string: 403 "Unknown section name (%s) at line %ld" 404has two substitutions, and the translation must have the "%s" before the "%ld" 405(even if the sentence is awkward). 406 407 408At some point in the translation process, you may see the keyword "fuzzy" on the flags line 409(the line that begins with "#,"). This indicates that some program guessed at the translation 410because of similarity. No human did a translation for this string, and it may be wrong. 411Verify the translation and remove the word "fuzzy". 412 413 414Some lines begin with "#~", for example: 415 #~ msgid "File Format:" 416 #~ msgstr "Format fichier" 417This indicates messages that were translated but are no longer used in Electric. The 418translations are kept around in case the messages reappear in a later version of Electric. 419None of the lines that begin with "#~" should require translation, so you can safely ignore them. 420 421 422Some translations span two lines, for example: 423 #: src/db/dbchange.c:1114 424 #, c-format 425 msgid "Warning: Could not find index %ld of attribute %s on object %s" 426 msgstr "" 427 " Attention: Impossible de trouver l'index %ld de l'attribut %s de l'objet %s" 428This is standard format for the translation package. It is permitted for the translation 429to span more than 1 line in the file, but in all cases these strings are concatenated together 430to form 1 string. 431 432 433Sometimes the English contains the character "&" where it makes no sense (for example, the 434word "P&rint"). These are markers for "quick keys" in pulldown menus. When the "&" is in 435front of the letter "X", it means that typing "X" will invoke that menu entry. However, each 436menu must have the "&" in front of a unique letter. And since you cannot tell, when you are 437translating, which strings are grouped into a single menu, it is best if you simply ignore the 438"&" character and translate the string without it. Note, however, that the character should 439be preserved where it makes sense, such as in the expression "black&white". 440 441 442An alternate "quick key" marker is the string "/X" at the end of a phrase. This indicates that 443the Control-X key will invoke that menu entry. These letters are not part of the phrase, and 444so they do not need to be translated (just left alone). Ambitious translators will want to 445rearrange these control-keys so that they make sense for the language. 446 447 448Some phrases end with an elipsis ("..."). These are used in pulldown menu entries that 449invoke dialogs. Keep the elipses when translating. 450 451 452Here are some terms that may be confusing: 453 "jog" describes a wire that makes two bends. Like a "Z", it turns in one direction 454 and then back again. Also called a "zig-zag" in English. 455 "R-Tree" is a technical term...you can translate "tree" (as in "tree structure", 456 something that branches), and leave the letter "R". 457 "high" refers to a signal level (high voltage, low voltage). 458 "trans" is an abbreviation for "transistor" 459 "diff" is an abbreviation for "diffusion" (the active layer on an IC). 460 "gate" is the polysilicon layer on a chip that "gates" (controls) the transistor. 461 "deck" refers to a disk file with netlist information. 462 "prim" is an abbreviation for "primitive", a type of node (the other type 463 of node is the cell instance). 464 "serpentine" describes a transistor with a complex gate path, winding its way through 465 the active region. Thus, it looks like a serpent. 466 "arch" is an abbreviation for Architecture, and is used to describe FGPAs. 467 "pip" is another FPGA term: it is a "program point" on the chip. 468 "block" refers to a main section of a FPGA chip, similar to a "cell". 469 The "block net" is a network in a block. A "block net segment" is a part of that network. 470 "well" refers to an implant layer on a chip (p-well and n-well are the two types). 471 "negated arc" is one with a negating bubble on it. 472 "reversed arc" is one where the head and tail are swapped. 473 474---------------- Discussion: 475 476There are two GNU mailing lists devoted to Electric: 477 bug-gnu-electric (subscribe at http://mail.gnu.org/mailman/listinfo/bug-gnu-electric) 478 discuss-gnu-electric (subscribe at http://mail.gnu.org/mailman/listinfo/discuss-gnu-electric) 479 480In addition, you can send mail to: 481 info@staticfreesoft.com 482 483 484