OpenSystemsDevelopment / qpdf

Commit a78f8327587c281533c591156c10e9a6d15b3896

Authored by Jay Berkenbilt 2010-08-14 16:35:10 +0000

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.