qpdf/README

This is the QPDF package.  Information about it can be found at
http://qpdf.qbilt.org.

QPDF is copyright (c) 2005-2009 Jay Berkenbilt

This software may be distributed under the terms of version 2 of the
Artistic License which may be found in the source distribution as
"Artistic-2.0".  It is provided "as is" without express or implied
warranty.


Licensing terms of embedded software
====================================

Some additional software with additional licensing terms is embedded
within the qpdf source distribution in "external-libs".  This software
is not actually used by the qpdf build unless the
--enable-build-external-libs option is passed to ./configure.  These
packages have their own licensing terms, both of which are compatible
with qpdf's license.

Zlib's license can be read in external-libs/zlib/zlib.h

PCRE's licensing terms can be found in external-libs/pcre/LICENSE.
PCRE's licensing terms require that we include the following
information:

   Regular expression support is provided by the PCRE library package,
   which is open source software, written by Philip Hazel, and
   copyright by the University of Cambridge, England.

The sources to PCRE can be independently obtained from

   ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/

The Rijndael encryption implementation used as the basis for AES
encryption and decryption support comes from Philip J. Erdelsky's
public domain implementation.  The files libqpdf/rijndael.cc and
libqpdf/qpdf/rijndael.h remain in the public domain.  They were
obtained from

  http://www.efgh.com/software/rijndael.htm
  http://www.efgh.com/software/rijndael.txt


Building on UNIX/Linux
======================

For UNIX and UNIX-like systems, you can usually get by with just

./configure
make
make install

For more detailed general information, see the "INSTALL" file in this
directory.

Building on Windows
===================

QPDF is known to build and pass its test suite with mingw (gcc 4.4.0)
and Microsoft Visual C++ .NET 2008 Express.  Either cygwin or MSYS
plus ActivateState Perl is required to build as well in order to get
make and other related tools.  The MSVC works with either cygwin or
MSYS.  The mingw build requires MSYS and will probably not work with
cygwin.

For details on how to build under Windows, see README.windows.


Additional Notes on Build
=========================

QPDF's build system, inspired by abuild (http://www.abuild.org), can
optionally use its own built-in rules rather than using libtool and
obeying the compiler specified with configure.  This can be enabled by
passing --with-buildrules=buildrules where buildrules corresponds to
one of the .mk files (other than rules.mk) in the make directory.
This should never be necessary on a UNIX system, but may be necessary
on a Windows system.  See README.windows for details.  There is a
gcc-linux.mk file enable "gcc-linux" build rules, but it is intended
to help test the build system; Linux users should build with the
"libtools" rules, which are enabled by default.

The QPDF package provides some executables and a software library.  A
user's manual can be found in the "doc" directory.  The docbook
sources to the user's manual can be found in the "manual" directory.

The software library is just libqpdf, and all the header files are in
the qpdf subdirectory.  If you link with -lqpdf and your system does
not know how to read libtool .la files, then you will also need to
link with -lpcre and -lz.

To learn about using the library, please read comments in the header
files in include/qpdf, especially QPDF.hh, QPDFObjectHandle.hh, and
QPDFWriter.hh.  You can also study the code of qpdf/qpdf.cc, which
exercises most of the public interface.  There are additional example
programs in the examples directory.