Author: Jacob Levy

Installing and Building e4Graph

This page explains the version numbering scheme for e4Graph, lists the package dependencies it has, and provides pointers to detailed instructions on how to build and install e4Graph on a wide variety of OSes.

- [*] e4Graph Distributions and Versioning Method.
- [*] Packages Used by e4Graph.
- [*] Structure of e4Graph Distributions.
- [*] How to Build and Install e4Graph on Unix.
- [*] How to Build and Install e4Graph on Win32.
- [*] How to Build and Install e4Graph on MacOS X 10.

Distributions

The e4Graph package is distributed as source code and as prebuilt binaries for several platforms. The distributions are packaged as a ZIP file for Win32 platforms and as a gzipped tar file for Unix and MacOS X 10 platforms.

The current release of e4Graph is numbered 1.0a11, the eleventh Alpha release of version 1.0.

The 1.0a11 release is not feature complete, hence it is called an Alpha.

Please retrieve the distributions from here.

Versioning Scheme

The versioning scheme works as follows:

- The first number is the major version. All versions with the same major number use compatible data structures and file formats. Versions with different major version numbers may use incompatible data structures and file formats. Generally the data files from a higher version number are unreadable by a version with a lower major version number. Sometimes it is possible for a version with a higher major version number to read data files produced by a version with a lower major version number. If this is impossible, the newer version of e4Graph will provide conversion routines for bringing the old data files up to the new format.
- The second number is the minor version. New APIs may be introduced between minor version numbers, and data files produced by newer minor versions can be read by older minor versions as long as they both have the same major version number.
- Optionally there may be either a third number indicating a patch level, or a string starting with the letter a (for Alpha releases) or b (for Beta releases) followed by a number indicating the sequence number for the Alpha or Beta release.

Based on this numbering scheme, the current version (1.0a11) is the sixth Alpha version of the first major release of e4Graph. When the first version reaches maturity, its number will be promoted to 1.0.

The distributions, both binary and source, unpack into directories that reflect the name and numbering of the release they represent. For example, the second Beta of version 2.3 unpacks into a directory named e4graph-2.3b2.

[back to top of page]

Dependencies on Other Packages

To use e4Graph in your projects, you can choose to use either a prebuilt e4Graph distribution, if one is available for your platform, or build e4Graph from source. Either way, you need to install and possibly build several other packages that e4Graph depends on. The e4Graph package depends on these other packages:

Package | Get it from here: | Required/Optional
Metakit 2.4.9.2 (source) | http://www.equi4.com/pub/mk/metakit-2.4.9.2.tar.gz | Required
Tcl 8.4.4 (source) | http://prdownloads.sourceforge.net/tcl/tcl8.4.4-src.tar.gz?download | Optional
Tcl 8.4.4 (prebuilt for Win32) | http://downloads.activestate.com/ActiveTcl/Windows/8.4.4/ActiveTcl8.4.4.0-win32-ix86.exe | Optional
Expat 1.95.7 (source) | http://prdownloads.sourceforge.net/expat/expat-1.95.7.tar.gz?download | Optional
Expat 1.95.7 (prebuilt for Win32) | http://prdownloads.sourceforge.net/expat/expat_win32bin_1_95_7.exe?download | Optional
Python 2.2.3 (source) | http://www.python.org/ftp/python/2.2.3/Python-2.2.3.tgz | Optional
Python 2.2.3 (prebuilt for Win32) | http://www.python.org/ftp/python/2.2.3/Python-2.2.3.exe | Optional
Java (prebuilt only) | http://java.sun.com | Optional

NOTES:

To unpack the source releases on Unix, you need gzip and tar. Some versions of tar understand the -z which obviates the need for invoking gzip. On Win32 or MacOS X use winzip or a command line version of zip respectively. Most implementations of zip understand archives compressed with gzip and will be able to decompress and unpack them.

We recommend use of Metakit 2.4.9.2 with e4Graph. All older versions of Metakit up to 2.4.8 are known to work well with e4Graph. As noted above, only the Metakit 2.4.9.2 package is a required dependency. The others are optional, and are required only for building extensions to e4Graph such as a Tcl or Python binding, or support for XML input and output. We suggest that on Windows, you use the prebuilt packages on which you will depend, to simplify the effort required to get started using e4Graph. However, Metakit does not provide a prebuilt package for Windows, so you have to build it from source there also. On Unix, the best option is to build each package from the sources, and then to use it. For each component that e4Graph depends on, you only need either the binary or source distribution of that component.

