Common Setup ============ You may need to disable antivirus software to run qpdf's test suite. To be able to build qpdf and run its test suite, you must have MSYS from MinGW installed, and you must have ActiveState Perl. Here's what I did on my system: Install ActiveState perl. Grab the latest mingw-get-inst. From the installation wizard, choose to install developer kit, C, and C++ support. Once installed, you will have an icon to start an msys shell. From the msys shell, run mingw-get install msys-unzip msys-zip mingw32-make Then replace perl and make with the appropriate versions: mv /bin/perl.exe /bin/msys-perl.exe mv /bin/make.exe /bin/msys-make.exe mv /mingw/bin/mingw32-make.exe /mingw/bin/make.exe Make sure perl --version shows ActiveState perl. To install MinGW-w64, first install msys and mingw32 as above. From MinGW-w64 download page, go to "Toolchains targeting Win64/Automated Builds" and find the latest mingw-w64 that runs under i686-mingw. It will be called something like mingw-w64-bin_i686-mingw_yyyymmdd.zip. The compiler binaries are 32-bit, which (of course) runs on 64-bit Windows. Extract this under C:\MinGW-w64, and add C:\MinGW-w64\bin and C:\MinGW-w64\lib\mingw to the path. As of this writing, the image comparison tests confuse ghostscript in cygwin, but there's a chance they might work at some point. If you want to run them, you need ghostscript and tiff utils as well, and you will need to add --enable-test-compare-images from the configure statements given below. Jian Ma has generously provided a port of QPDF that works with Microsoft VC6. Several changes are required, but they are well documented in his port. You can find the VC6 port in the contrib area of the qpdf download area. It may not always be up-to-date with the latest official qpdf release. External Libraries ================== In order to build qpdf, you must have copies of zlib and pcre. The easy way to get them is to download them from the qpdf download area. There are packages called external-libs-bin.zip and external-libs-src.zip. If you are building with MSVC 2010 or MINGW, you can just extract the qpdf-external-libs-bin.zip zip file into the top-level qpdf source tree. Note that you need the 2012-06-20 version (at least) to build qpdf 3.0 or greater since this includes 64-bit libraries. It will create a directory called external-libs which contains header files and precompiled libraries. Passing --enable-external-libs to ./configure (which is done automatically if you follow the instructions below) is sufficient to find them. You can also obtain pcre and zlib directly on your own and install them. If you are using mingw, you can just set CPPFLAGS, LDFLAGS, and LIBS when you run ./configure so that it can find the header files and libraries. If you are building with msvc and you want to do this, it probably won't work because ./configure doesn't know how to interpret LDFLAGS and LIBS properly for MSVC (though qpdf's own build system does). In this case, you can probably get away with cheating by passing --enable-external-libs to ./configure and then just editing CPPFLAGS, LDFLAGS, LIBS in the generated autoconf.mk file. Note that you should use UNIX-like syntax (-I, -L, -l) even though this is not what cl takes on the command line. qpdf's build rules will fix it. You can also download qpdf-external-libs-src.zip and follow the instructions in the README.txt there for how to build external libs. Building from version control ============================= If you check out qpdf from version control, you will not have the files that are generated by autoconf. If you are not changing these files, you can grab them from a source distribution or create them from a system that has autoconf. To create them from scratch, run ./autogen.sh on a system that has autoconf installed. Once you have them, you can run make CLEAN=1 autofiles.zip. This will create an autofiles.zip that you can extract on top of a fresh checkout. Building with MinGW =================== 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. While it is possible that Cygwin could be used to build native Windows versions of qpdf, this configuration has not been tested recently. From your MSYS prompt, run ./config-mingw32 or ./config-mingw64 and then make Note that ./config-mingw32 and ./configure-mingw64 just run ./configure with specific arguments, so you can look at it, make adjustments, and manually run configure instead. Note also that config-mingw32 appends definition of _FILE_OFFSET_BITS=64 to qpdf-config.h since, as of the qpdf 3.0 release, the current versions of the autoconf tools did not correctly detect that mingw requires this to get large file support. This workaround is only required for mingw32. The 64-bit version of mingw works "out of the box" with large file support, as do both the 32-bit and 64-bit versions of MSVC. Add the absolute path to the libqpdf/build directory to your PATH. Make sure you can run the qpdf command by typing qpdf/build/qpdf and making sure you get a help message rather than an error loading the DLL or no output at all. Run the test suite by typing make check If all goes well, you should get a passing test suite. To create an installation directory, run make install. This will create install-mingw/qpdf-VERSION and populate it. The binary download of qpdf for Windows with mingw is created from this directory. You can also take a look at make_windows_releases for reference. This is how the distributed Windows executables are created. Building with MSVC 2010 ======================= These instructions would likely work with newer version of MSVC or with full version of MSVC. They may also work with .NET 2005. They have only been tested with Visual C++ 2010. Earlier version of qpdf were built with MSVC 2008 Express. You should first set up your environment to be able to run MSVC from the command line. There is usually a batch file included with MSVC that does this. Make sure that you start a command line environment configured for whichever of 32-bit or 64-bit output that you intend to build for. From that cmd prompt, you can start your msys shell by just running manually whatever command is associated with your msys shell icon. Configure as follows: ./config-msvc 32 or ./config-msvc 64 Note that you must pass the 32/64 option that matches your command line setup. The scripts do not presently figure this out. If you used the wrong argument, it would probably just build the size you have in your environment and then install the results in the wrong place. Once configured, run make Note that ./config-msvc just runs ./configure with specific arguments, so you can look at it, make adjustments, and manually run configure instead. NOTE: automated dependencies are not generated with the msvc build. If you're planning on making modifications, you should probably work with mingw. If there is a need, I can add dependency information to the msvc build, but since I only use it for generating release versions, I haven't bothered. Once built, add the full path to the libqpdf/build directory to your path and run make check to run the test suite. If you are building with MSVC and want to debug a crash in MSVC's debugger, first start an instance of Visual C++. Then run qpdf. When the abort/retry/ignore dialog pops up, first attach the process from within visual C++, and then click Retry in qpdf. A release version of qpdf is built by default. If you want to link against debugging libraries, you will have to change /MD to /MDd in make/msvc.mk. Note that you must redistribute the Microsoft runtime DLLs. Linking with static runtime (/MT) won't work; see "Static Runtime" below for details. Runtime DLLs ============ Both build methods create executables and DLLs that are dependent on the compiler's runtime DLLs. When you run make install, the installation process will automatically detect the DLLs and copy them into the installation bin directory. Look at the copy_dlls script for details on how this is accomplished. Redistribution of the runtime DLL is unavoidable as of this writing; see "Static Runtime" below for details. Static Runtime ============== Building the DLL and executables with static runtime does not work with either Visual C++ .NET 2008 (a.k.a. vc9) using /MT or with mingw (at least as of 4.4.0) using -static-libgcc. The reason is that, in both cases, there is static data involved with exception handling, and when the runtime is linked in statically, exceptions cannot be thrown across the DLL to EXE boundary. Since qpdf uses exception handling extensively for error handling, we have no choice but to redistribute the C++ runtime DLLs. Maybe this will be addressed in a future version of the compilers. This has not been retested with the toolchain versions used to create qpdf 3.0 distributions.