notes

git-svn-id: svn+q:///qpdf/trunk@779 71b93d88-0707-0410-a8cf-f5a4172ac649

notes
git-svn-id: svn+q:///qpdf/trunk@779 71b93d88-0707-0410-a8cf-f5a4172ac649
Jay Berkenbilt
1 parent 4f1ce188
Showing 4 changed files with 92 additions and 47 deletions
Makefile
README.windows
TODO
manual/qpdf-manual.xml
@@ -23,7 +23,9 @@
 # and make maintainer-clean to remove everything that is generated
 # including things distributed with the source distribution.  You can
 # pass CLEAN=1 to prevent this Makefile from complaining if
-# ./configure has not been run.
+# ./configure has not been run.  If you are cleaning from Windows, you
+# may also need to add BUILD_EXTERNAL_LIBS=1 to make sure you can that
+# as well.
 # The install target works as usual and obeys --prefix and so forth
 # passed to ./configure.  You can also pass DESTDIR=/dir to make
-By default, qpdf builds on UNIX and UNIX-like systems with simple
-./configure; make; make install comamnds.  It ordinarily uses libtool
-to build libraries and link executables.
+Common Setup
+============
-As an alternative, the build system can use its own built-in rules.
-The available build rules can be found in the make directory; all the
-files except rules.mk are build rules.  The gcc-linux rules are there
-primarily for testing the build system.  They are not intended to be
-used in production since, in a Linux environment, it's better to use
-the default libtool rules.
+To be able to run qpdf's test suite, you must have cygwin installed.
+This is because qpdf's test suite uses qtest, which requires cygwin
+perl on Windows.  (Hopefully a future version of qtest will work with
+ActiveState Perl.)  You must have at least perl and gnu diffutils
+installed to run the test suite.
-For building on Windows, autoconf and libtool don't generate a working
-build for either mingw (as of this writing) or MS Visual C++.  We use
-our own rules instead.  In addition, the external dependencies (pcre
-and zlib) are often not present on Windows systems.
+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.
-If you have MSYS and Mingw installed, you can run configure as follows:
+Building with MinGW
+===================
-./configure --disable-test-compare-images --enable-build-external-libs --with-buildrules=mingw
+QPDF is known to build and pass its test suite with MSYS-1.0.11 and
+gcc 4.4.0 with C++ support.  You can fully configure and build qpdf in
+this environment, though cygwin is required to run the test suite.
+You will most likely not be able to build qpdf with mingw using
+cygwin, though it's possible that it could be made to work with gcc
+-mno-cygwin.
-To build with msvc, you must be running in a shell environment that
-puts the MSVC tools in your path.  Then you can run
+From your MSYS prompt, run
-CC=cl CXX="cl /TP /GR" CPPFLAGS=-DHAVE_VSNPRINTF ./configure --disable-test-compare-images --enable-build-external-libs --with-buildrules=msvc
+  ./configure --disable-test-compare-images --enable-build-external-libs --with-buildrules=mingw
+  make
-This is tested with MSVC .NET 2008 Express.
+When done, you should copy the gcc runtime dll into the libqpdf/build
+directory.  You can find the path to it by running
-From there, run
+  objdump -p qpdf/build/qpdf.exe | grep DLL
+  type -P libgcc_s_dw2-1.dll
-make
+replacing libgcc_s_dw2-1.dll with whatever gcc DLL is shown, if
+different.
-at the top level directory to build everything.  Building with mingw
-from a cygwin environment is not likely to work.  However, you have to
-have a cygwin environment to run the test suite.  Once you have built
-qpdf using mingw, you can test as follows:
+From your cygwin prompt, 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
-From your MSYS environment:
+  make check GENDEPS=0
- * Run objdump qpdf/build/qpdf.exe | grep DLL
+from your cygwin prompt.  The GENDEPS=0 is necessary to prevent the
+build system in cygwin from trying to interpret the MSYS/Windows paths
+embedded in the dependency files.  If all goes well, you should get a
+passing test suite.
- * Copy the gcc runtime DLL into libqpdf/build
+Building with MSVC .NET 2008 Express
+====================================
-From a Cygwin environment:
+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.
- * Add the full path libqpdf/build to your path
+It's possible that the MSVC build may work from MSYS, but since cygwin
+is needed to run the test suite, these have only been tested from
+cygwin.
- * Run
+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.
-   make check GENDEPS=0
+Configure as follows:
-This will run the qtest-based test suite, which requires cygwin.  You
-need perl, gnu diffutils, and basic shell commands.
+  CC=cl CXX="cl /TP /GR" CPPFLAGS=-DHAVE_VSNPRINTF ./configure --disable-test-compare-images --enable-build-external-libs --with-buildrules=msvc
+  make
-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 your configure statement.
+Then 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.  You will probably have
+to edit msvc.mk to change /MD to /MDd to build a debugging version.
+It has also been attempted to build qpdf with /MT, but it does not
+pass its test suite in this configuration.  I have not investigated.
 2.1
 ===
- * Remember to update documentation with Windows build instructions.
-   Search for Windows (case insensitive to be safe).  Update
-   README.windows.
+ * Update documentation to reflect new command line flags and any
+   other relevant changes.  Should read through ChangeLog and the
+   manual before releasing 2.1.
+
+ * Add comments for the security functions that map them back to the
+   items in Adobe's products.
+
+ * Have force version at least turn off object streams and maybe
+   change security settings?
+
+ * Add error codes to QPDFException.  Change the error interface so
+   that warnings and errors are pointers that can be queried using
+   more C API functions.  We need a way to get a full string as well
+   as an error code, file name, offset, and message.  We should go
+   through all error messages to try to include all these fields as
+   appropriate.  Make sure invalid password is specifically
+   detectable.  I/O errors and so forth should also be
+   distinguishable.
+
+ * Test DLL works on a fresh XP installation
  * "Delphi wrapper unit 'qpdf.pas' created by Zarko Gajic
    (http://delphi.about.com). .. use at your own risk and for whatever
@@ -179,11 +179,10 @@ make
     <filename>INSTALL</filename> files in the source distribution.
    </para>
    <para>
-    There is currently no support for building qpdf on Windows.  The
-    code is reasonably portable, however, and making it work on
-    Windows would probably be reasonably straightforward.  A
-    significant amount of the code in QPDF has been known to work on
-    Windows in the past.
+    Building on Windows is a little bit more complicated.  For
+    details, please see <filename>README.windows</filename> in the
+    source distribution.  You can also download a binary distribution
+    for Windows.
    </para>
    <para>
     There are some other things you can do with the build.  Although