OpenSystemsDevelopment / qpdf

Commit a78f8327587c281533c591156c10e9a6d15b3896

Authored by Jay Berkenbilt
1 parent cda14581

dos line endings 


git-svn-id: svn+q:///qpdf/trunk@1014 71b93d88-0707-0410-a8cf-f5a4172ac649
Inline Side-by-side
Showing 1 changed file with 154 additions and 154 deletions
README-windows.txt
  View file @a78f832
1   -Common Setup
2   -============
3   -
4   -To be able to build qpdf and run its test suite, you must have either
5   -Cygwin or MSYS from MinGW (>= 1.0.11) installed. If you want to build
6   -with Microsoft Visual C++, either Cygwin or MSYS will do. If you want
7   -to build with MinGW, you must use MSYS rather than Cygwin.
8   -
9   -As of this writing, the image comparison tests confuse ghostscript in
10   -cygwin, but there's a chance they might work at some point. If you
11   -want to run them, you need ghostscript and tiff utils as well. Then
12   -omit --disable-test-compare-images from the configure statements given
13   -below. The image comparison tests have not been tried under MSYS.
14   -
15   -
16   -External Libraries
17   -==================
18   -
19   -In order to build qpdf, you must have copies of zlib and pcre. The
20   -easy way to get them is to download them from the qpdf download area.
21   -There are packages called external-libs-bin.zip and
22   -external-libs-src.zip. If you are building with MSVC 9 (.NET 2008) or
23   -MINGW 4.4, you can just extract the external-libs-bin.zip zip file
24   -into the top-level qpdf source tree. It will create a directory
25   -called external-libs which contains header files and precompiled
26   -libraries. Passing --enable-external-libs to ./configure (which is
27   -done automatically if you follow the instructions below) is sufficient
28   -to find them.
29   -
30   -You can also obtain pcre and zlib directly on your own and install
31   -them. If you are using mingw, you can just set CPPFLAGS, LDFLAGS, and
32   -LIBS when you run ./configure so that it can find the header files and
33   -libraries. If you are building with msvc and you want to do this, it
34   -probably won't work because ./configure doesn't know how to interpret
35   -LDFLAGS and LIBS properly for MSVC (though qpdf's own build system
36   -does). In this case, you can probably get away with cheating by
37   -passing --enable-external-libs to ./configure and then just editing
38   -CPPFLAGS, LDFLAGS, LIBS in the generated autoconf.mk file. Note that
39   -you should use UNIX-like syntax (-I, -L, -l) even though this is not
40   -what cl takes on the command line. qpdf's build rules will fix it.
41   -
42   -
43   -Building with MinGW
44   -===================
45   -
46   -QPDF is known to build and pass its test suite with MSYS-1.0.11 and
47   -gcc 4.4.0 with C++ support. If you also have ActiveState Perl in your
48   -path and the external-libs distribution described above, you can fully
49   -configure, build, and test qpdf in this environment. You will most
50   -likely not be able to build qpdf with mingw using cygwin.
51   -
52   -From your MSYS prompt, run
53   -
54   - ./config-mingw
55   -
56   -and then
57   -
58   - make
59   -
60   -Note that ./config-mingw just runs ./configure with specific
61   -arguments, so you can look at it, make adjustments, and manually run
62   -configure instead.
63   -
64   -Add the absolute path to the libqpdf/build directory to your PATH.
65   -Make sure you can run the qpdf command by typing qpdf/build/qpdf and
66   -making sure you get a help message rather than an error loading the
67   -DLL or no output at all. Run the test suite by typing
68   -
69   - make check
70   -
71   -If all goes well, you should get a passing test suite.
72   -
73   -To create an installation directory, run make install. This will
74   -create install-mingw/qpdf-VERSION and populate it. The binary
75   -download of qpdf for Windows with mingw is created from this
76   -directory.
77   -
78   -
79   -Building with MSVC .NET 2008 Express
80   -====================================
81   -
82   -These instructions would likely work with newer version of MSVC or
83   -with full version of MSVC. They may also work with .NET 2005. They
84   -have only been tested with .NET 2008 Express (VC9.0). You may follow
85   -these instructions from either Cygwin or from MSYS, though only MSYS
86   -is regularly tested.
87   -
88   -You should first set up your environment to be able to run MSVC from
89   -the command line. There is usually a batch file included with MSVC
90   -that does this. From that cmd prompt, you can start your cygwin
91   -shell.
92   -
93   -Configure as follows:
94   -
95   - ./config-msvc
96   -
97   -and then
98   -
99   - make
100   -
101   -Note that ./config-msvc just runs ./configure with specific arguments,
102   -so you can look at it, make adjustments, and manually run configure
103   -instead.
104   -
105   -NOTE: automated dependencies are not generated with the msvc build.
106   -If you're planning on making modifications, you should probably work
107   -with mingw. If there is a need, I can add dependency information to
108   -the msvc build, but since I only use it for generating release
109   -versions, I haven't bothered.
110   -
111   -Once built, add the full path to the libqpdf/build directory to your
112   -path and run
113   -
114   - make check
115   -
116   -to run the test suite.
117   -
118   -If you are building with MSVC and want to debug a crash in MSVC's
119   -debugger, first start an instance of Visual C++. Then run qpdf. When
120   -the abort/retry/ignore dialog pops up, first attach the process from
121   -within visual C++, and then click Retry in qpdf.
122   -
123   -A release version of qpdf is built by default. If you want to link
124   -against debugging libraries, you will have to change /MD to /MDd in
125   -make/msvc.mk. Note that you must redistribute the Microsoft runtime
126   -DLLs. Linking with static runtime (/MT) won't work; see "Static
127   -Runtime" below for details.
128   -
129   -
130   -Runtime DLLs
131   -============
132   -
133   -Both build methods create executables and DLLs that are dependent on
134   -the compiler's runtime DLLs. When you run make install, the
135   -installation process will automatically detect the DLLs and copy them
136   -into the installation bin directory. Look at the copy_dlls script for
137   -details on how this is accomplished.
138   -
139   -Redistribution of the runtime DLL is unavoidable as of this writing;
140   -see "Static Runtime" below for details.
141   -
142   -
143   -Static Runtime
144   -==============
145   -
146   -Building the DLL and executables with static runtime does not work
147   -with either Visual C++ .NET 2008 (a.k.a. vc9) using /MT or with mingw
148   -(at least as of 4.4.0) using -static-libgcc. The reason is that, in
149   -both cases, there is static data involved with exception handling, and
150   -when the runtime is linked in statically, exceptions cannot be thrown
151   -across the DLL to EXE boundary. Since qpdf uses exception handling
152   -extensively for error handling, we have no choice but to redistribute
153   -the C++ runtime DLLs. Maybe this will be addressed in a future
154   -version of the compilers.
  1 +Common Setup
  2 +============
  3 +
  4 +To be able to build qpdf and run its test suite, you must have either
  5 +Cygwin or MSYS from MinGW (>= 1.0.11) installed. If you want to build
  6 +with Microsoft Visual C++, either Cygwin or MSYS will do. If you want
  7 +to build with MinGW, you must use MSYS rather than Cygwin.
  8 +
  9 +As of this writing, the image comparison tests confuse ghostscript in
  10 +cygwin, but there's a chance they might work at some point. If you
  11 +want to run them, you need ghostscript and tiff utils as well. Then
  12 +omit --disable-test-compare-images from the configure statements given
  13 +below. The image comparison tests have not been tried under MSYS.
  14 +
  15 +
  16 +External Libraries
  17 +==================
  18 +
  19 +In order to build qpdf, you must have copies of zlib and pcre. The
  20 +easy way to get them is to download them from the qpdf download area.
  21 +There are packages called external-libs-bin.zip and
  22 +external-libs-src.zip. If you are building with MSVC 9 (.NET 2008) or
  23 +MINGW 4.4, you can just extract the external-libs-bin.zip zip file
  24 +into the top-level qpdf source tree. It will create a directory
  25 +called external-libs which contains header files and precompiled
  26 +libraries. Passing --enable-external-libs to ./configure (which is
  27 +done automatically if you follow the instructions below) is sufficient
  28 +to find them.
  29 +
  30 +You can also obtain pcre and zlib directly on your own and install
  31 +them. If you are using mingw, you can just set CPPFLAGS, LDFLAGS, and
  32 +LIBS when you run ./configure so that it can find the header files and
  33 +libraries. If you are building with msvc and you want to do this, it
  34 +probably won't work because ./configure doesn't know how to interpret
  35 +LDFLAGS and LIBS properly for MSVC (though qpdf's own build system
  36 +does). In this case, you can probably get away with cheating by
  37 +passing --enable-external-libs to ./configure and then just editing
  38 +CPPFLAGS, LDFLAGS, LIBS in the generated autoconf.mk file. Note that
  39 +you should use UNIX-like syntax (-I, -L, -l) even though this is not
  40 +what cl takes on the command line. qpdf's build rules will fix it.
  41 +
  42 +
  43 +Building with MinGW
  44 +===================
  45 +
  46 +QPDF is known to build and pass its test suite with MSYS-1.0.11 and
  47 +gcc 4.4.0 with C++ support. If you also have ActiveState Perl in your
  48 +path and the external-libs distribution described above, you can fully
  49 +configure, build, and test qpdf in this environment. You will most
  50 +likely not be able to build qpdf with mingw using cygwin.
  51 +
  52 +From your MSYS prompt, run
  53 +
  54 + ./config-mingw
  55 +
  56 +and then
  57 +
  58 + make
  59 +
  60 +Note that ./config-mingw just runs ./configure with specific
  61 +arguments, so you can look at it, make adjustments, and manually run
  62 +configure instead.
  63 +
  64 +Add the absolute path to the libqpdf/build directory to your PATH.
  65 +Make sure you can run the qpdf command by typing qpdf/build/qpdf and
  66 +making sure you get a help message rather than an error loading the
  67 +DLL or no output at all. Run the test suite by typing
  68 +
  69 + make check
  70 +
  71 +If all goes well, you should get a passing test suite.
  72 +
  73 +To create an installation directory, run make install. This will
  74 +create install-mingw/qpdf-VERSION and populate it. The binary
  75 +download of qpdf for Windows with mingw is created from this
  76 +directory.
  77 +
  78 +
  79 +Building with MSVC .NET 2008 Express
  80 +====================================
  81 +
  82 +These instructions would likely work with newer version of MSVC or
  83 +with full version of MSVC. They may also work with .NET 2005. They
  84 +have only been tested with .NET 2008 Express (VC9.0). You may follow
  85 +these instructions from either Cygwin or from MSYS, though only MSYS
  86 +is regularly tested.
  87 +
  88 +You should first set up your environment to be able to run MSVC from
  89 +the command line. There is usually a batch file included with MSVC
  90 +that does this. From that cmd prompt, you can start your cygwin
  91 +shell.
  92 +
  93 +Configure as follows:
  94 +
  95 + ./config-msvc
  96 +
  97 +and then
  98 +
  99 + make
  100 +
  101 +Note that ./config-msvc just runs ./configure with specific arguments,
  102 +so you can look at it, make adjustments, and manually run configure
  103 +instead.
  104 +
  105 +NOTE: automated dependencies are not generated with the msvc build.
  106 +If you're planning on making modifications, you should probably work
  107 +with mingw. If there is a need, I can add dependency information to
  108 +the msvc build, but since I only use it for generating release
  109 +versions, I haven't bothered.
  110 +
  111 +Once built, add the full path to the libqpdf/build directory to your
  112 +path and run
  113 +
  114 + make check
  115 +
  116 +to run the test suite.
  117 +
  118 +If you are building with MSVC and want to debug a crash in MSVC's
  119 +debugger, first start an instance of Visual C++. Then run qpdf. When
  120 +the abort/retry/ignore dialog pops up, first attach the process from
  121 +within visual C++, and then click Retry in qpdf.
  122 +
  123 +A release version of qpdf is built by default. If you want to link
  124 +against debugging libraries, you will have to change /MD to /MDd in
  125 +make/msvc.mk. Note that you must redistribute the Microsoft runtime
  126 +DLLs. Linking with static runtime (/MT) won't work; see "Static
  127 +Runtime" below for details.
  128 +
  129 +
  130 +Runtime DLLs
  131 +============
  132 +
  133 +Both build methods create executables and DLLs that are dependent on
  134 +the compiler's runtime DLLs. When you run make install, the
  135 +installation process will automatically detect the DLLs and copy them
  136 +into the installation bin directory. Look at the copy_dlls script for
  137 +details on how this is accomplished.
  138 +
  139 +Redistribution of the runtime DLL is unavoidable as of this writing;
  140 +see "Static Runtime" below for details.
  141 +
  142 +
  143 +Static Runtime
  144 +==============
  145 +
  146 +Building the DLL and executables with static runtime does not work
  147 +with either Visual C++ .NET 2008 (a.k.a. vc9) using /MT or with mingw
  148 +(at least as of 4.4.0) using -static-libgcc. The reason is that, in
  149 +both cases, there is static data involved with exception handling, and
  150 +when the runtime is linked in statically, exceptions cannot be thrown
  151 +across the DLL to EXE boundary. Since qpdf uses exception handling
  152 +extensively for error handling, we have no choice but to redistribute
  153 +the C++ runtime DLLs. Maybe this will be addressed in a future
  154 +version of the compilers.
... ...