1 files changed, 220 insertions, 0 deletions
diff --git a/README-windows.txt b/README-windows.txt
new file mode 100644
index 0000000..682920c
--- /dev/null
+++ b/README-windows.txt
@@ -0,0 +1,220 @@
+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 <stronghorse@tom.com> 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 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.