EGAD Library Manual

• Previous
• Contents
• Next

Introduction

Installation

EGAD Library has been developed to be as cross-platform as possible. The two main development platforms have been Linux and Windows. SGI Irix machines have also been used, though the compilation is similar to that of Linux machines. If any other platforms have been attempted, we would love to know about them.

General Considerations

EGAD Library has relatively few dependencies. It is a C++ library that makes extensive use of the Standard Template Library (STL), so make sure you have a stable, up-to-date copy of one for your platform of choice. It also makes use of the zlib compression library. It is necessary to have the development header files available, in order to successfully compile EGAD Library.

Since the library is not a standalone program, "installation" refers to the process of compiling the library from source and placing the resulting files in an obvious location, depending on platform. Packages may be available for your platform that automatically install the header and library files, without the need for compilation.

However, the cleanest way is always to compile your own copy. This guide assumes that you have downloaded the source code and unpacked it into an empty directory. Within the directory, you should have a structure similar to this:

/
 docs/
 ... documentation files
 include/
 ... header files
 lib/
 ... empty
 src/
 ... source code
 EGAD_Library.vcproj
 Makefile
 Makefile.common
 Makefile.deps
 Makefile.library
 Makefile.vars
 Makefile.win32

The files present in the root directory are used for building across various architectures, as described below.

Linux

The library has been compiled on Linux machines using both the GNU g++ compiler and the Intel C++ compiler. We have noticed speed improvements when using Intel's compiler on Pentium 4 machines, though we have not profiled the applications to be sure.

Zlib is provided by most modern Linux distributions, but many of them may not provide the header files necessary to compile EGAD Library. Check if there is a "devel" package available for your distribution and make sure it is installed, before proceeding. The compiler will have to be able to find the zlib.h header file.

The Linux build process involves the GNU make utility that most users are familiar with. It does not, currently, use the autoconf package, mostly because we haven't managed to decipher the obfuscated autoconf documentation. If this means nothing to you, don't worry about it.

The default Makefile uses the gcc compiler, version 3, with the -O2 optimization flag, which is acceptable for nearly all Linux distributions. If any of these have to be changed, edit the variables in Makefile.common. Otherwise, compilation is straightforward:

> make clean
> make all

The result of this process should be a ton of object (.o) files in the root of the build directory, and a single static library (.a) file in the lib subdirectory. If you have these files, then the compilation is a success. There is no "install" target in the Makefile, so installation must be done manually, if at all. 

To compile applications using the library, simply make sure that the header and library files are accessible at the appropriate stages of compilation and linking:

# $(LIB_DIR) is the directory containing the static library (libEgad.a)
# $(ZLIB_DIR) is the directory containing the zlib static library (libz.a)
# $(INC_DIR) is the directory containing the header files (EGAD_*.h)
#
# Any of these directories may be omitted if the files are present in the
# standard compiler search path.

# Compile the application code (example.cpp) to an object file (example.o)
gcc -Wall -O2 -c -I$(INC_DIR) example.cpp -o example.o

# Link the object file (example.o) to make an executable (example)
gcc -Wall -L$(LIB_DIR) -o example example.cpp -lEgad -lz

Windows

The library has been compiled on Windows machines using Microsoft's Visual C++ .NET (7.1) compiler. There are two windows-specific files, found in the root directory of the source tree. Makefile.win32 is an NMAKE Makefile that will compile the sources into object (.obj) files and link them into a static library (.lib) file. EGAD_Library.vcproj is a project file for the Visual C++ IDE. The project simply allows use of the makefile through the IDE, so if you prefer to use NMAKE from the command line, then feel free to do so.

Zlib does not come standard, in any version of Windows. You have to download a copy of it. The source-code can be downloaded and compiled from scratch, but it is easier to simply download the "developer files" distribution from http://gnuwin32.sourceforge.net/packages/zlib.htm. Modify the ZLIB_INCLUDE variable inside the Makefile.win32 file to point to the directory containing the zlib.h header file. This is the only variable that needs to be set.

This documentation assumes that you are familiar with the Visual C++ IDE and have already set it up, properly, to compile other applications. This means that your include and linking paths are set up and you could compile a Hello World program in C++. For more information on how to do this, consult the Visual C++ documentation or Microsoft Developer Network (MSDN).

Open the project file and run the Build command. NMAKE should execute and compile .obj files into the "Release" subdirectory of the source (if one doesn't exist, it will be created silently). Once the objects have finished compiling, it will link them together into a file called EGAD_Library.lib, which can later be statically linked into an application.

To use the library in other projects, add the include directory to the project path (Project Properties > C/C++ >General > Additional Include Directories). Also add the Release directory and the directory containing zlib.lib to the linker path (Project Properties > Linker > General > Additional Library Directories). Finally, add EGAD_Library.lib and zlib.lib as dependencies for the linker(Project Properties > Linker > Input > Additional Dependencies).