Building PDFlib on Unix systems
===============================

Auxiliary libraries
-------------------

The configure script will automatically find out which libraries
are available. Note that certain builds of the TIFF library also need
the IJG JPEG library. The configure script therefore also looks for the
JPEG library.

If you want to use one of the auxiliary libraries but haven't installed
them yet, you must do so before running PDFlib's configure script.

Source code for the auxiliary libraries is available from the Web sites
quoted in readme.txt.


Building PDFlib
---------------

To start the build process on Unix, type

unix> ./configure
unix> make
unix> make test

Several options can used with the configure script in order to
override some default configuration options, or to assist configure
in finding some software locations on your machine. Type

unix> ./configure --help

before the make command in order to see a list of available configure
options.

IMPORTANT: make sure to use only absolute path names for all custom
directories. Also, wildcards should not be used. This requirement is
necessary because otherwise the paths won't work as include paths with
compiler calls.

If you want to use PDFlib on another machine, do not simply copy
the PDFlib source tree over. Instead, copy the distribution fileset
and re-run the configure script. Otherwise, compiler, shared library
and installation settings may erroneously be taken from the first
machine instead of from the actual one.

Note that in very rare cases it may be necessary to rename the generated
library file in order to avoid name clashes when installing it. This
can be achieved with configure's --with-libname option. Currently this
problem is known to exist on Digital Unix 4.


configure troubleshooting
-------------------------

The configure script helps to keep PDFlib portable across a wide variety
of systems, and to keep track of many different configurations and
the availability of features. Generally the script does a good job.
Given the huge number of different systems, configure may occasionally
fail in one of several ways:

- failing to detect installed software

- failing to complete all tests due to errors during script execution

In the first case, you can help configure by finding out the necessary
paths etc. yourself, and supplying any required --with-... option on
the configure command line.

In the second case, you either also can try to supply --with-... options
in order to prevent the failing test from being called, or abandon
the feature if you don't need it by supplying the value "no" to the
respective configure option, e.g., --with-tcl=no.

If you can determine the cause of a failing configure script, we will
be happy to hear from you. Please supply your system details, the
feature/option in question, and a workaround or improvement if possible.


Testing and installing the library
----------------------------------

Optionally, to run sample PDFlib applications in several programming
environments (including the scripting languages which have been
detected by configure), type:

unix> make test

In order to install the library and the support files for all detected
scripting languages, type:

unix> make install

If you want to install only selected parts (e.g., only the PDFlib
C library or the Perl support), type "make install" in the
respective subdirectory.


Shared library support
----------------------

By default, the PDFlib core and auxiliary libraries are built
as shared objects (.so on most systems) instead of as a static library.
PDFlib relies on GNU libtool for shared library support. libtool
shadows the object files and libraries with a layer of .lo and .la
files. The actual library files are placed in a subdirectory called
".libs". The PDFlib Makefiles and libtool will take care of correct
use, testing, and installation of these libraries. If anything goes
wrong on your system, read the manual section on shared libraries,
take a look at the contents of the .libs subdirectory, and observe
what the supplied Makefiles do for compiling, linking, testing, and
installing.


Library version numbers
-----------------------

Libtool-generated libraries such as PDFlib number their interfaces
with integer interface numbers (no subversions!). In addition to the
interface number, a revision number can be used. A particular library
supports a range of interface numbers, where the range can have a length
of one or more. In particular, libtool defines the following:

CURRENT   The most recent interface number that this library implements.
REVISION  The implementation number of the CURRENT interface.
AGE       The length of the range of supported interfaces.

The following table relates PDFlib version numbers to the
C:R:A library versioning scheme which you may see in the names of
shared library files:

PDFlib    C:R:A   comments
----------------------------------------------------------------------
3.00      0:0:0   first release based on libtool

Many thanks to Evgeny Stambulchik for leading me on the right track
with respect to libtool and library versioning schemes!
