Chapter 1: Introduction

This is the Programmers' Reference Manual to e-lib, e-tunity's "miscellaneous tools library". e-lib contains C and C++ functions which we use in many of our programs. You'll probably need e-lib when building our software.

This chapter provides information on the installation and usage of e-lib. The following chapters are the core of the programmers' reference.

1.1: For e-lib V3 users

Important: If you're using e-lib version 3.XX, then this version should be considered as a major upgrade. e-lib 4 is a shared object archive libe.so, while older versions were statically linkable archives (libe.a).

This means that new versions of e-lib can now be installed without having to recompile the programs that use e-lib. We suggest that, during the first installation of e-lib V4, the file /usr/e/lib/libe.a is unlinked. This is the static library of version 3.

1.2: Installation of e-lib

The installation of e-lib is very straight-forward. If you're on a i386-based Linux platform, then the easiest way is to get the RPM named e-lib-X.YY-R-i386.rpm from http://public.e-tunity.com. Here, X.YY is a version ID, and R is a release ID. The RPM is installed by user root using rpm -i rpmfile.

Alternatively, you might want to build e-lib from source. In that case, proceed as follows:

1.2.1: General preparations

First of all, obtain the source archive from http://public.e-tuniyt.com. Unpack the archive in a suitable place.

Next, edit etc/Makefile.def and search for the symbol PREFIX. This is the global installation path. When not present, $EBASE or /usr/local are taken.

Make sure that you create the following directories under the prefix directory:

lib/ for libraries;
include/ for header files;
man/ for manual pages.

1.2.2: Preparations for shared libraries

If your operating system has a gcc compiler that supports -shared to build shared libraries, then read on. Otherwise skip to section 1.2.3.

Edit /etc/ld.so.conf and add the directory /usr/e/lib to the shared library search path. This step must be run by the user root and is only necessary during a 'fresh' install; i.e., on a system where e-lib isn't available yet. After this, the command ldconfig must be run by root.

Alternatively, the environment variable LD_LIBRARY_PATH may be set to point to the directory /usr/e/lib. We suggest however to change /etc/ld.so.conf, that way, program execution is not dependent on an environment setting. This may be relevant in, e.g., cron jobs, where the full login environment is not available.

1.2.3: Compiling and installing

chdir into the created directory e-lib, and make install. The installation will install all headers and shared or static libraries (depending on your system).

The prerequisites for a succesful full build of e-lib are a C and C++ compiler.

In order to create the manpages and documentation, you will need the package Yodl. The installation is triggerd by make installdoc.

1.2.4: FastCGI

FastCGI is an Apache module that allows CGI programs to run as server processes, with minimal code changes. CGI programs that require e-lib can be built as FastCGI server applications with the use of e-lib in FastCGI mode.

The construction of e-lib for FastCGI is not enabled by default. Contact e-tunity if you want to use e-lib in FastCGI programs; in that case, we'll happily let you know how to cook a FastCGI-e-lib version.

1.3: Using the functions, classes and libraries

Once installed, the following libraries are available:

libe.so and libefcgi.so: these libraries contain the C functions, in plain mode and in FastCGI mode. The archives are 'shared libraries', which makes updates of e-lib functionality easier.
libepp.so: this shared library holds the C++ classes.
libgetline.a: a separate small C library for light-weight command-line editing support.

1.3.1: Using the C functions

To use the C functions, the compile-time inclusion of e-lib.h is required. During linkage, the flags -L/usr/e/lib -le or -L/usr/e/lib -lefcgi are needed. (The flag -lefcgi of course selects the FastCGI version of e-lib.)

The thus linked program will connect to libe.so or libefcgi.so during the program execution. The shared object libraries are not directly linked to a program.

1.3.2: Using the C++ classes

To use the C++ classes, the class header must be included (e.g., e-strarr.h). During linkage, the flags -L/usr/e/lib -lepp are required.

1.3.3: Using getline

To use the functionality of getline, the header getline.h is included during compilation. During linkage, the flags -L/usr/e/lib -lgetline are needed. For more information on getline, please see the manpage (run man getline after installing e-lib).