Installing and Building e4Graph
The e4Graph package is distributed as source code and as pre-built binaries
for several platforms. The distributions are packaged as a ZIP file for
Win32 platforms and as a gzipped tar file for Unix platforms.
The current release of e4Graph is numbered 1.0a4, the fourth Alpha
release of version 1.0.
The 1.0a4 release is not feature complete, hence it is called an Alpha.
Downloading the Distributions
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.0a4) is the
fourth 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.
Dependencies on Other Packages
The e4Graph package depends on these other packages:
Using the Pre-built Distributions
Structure of the Pre-built Distributions
The pre-built distributions contain pre-built libraries for all sub-packages
provided by e4Graph, header files, documentation and for the Windows release
also the export libraries.
All pre-built distributions have the same 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.
-
The include sub-directory contains header files for all sub-packages
provided by e4Graph.
-
The docs sub-directory contains documentation for all sub-packages
provided by e4Graph.
-
The lib sub-directory contains shared objects: DLLs in the Windows
binary release and files with an .so extension on Unix.
-
The exp sub-directory contains export libraries in the Windows binary
release, and is present but empty for the Unix binary release.
Using the Pre-built Distribution on Windows
The e4Graph DLL files were compiled in release mode with Visual C++
6.0. To use this pre-built distribution of e4Graph, you need to have Visual
C++ 6.0 installed on your system. To use e4Graph in your project, do the
following:
-
You must have pre-installed binary distributions of Metakit 2.4.0 and
optionally Tcl 8.3 or later and Expat 1.95 or later. See above for how to obtain them.
-
Copy lib\e4graph.dll, lib\tgraph.dll, lib\e4xml.dll
and lib\txml.dll into a directory in your PATH variable.
-
Add the include directory to the include path of your project and
include e4graph.h in the source files of your project that need
direct access to e4Graph types and methods. If your project uses the Tcl
binding, include t4graph.h instead; it recursively includes all
the other needed files. If you intend to use the XML facilities, you can
include e4xml.h; it recursively includes e4graph.h and all
other needed files. If you intend to use both the XML facilities and the
Tcl binding, include t4xml.h.
-
Add the exp directory to the input directories for linking your
project and add e4graph.lib to the libraries to be linked with your
project. This will guarantee that the executable or DLL built by your project
will load the e4Graph DLL when it is used or executed. If you use the Tcl
binding, add tgraph.lib instead; it depends on e4graph.lib
and will recursively include it. If your project uses the XML facilities,
add e4xml.lib instead; it depends on e4graph.lib and will
recursively include it. If your project uses both the Tcl binding and XML,
add t4xml.lib instead; it depends on both tgraph.lib and
e4xml.lib
and will recursively include them.
Using the Pre-built Distributions on Unix
The e4Graph shared libraries were compiled with GCC 2.95.2 with -O4
-g. You need to have GCC and G++ 2.7.2.1 or a more recent release of GCC
and G++ installed on your system to use this pre-built release. To use
e4Graph in your project, do the following:
-
You must have pre-installed binary distributions of Metakit 2.4.0, and
optionally Tcl 8.3 and expat-1.95 or later if your project uses the Tcl
binding or the XML facilities. See above for
how to obtain them. To use the XML facilities, you must build expat from
sources. Unfortunately, the expat project currently does not ship binary
releases for Unix.
-
Copy lib/libe4graph.so, lib/libtgraph.so, lib/libe4xml.so
and lib/libtxml.so into a directory in your LD_LIBRARY_PATH environment
variable.
-
Add the include directory to the include path of your project and
include e4graph.h in the source files of your project that need
direct access to e4Graph types and methods. If your project uses the Tcl
binding, include t4graph.h instead; it recursively includes all
the other needed files. If your project uses the XML facilities, include
e4xml.h
instead; it recursively includes all other needed files. If your project
uses both the Tcl binding andthe XML facilities, include
t4xml.h
instead; it recursively includes all other depended-on headers.
-
Add -le4graph to the link line of your project. If you are building
an executable or shared object, this will guarantee that the executable
will load the e4Graph library on startup. If your project uses the Tcl
binding, add -ltgraph to the link line instead; the Tcl library
pulls in all the required shared objects. If your project uses the XML
facilities, add -le4xml to the link line instead; this library pulls
in all the other required shared objects. If your project uses both the
XML facilities and the Tcl binding, add -ltxml instead; this library
also ensures all depended-on shared objects are linked in.
Building e4Graph from a Source Distribution and Using
it
The Structure of the Source Code Distribution, Build Targets and
Depended-on Packages
The source distribution of e4Graph contains these sub-directories and
files:
-
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 systems. Building the all target builds
everything on Windows and builds the sub-packages you selected with the
invocation of configure on Unix -- see below on how to configure
e4Graph.
-
The main sub-directory contains the basic facilities of e4Graph.
Building the main target builds libe4graph.so on Unix and
e4graph.dll
on Windows. On Unix, the configure step during building the source will
automatically locate the needed header files and library for Metakit 2.4.0
if you've installed them. The configure script assumes that the revision
number of release 2.4 of Metakit is 0, hence it'll search for a directory
named metakit-2.4.0 containing the Metakit sources. You will
need to install a source distribution of Metakit-2.4.0 in a
directory named metakit-2.4.0 whose parent is the same directory
as the e4Graph source distribution. See here
for instructions for obtaining Metakit.
-
The test sub-directory contains source code for building an exhaustive
tester for the e4Graph library. Building the testcore target on
Unix builds the testcore executable.
On Win32, building the teste4dll target builds
teste4dll.exe, a dynamically linked version of the API
tester. You can also build a statically linked version by building the
teste4lib target.
-
The tcl sub-directory contains source code for building the Tcl
binding of e4Graph. Building the tgraph target builds
libtgraph.so on Unix and tgraph.dll on Windows. On Unix,
the configure step during building the source will automatically
locate the needed header files and library for Tcl 8.3 or later if
you've installed them. On Windows, you will need to install a binary
distribution of Tcl 8.3 in a directory named tcl8.3 whose
parent is the same directory as the e4Graph source distribution. See
here for instructions on how to obtain the
source code for Tcl.
-
The xml sub-directory contains source code for building the XML
facilities for e4Graph. Building the e4xml target builds libe4xml.so
on Unix and e4xml.dll on Windows. On Unix, the configure step during
building the source will automatically locate the needed header files and
library for Expat 1.95.2 if you've installed them. On Windows, you will
need to install a source distribution of Expat 1.95.2 in a directory named
expat-1.95.
whose parent is the same directory as the e4Graph source distribution.
See here for instructions on how to obtain
the source code for Expat.
-
Finally, 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. Building the t4xml target builds libtxml.so
on Unix and txml.dll on Windows. On Unix, the configure step of
building the source will automatically locate the Tcl and Expat header
files and libraries if you've installed them. On Windows you need to install
both Expat and Tcl as explained above.
Building on Win32
Assume that e4Graph sources are in c:\e4graph-1.0a4. The e4Graph
source distribution expects to find Tcl 8.3 binary distribution for Win32
systems in c:\tcl8.3 and the source distribution of Metakit 2.4.0
in c:\metakit-2.4.0. The source distribution is configured this
way because I expect that most developers wanting to use e4Graph also build
Metakit from source. Before building e4Graph, you need to build Metakit
with Visual C++ 6.0, which must be installed on your system. Build the
mksrc project. If you want to build the XML related facilities,
the source code for Expat must be installed in c:\expat-1.95.2.
You should build expat prior to using it in a build of e4Graph.
First build Metakit, and optionally Expat, from their sources. Then
open the e4Graph workspace c:\e4graph-1.0a4\all\all.dsw in Visual
C++ 6.0 and select from the following sub-projects of e4Graph (you should
use the release configuration for optimal performance and you can
use the debug configuration if you want to use the debugger to step
into e4Graph sources):
-
all builds everything below. As distributed, the project file is
set to build all in release configuration.
-
main builds just the e4Graph DLL, e4graph.dll. This depends
on Metakit 2.4.0 being installed as explained above.
-
teste4dll builds the exhaustive test binary teste4dll.exe which
exercises all facilities of the base e4Graph library.
-
tcl builds main and then the Tcl binding DLL, tgraph.dll.
This depends on Metakit 2.4.0 and Tcl 8.3 being installed.
-
xml builds main and then the XML facilities DLL,
e4xml.dll.
This depends on Metakit 2.4.0 and Expat 1.95.2 being installed as explained
above.
-
t4xml builds main, tcl and xml, and then the
XML facilities for Tcl, embodied in txml.dll. This depends on Metakit
2.4.0, Expat 1.95.2 and Tcl 8.3 being installed.
The products of these build targets are left in c:\e4graph-1.0a4\builds\win32\.
To learn how to use the e4Graph sub-packages you just built in your own
projects, read this.
Building on Unix
Assume that the e4Graph sources are in /home/user/e4graph-1.0a4.
The e4Graph source distribution configure utility automatically
figures out where you've installed the needed header files for Metakit,
and optionally Tcl and Expat. The configure script looks for Metakit, Tcl
and Expat in /home/user/metakit-2.4.0, /home/user/tcl8.3/
and /home/user/expat-1.95.2 and in several system wide directories.
You must first build and install Metakit and optionally Tcl and Expat
with GCC and G++ 2.95.2 or a later version. Then change directory to /home/user/e4graph-1.0a4/all
and invoke ./configure with the appropriate flags for your situation:
-
Specify --enable-tcl if you want to create a Makefile that builds
the Tcl binding.
-
Specify --enable-xml if you want to create a Makefile that builds
the XML facilities.
-
If you specify both, configure will create a Makefile that builds
the Tcl binding, the XML facilities and the needed extension to use the
XML facilities in the Tcl binding.
-
Specify --with-metakit=<dir> if you want to specify which Metakit
distribution to use.
-
Specify --with-tcl=<dir> if you want to specify which Tcl distribution
to use.
-
Specify --with-expat=<dir> if you want to specify which Expat
distribution to use.
-
Specify --prefix=<dir> if you want to specify the root directory
where sub-packages of e4Graph will be installed. The default is /usr/local;
header files are installed in /usr/local/include and libraries go
into /usr/local/lib.
-
Specify --help to see what options, including the above, are supported
by configure.
-
Specify --with-release=<file-name> to create a Makefile that
will build a release of e4Graph. The release file will be deposited in
the /home/user/e4graph-1.0a4/all directory. If you specify --with-release,
a Makefile will be created that builds all sub-packages when make all is
invoked -- it implies --with-tcl and --with-xml. The specified
file-name
should not have a directory prefix or an archive or compression-related
extension (e.g. no .tar and no .Z or .gz). This flag
is intended for the maintainers of e4Graph or for those who want to repackage
e4Graph as part of their own projects. The default value of this flag,
if not specified, is --with-release=e4graph.
Then invoke make with the target you want to build:
-
Make all to build all the sub-packages of e4Graph you selected when
you invoked configure.
-
Make install to build and install all the sub-packages of e4Graph
you selected when you invoked configure.
-
Make core to build just the core e4Graph library,
libe4graph.so.
-
Make testcore to build core and the exhaustive test facility,
the testcore executable.
-
Make tcl to build core and the Tcl binding to e4Graph,
libtgraph.so.
-
Make xml to build core and the XML facilities,
libe4xml.so.
-
Make t4xml to build core, xml and tcl, and
the facilities enabling use of the XML capabilities in the Tcl binding,
libtxml.so.
-
Make release to build a release in the file
file-name-version.tar.gz where file-name
was specified as the parameter of the --with-release
flag to configure. This target is intended for the maintainers of
the e4Graph package or for those who want to repackage e4Graph as part
of their own projects. Suppose you specified --with-release=mye4graph
to configure and the current version of e4Graph is 1.3b2; then the
release file deposited in the all sub-directory will be named
mye4graph-1.3b2.tar.gz.
Read this section to learn how to use the e4Graph
sub-packages you just built in your own projects. Invoking make install
will do the necessary work for you automatically, according to the parameters
you selected when you invoked configure.
If You Encounter Problems...
If you have problems building Metakit, Tcl or Expat on your platform,
use the methods described in their distributions to obtain help.
If you have problems building e4Graph on your platform, use the e4Graph
mailing lists described on the e4Graph project home
page to obtain help. I prefer this method rather than
corresponding via direct email, so that other subscribers can benefit
from the answers you receive.