From dba228452df014b6302eae5c5d97963fedebe6d3 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Tue, 22 Aug 2017 13:00:49 -0400 Subject: Rename README files before converting to markdown --- README.md | 239 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 00000000..5c15fa3d --- /dev/null +++ b/README.md @@ -0,0 +1,239 @@ +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-2017 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 the external libraries "zlib" and "jpeg". These are +part of every Linux distribution and are readily available. Download +information appears in the documentation. For Windows, you can +download pre-built binary versions of these 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 jpeg libraries 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 + +The embedded sha2 code comes from sphlib 3.0 + + http://www.saphir2.com/sphlib/ + +That code has the following license: + + Copyright (c) 2007-2011 Projet RNRT SAPHIR + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +Building from a pristine checkout +================================= + +When building qpdf from a pristine checkout from version control, +documentation and automatically generated files are not present. +Building on Windows from a pristine checkout is not guaranteed to work +because of issues running autoconf; see README-windows.txt for how to +handle this. For UNIX and UNIX-like systems, you must have some +addditional tools installed to build from the source repository. To +do this, you should run + +./autogen.sh +./configure --enable-doc-maintenance +make +make install + +If you don't have Apache fop and the docbook stylesheets installed, +you won't be able to build documentation. You can omit +--enable-doc-maintenance and produce working qpdf software that passes +its test suite, but make install will fail because the documentation +files won't exist. Depending on your purposes, you can either work +around this or grab the docs from a source distribution. + + +Building from source distribution 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 -lz and -ljpeg. The shared qpdf library is +linked with -lz and -ljpeg, none of qpdf's public header files +directly include files from libz, and only Pl_DCT.hh includes files +from libjpeg, so for most cases, qpdf's development files are self +contained. If you need to use Pl_DCT in your application code, you +will need to have the header files for some libjpeg distribution in +your include path. + +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. On Windows, this +should be a Windows path. 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. + + +Random Number Generation +======================== + +By default, when the qpdf detects either the Windows cryptography API +or the existence of /dev/urandom, /dev/arandom, or /dev/random, it +uses them to generate cryptography secure random numbers. If none of +these conditions are true, the build will fail with an error. This +behavior can be modified in several ways: + + * If you configure with --disable-os-secure-random or define + SKIP_OS_SECURE_RANDOM, qpdf will not attempt to use Windows + cryptography or the random device. You must either supply your own + random data provider or allow use of insecure random numbers. + + * If you configure qpdf with the --enable-insecure-random option or + define USE_INSECURE_RANDOM, qpdf will try insecure random numbers + if OS-provided secure random numbers are disabled. This is not a + fallback. In order for insecure random numbers to be used, you + must also disable OS secure random numbers since, otherwise, + failure to find OS secure random numbers is a compile error. The + insecure random number source is stdlib's random() or rand() calls. + These random numbers are not cryptography secure, but the qpdf + library is fully functional using them. Using non-secure random + numbers means that it's easier in some cases to guess encryption + keys. If you're not generating encrypted files, there's no + advantage to using secure random numbers. + + * In all cases, you may supply your own random data provider. To do + this, derive a class from qpdf/RandomDataProvider (since 5.1.0) and + call QUtil::setRandomDataProvider before you create any QPDF + objects. If you supply your own random data provider, it will + always be used even if support for one of the other random data + providers is compiled in. If you wish to avoid any possibility of + your build of qpdf from using anything but a user-supplied random + data provider, you can define SKIP_OS_SECURE_RANDOM and not + USE_INSECURE_RANDOM. In this case, qpdf will throw a runtime error + if any attempt is made to generate random numbers and no random + data provider has been supplied. + +If you are building qpdf on a platform that qpdf doesn't know how to +generate secure random numbers on, a patch would be welcome. -- cgit v1.2.3-54-g00ecf