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 4.0.3 2:3: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!