This is the QPDF package. Information about it can be found at http://qpdf.sourceforge.net. The source code repository is hosted at github: https://github.com/qpdf/qpdf. QPDF is copyright (c) 2005-2012 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. Prerequisites ============= QPDF depends on external libraries "zlib" and "pcre". These are part of virtually all Linux distributions and are readily available; download information appears in the documentation. For Windows, you can download pre-built binary versions of those libraries for some compilers; see README-windows.txt for additional details. QPDF requires a C++ compiler that works with STL. Your compiler must also support "long long". Almost all modern compilers do. If you are trying to port qpdf to a compiler that doesn't support long long, you could change all occurrences of "long long" to "long" in the source code, noting that this would break binary compatibility with other builds of qpdf. Doing so would certainly prevent qpdf from working with files larger than 2 GB, but remaining functionality would most likely work fine. If you built qpdf this way and it passed its test suite with large file support disabled, you could be confident that you had an otherwise working qpdf. Licensing terms of embedded software ==================================== QPDF makes use of zlib and pcre for its functionality. These packages can be downloaded separately from their own download locations, or they can be downloaded in the external-libs area of the qpdf download site. 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 Packagers may set DESTDIR, in which case make install will install inside of DESTDIR, as is customary with many packages. For more detailed general information, see the "INSTALL" file in this directory. If you are already accustomed to building and installing software that uses autoconf, there's nothing new for you in the INSTALL file. Building on Windows =================== QPDF is known to build and pass its test suite with mingw (latest version tested: gcc 4.6.2), mingw64 (latest version tested: 4.7.0) and Microsoft Visual C++ 2010, both 32-bit and 64-bit versions. MSYS plus ActiveState Perl is required to build as well in order to get make and other related tools. See README-windows.txt for details on how to build under Windows, see README-windows.txt. 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.txt 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 statically with -lqpdf, then you will also need to link with -lpcre and -lz. The shared qpdf library is linked with -lpcre and -lz, and none of qpdf's public header files directly include files from pcre or libz, so in many cases, qpdf's development files are self contained. 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. Reading all the source files in the qpdf directory (including the qpdf command-line tool and some test drivers) along with the code in the examples directory will give you a complete picture of every aspect of the public interface. Additional Notes on Test Suite ============================== By default, slow tests are disabled. Slow tests include image comparison tests and large file tests. Image comparison tests can be enabled by passing --enable-test-compare-images to ./configure. This was on by default in qpdf versions prior to 3.0, but is now off by default. Large file tests can be enabled by passing --with-large-file-test-path=path to ./configure or by setting the QPDF_LARGE_FILE_TEST_PATH environment variable. Run ./configure --help for additional options. The test suite provides nearly full coverage even without these tests. Unless you are making deep changes to the library that would impact the contents of the generated PDF files or testing this on a new platform for the first time, there is no real reason to run these tests. If you're just running the test suite to make sure that qpdf works for your build, the default tests are adequate. The configure rules for these tests do nothing other than setting variables in autoconf.mk, so you can feel free to turn these on and off directly in autoconf.mk rather than rerunning configure. If you are packaging qpdf for a distribution and preparing a build that is run by an autobuilder, you may want to add the --enable-show-failed-test-output to configure options. This way, if the test suite fails, test failure detail will be included in the build output. Otherwise, you will have to have access to the qtest.log file from the build to view test failures. The debian packages for qpdf enable this option, for example.
