It is not necessary to rebuild Electric from the source code because the downloads are ready to run.
For people who wish to explore the source code, this section describes some of the necessary steps.
The first step in building the source code is to extract it from the ".jar" file.
To do this, place the ".jar" file in its own directory, change to that directory, and run the following command:
jar xf electric-version.jar
(Windows users may want to install "cygwin," from www.cygwin.com,
in order to more easily run "jar" and other commands.)
The "jar" command will create a number of files and folders on your disk:
- com is a folder with all of the source code.
- packaging is a folder with support files for building Electric.
- META-INF is a support folder used when running the ".jar" file and can be deleted.
- build.xml is an Ant script for building Electric.
- ChangeLog.txt is a detailed list of changes to Electric.
- COPYING.txt is the GNU copyright document that applies to your use of Electric.
- README.txt is a file of notes about Electric.
The next step is to get a version of Java that can build source code.
Although a "JRE" (Java Runtime Environment) is sufficient for running Electric,
it is not able to build the source code.
For that, you must have a "JDK" (Java Development Kit).
In addition, you may want to use an IDE (Integrated Development Environment) such as
NetBeans (at www.netbeans.org) or
Eclipse (at www.eclipse.org).
Running under Eclipse
Here are some notes about building Electric under Eclipse:
- Setup Workspace. The Workspace is a point in the file system where all source code can be found.
You can use the directory where you extracted the Electric source code, or any point above that on your disk.
- Create Project. The Project defines a single program that is being built.
Use New Project under the File menu and choose "Java Project".
Choose "Create project from existing source" and browse to the folder where the files were extracted.
Give the project a name, for example, "Electric."
- Configure Source Code. The "Source" tab of the Eclipse project settings shows the files that were discovered.
Make sure that the extracted directory is included (along with everything else under it).
- Configure Libraries. The "Libraries" tab of the Eclipse project settings lets you add other packages that may be relevant to the build.
There are no required libraries, but many optional ones
(see Section 1-5 on plug-ins).
Use the "Add External JARs" button to add any extra libraries.
- Handle Macintosh variations.
If you are building on a Macintosh, no changes are needed.
If you are not building on a Macintosh, you must decide whether or not you want the code that you produce to
also run on a Macintosh.
If you do not care about being able to run on a Macintosh, remove the source code module
"com.sun.electric.tool.user.MacOSXInterface.java" (which probably has a red "X" next to it indicating that there
are errors in the file).
If you want the final code to be able to run on all platforms,
download the stub package "AppleJavaExtensions.jar" from
developer.apple.com/samplecode/AppleJavaExtensions
and add this as an external JAR file.
- Run Electric. Use the Run... command (under the Run menu)
to create a run configuration.
Under the "Main" tab of the run-configuration dialog,
give the configuration a name (for example, "Electric"),
set the Project to match the one that you have created,
and set the "Main class" to be "com.sun.electric.Launcher".
Under the "Arguments" section of the dialog,
it is a good idea to increase Electric's memory size by entering "-mx1000m" under "VM arguments".
Using Ant
"Ant" is a scripting system for building Java programs,
and Electric comes with an Ant script file called "build.xml".
Once the source code is extracted, you can build Electric simply by typing Ant commands.
The Ant target "runFromBin" will build and run Electric.
The Ant target "jarForGNUBinary" will build a new ".jar" file from the source code.
Note that when using Ant, there are some Macintosh vs. non-Macintosh issues to consider.
- Build on a Macintosh
The easiest thing to do is to remove references to "AppleJavaExtensions.jar" from the Ant script.
This package is a collection of "stubs" to replace Macintosh functions that are unavailable elsewhere.
You can also build a native "App" by running the Ant target "mac-app".
Macintosh computers must be running OS 10.3 or later.
- Build on non-Macintosh
If you are building Electric on and for a non-Macintosh platform,
remove references to "AppleJavaExtensions.jar" from the Ant script.
Also, remove the module "com.sun.electric.MacOSXInterface.java".
It is sufficient to delete this module, because Electric automatically
detects its presence and is able to run without it.
- Build on non-Macintosh, to run on all platforms
To build Electric so that it can run on all platforms, Macintosh and other,
you will need to keep the module "com.sun.electric.MacOSXInterface.java".
However, in order to build it, you will need the stub package "AppleJavaExtensions.jar".
The package can be downloaded from Apple at
developer.apple.com/samplecode/AppleJavaExtensions.