diff --git a/README-windows.txt b/README-windows.txt index ac02c95e..2b665c31 100644 --- a/README-windows.txt +++ b/README-windows.txt @@ -1,154 +1,154 @@ -Common Setup -============ - -To be able to build qpdf and run its test suite, you must have either -Cygwin or MSYS from MinGW (>= 1.0.11) installed. If you want to build -with Microsoft Visual C++, either Cygwin or MSYS will do. If you want -to build with MinGW, you must use MSYS rather than Cygwin. - -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. Then -omit --disable-test-compare-images from the configure statements given -below. The image comparison tests have not been tried under MSYS. - - -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 9 (.NET 2008) or -MINGW 4.4, you can just extract the external-libs-bin.zip zip file -into the top-level qpdf source tree. 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. - - -Building with MinGW -=================== - -QPDF is known to build and pass its test suite with MSYS-1.0.11 and -gcc 4.4.0 with C++ support. If you also have ActiveState Perl in your -path and the external-libs distribution described above, you can fully -configure, build, and test qpdf in this environment. You will most -likely not be able to build qpdf with mingw using cygwin. - -From your MSYS prompt, run - - ./config-mingw - -and then - - make - -Note that ./config-mingw just runs ./configure with specific -arguments, so you can look at it, make adjustments, and manually run -configure instead. - -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. - - -Building with MSVC .NET 2008 Express -==================================== - -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 .NET 2008 Express (VC9.0). You may follow -these instructions from either Cygwin or from MSYS, though only MSYS -is regularly tested. - -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. From that cmd prompt, you can start your cygwin -shell. - -Configure as follows: - - ./config-msvc - -and then - - 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. +Common Setup +============ + +To be able to build qpdf and run its test suite, you must have either +Cygwin or MSYS from MinGW (>= 1.0.11) installed. If you want to build +with Microsoft Visual C++, either Cygwin or MSYS will do. If you want +to build with MinGW, you must use MSYS rather than Cygwin. + +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. Then +omit --disable-test-compare-images from the configure statements given +below. The image comparison tests have not been tried under MSYS. + + +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 9 (.NET 2008) or +MINGW 4.4, you can just extract the external-libs-bin.zip zip file +into the top-level qpdf source tree. 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. + + +Building with MinGW +=================== + +QPDF is known to build and pass its test suite with MSYS-1.0.11 and +gcc 4.4.0 with C++ support. If you also have ActiveState Perl in your +path and the external-libs distribution described above, you can fully +configure, build, and test qpdf in this environment. You will most +likely not be able to build qpdf with mingw using cygwin. + +From your MSYS prompt, run + + ./config-mingw + +and then + + make + +Note that ./config-mingw just runs ./configure with specific +arguments, so you can look at it, make adjustments, and manually run +configure instead. + +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. + + +Building with MSVC .NET 2008 Express +==================================== + +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 .NET 2008 Express (VC9.0). You may follow +these instructions from either Cygwin or from MSYS, though only MSYS +is regularly tested. + +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. From that cmd prompt, you can start your cygwin +shell. + +Configure as follows: + + ./config-msvc + +and then + + 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.