We recommend use of Tcl 8.4.4 with e4Graph. Do not use Tcl 8.4.3, it has a known bug (Tcl Bug #726018, see here) that prevents the Tcl binding for e4Graph from working. Tcl 8.4.2 and older versions up to Tcl 8.1 also work fine, because they do not have this bug.

We recommend use of Expat 1.95.7 with e4Graph. Do not use Expat 1.95.6, it has build problems with some widely used compilers such as GCC 2.95.7. Expat 1.95.5 and older versions are also suitable for use with e4Graph.

We recommend use of Python 2.2.3 with e4Graph. All Python 2.2 releases work well with e4Graph's Python binding. Python 2.1 releases do not work properly, so we recommend use of the latest release of Python 2.2, currently Python 2.2.3.

All versions of Java from Java 1.1 to Java 1.4.2 are known to work with e4Graph. The Java binding of e4Graph depends on a very basic subset of JNI (the Java Native Interface).

[back to top of page]

Structure of e4Graph Distributions

There are two kinds of distributions of e4Graph: source and binary.

Structure of the Source Distributions

The source distributions contain the following directories:

- The top-level directory contains the files README, INSTALL, readme.html and changes. Its name reflects the release that this distribution represents; for example e4graph-1.3a2 is the second Alpha of release 1.3.
- The docs sub-directory contains documentation for all sub-packages of e4Graph.
- The all sub-directory is from where the e4Graph source code is built. It contains a VC++ 6.0 project file and the necessary files to create a customized Makefile for Unix and MacOS X systems. See above for how to build e4Graph on each system.
- The main sub-directory contains the basic facilities of e4Graph.
- The test sub-directory contains source code for building an exhaustive tester for the e4Graph library.
- The tcl sub-directory contains source code for building the Tcl binding of e4Graph.
- The python sub-directory contains source code for building the Python binding of e4Graph.
The xml sub-directory contains source code for building the XML facilities for e4Graph.
- The t4xml sub-directory contains source code for building an extension that allows use of the XML facilities for e4Graph together with the Tcl binding.
- The java sub-directory contains source code, header files, class files and native C++ source code files. These files allow e4Graph to be used from Java programs.

When you build e4Graph from source, an additional directory named builds may also appear. You can safely remove this directory once you have built and installed e4Graph.

Structure of the Prebuilt Distributions

The prebuilt distributions contain prebuilt libraries for all sub-packages provided by e4Graph, header files, documentation and for the Windows release also the export libraries. Prebuilt distributions have the following directory structure:

- The top-level directory contains the files README, INSTALL, readme.html and changes. The name of this directory reflects the version of e4Graph which this release represents; e.g. e4graph-1.2b3 is the third Beta of release 1.2.
- include contains header files for all sub-packages provided by e4Graph.
- docs contains documentation for all sub-packages provided by e4Graph, including this document.
- lib contains shared objects: DLLs in the Windows binary release, files with an .so extension on Unix, and files with a .dylib extension on MacOS X 10
- exp contains export libraries in the Windows binary release, and is present only in the Windows binary release.

[back to top of page]

Structure of e4Graph Build Environment

If you intend to build e4Graph from source, you should arrange to install all packages on which e4Graph depends so that the e4Graph build can find them. If you intend to build these dependent packages from source, you should put their source code in directories that are siblings of the top-level e4Graph source directory. For example, if you intend to build e4Graph with Tcl support, and you intend to build Tcl from source, you should create the tcl source directory as a sibling of the e4Graph source directory.

On Unix and MacOS X, you will need GNU make and the m4 macro processor. I have not encountered a Unix system yet where these tools were not preinstalled.

On Unix and MacOS X, if your dependent packages are prebuilt, install them in standard locations for each system. The e4Graph build system will find and use them.

On Win32, if your dependent packages are prebuilt, install them as sibling directories of the main e4Graph source directory. For example, if you intend to build e4Graph with python support, and you use the prebuilt binary Python distribution, install it so that the Python-2.2.3 directory is a sibling of the main e4Graph source directory.

There are no instructions here on how to install and/or build each dependent package. Instead, look at the provided documentation for each dependent package that you will use.

[back to top of page]