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

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

To start the build process on Unix, type

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

Several options can be 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 could 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-pdflibname option. Currently this
problem is known to exist on Digital Unix 4.


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

# make install

Note that installing will usually require root privileges.

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 (e.g, bind/perl), or (equivalently) type
"make pdflib_perl_install".


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.

The configure script may  fail under Cygwin when trying to probe for languages
if path names contain space characters.
It's safer to disable language probing using --with-perl=no etc.


Forcing a certain compiler or compiler flags
--------------------------------------------

You can set several environment variables before running the configure
script. These variables will be used in the generated Makefiles. The more
important ones are:

CC       The C compiler to use
CXX      The C++ compiler to use
CFLAGS   C compiler flags
LDFLAGS	 linker flags, such as additional libraries

For example, the following works well on Solaris (in a csh environment):

setenv CC /opt/SUNWspro/bin/cc
setenv CXX /opt/SUNWspro/bin/CC
setenv CFLAGS '-fast -xO3 -xtarget=generic'
./configure


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

Language bindings other than C/C++ require shared library support for
PDFlib to work. By default, the PDFlib core library will be built as both
a static and a shared library if possible.

C or C++ language clients must deploy libtool for using PDFlib, or install
the generated PDFlib library using "make install".

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 correctly
building, testing, and installing 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.


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

Starting with version 4.0, PDFlib includes portions of the libtiff, zlib,
and libpng auxiliary libraries as part of the distribution package. These
libraries have been modified for use with PDFlib in several ways:

- all function names are prefixed with a PDFlib-private tag
- code which is not required for PDFlib has been removed
- a number of portability changes have been applied

Our build process directly links these libraries into the PDFlib binary,
regardless of whether a shared or static PDFlib is generated. We no longer
use external versions of these libraries for various reasons:

- an integrated build process generates a full-blown PDFlib with all features
- the user doesn't have to struggle with building other libraries
- most importantly, not all language bindings can be made to work
  reliably when multiple shared libraries are involved

Due to the prefixed function names an application can link against both
a full-blown PDFlib (including all auxiliary libraries) and standard
versions of these libs.

People who insist on using the standard versions of the auxiliary libs
can do so if they observe the following:

- The --with-tifflib, --with-zlib, --with-pnglib options of the configure
  script must be used to replace PDFlib's internal version of a library.

- If one of libpng and libz is replaced, the other one must be replaced, too.
  This is required because of the PDFlib-specific function name prefix
  which is used in the internal versions, and because libpng requires
  libz in turn. Internal and external versions of these libs just won't
  match.

- Libraries which shall be replaced must be installed in some "standard"
  system location, or in some private directory which is specified in
  an appropriate -L option in the LDFLAGS environment variable, for example:

  LDFLAGS=/home/tm/libs/libtiff configure --with-tifflib

  The specified directory must contain a usable static library, and the
  option will be included in the list of options which are required for
  linking an application against PDFlib (as reported by pdflib-config --libs).

- Replacing any one library will disable all language bindings except
  C and C++.
  

Querying PDFlib configuration info
----------------------------------

In order to find out details about PDFlib's version, configuration,
and use, the pdflib-config shell script can be used. It is built during
the configure run, and returns all information you'll need for PDFlib
deployment. Running the script without any options lists the supported
command line options.


Problems viewing the PDFlib purchase order form
-----------------------------------------------

If you experience the error message "Unable to extract the embedded
font..." while viewing the form under Unix or Linux, you are running into
a bug in Acrobat Reader which affects non-english locale settings.
Workarounds: use a different PDF viewer (e.g., xpdf or Ghostscript), or set
the LANG variable to either "C" or empty before launching Acrobat:

unix> LANG=C acroread PDFlib-purchase-order.pdf


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 (i.e., CURRENT
          numbers).

The following table relates PDFlib version numbers to the C:R:A library
versioning scheme used by libtool. Note that these numbers will not show
up in the PDFlib shared library file name directly, but in some modified form
which is system-dependent:

PDFlib    C:R:A   comments
-------------------------------------------------------------------------------
3.00      0:0:0   first release based on libtool
3.01      0:1:0   maintenance release (bug: should have increased C since
                  undocumented functions were removed)
3.02      1:0:0   cleans up the non-incrementing glitch in 3.01
3.03      1:1:1   maintenance release (bug: should not have increased A)
4.0.0b    2:0:2   new API functions (inherits the 3.03 bug)
4.0.0     2:0:1   cleanup for major release: repairs the 3.03 "age" bug
4.0.1     2:1:1   maintenance release
4.0.2     2:2:1   maintenance release

When the PDFlib core is built as a static library version numbers will not
be visible. However, since language bindings other than C and C++ are always
built as shared libraries, they will have version numbers visible on most
systems.

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