]>
Commit | Line | Data |
---|---|---|
26abc8f0 RL |
1 | |
2 | INSTALLATION ON THE WIN32 PLATFORM | |
3 | ---------------------------------- | |
4 | ||
5 | [Instructions for building for Windows CE can be found in INSTALL.WCE] | |
1875e6db | 6 | [Instructions for building for Win64 can be found in INSTALL.W64] |
26abc8f0 | 7 | |
3189772e AP |
8 | Here are a few comments about building OpenSSL for Win32 environments, |
9 | such as Windows NT and Windows 9x. It should be noted though that | |
10 | Windows 9x are not ordinarily tested. Its mention merely means that we | |
11 | attempt to maintain certain programming discipline and pay attention | |
12 | to backward compatibility issues, in other words it's kind of expected | |
13 | to work on Windows 9x, but no regression tests are actually performed. | |
26abc8f0 | 14 | |
3189772e AP |
15 | On additional note newer OpenSSL versions are compiled and linked with |
16 | Winsock 2. This means that minimum OS requirement was elevated to NT 4 | |
17 | and Windows 98 [there is Winsock 2 update for Windows 95 though]. | |
26abc8f0 | 18 | |
3189772e AP |
19 | - you need Perl for Win32. Unless you will build on Cygwin, you will need |
20 | ActiveState Perl, available from http://www.activestate.com/ActivePerl. | |
21 | ||
22 | - one of the following C compilers: | |
26abc8f0 RL |
23 | |
24 | * Visual C++ | |
25 | * Borland C | |
26 | * GNU C (Cygwin or MinGW) | |
27 | ||
39c63e16 AP |
28 | - Netwide Assembler, a.k.a. NASM, available from http://nasm.sourceforge.net/ |
29 | is required if you intend to utilize assembler modules. Note that NASM | |
30 | is the only supported assembler. | |
3189772e | 31 | |
26abc8f0 RL |
32 | If you are compiling from a tarball or a CVS snapshot then the Win32 files |
33 | may well be not up to date. This may mean that some "tweaking" is required to | |
34 | get it all to work. See the trouble shooting section later on for if (when?) | |
35 | it goes wrong. | |
36 | ||
37 | Visual C++ | |
38 | ---------- | |
39 | ||
3189772e AP |
40 | If you want to compile in the assembly language routines with Visual |
41 | C++, then you will need already mentioned Netwide Assembler binary, | |
39c63e16 | 42 | nasmw.exe or nasm.exe, to be available on your %PATH%. |
26abc8f0 RL |
43 | |
44 | Firstly you should run Configure: | |
45 | ||
df8dae1d DSH |
46 | > perl Configure VC-WIN32 --prefix=c:/some/openssl/dir |
47 | ||
3189772e | 48 | Where the prefix argument specifies where OpenSSL will be installed to. |
26abc8f0 | 49 | |
3189772e AP |
50 | Next you need to build the Makefiles and optionally the assembly |
51 | language files: | |
26abc8f0 | 52 | |
26abc8f0 RL |
53 | - If you are using NASM then run: |
54 | ||
55 | > ms\do_nasm | |
56 | ||
57 | - If you don't want to use the assembly language files at all then run: | |
58 | ||
59 | > ms\do_ms | |
60 | ||
61 | If you get errors about things not having numbers assigned then check the | |
62 | troubleshooting section: you probably won't be able to compile it as it | |
63 | stands. | |
64 | ||
65 | Then from the VC++ environment at a prompt do: | |
66 | ||
67 | > nmake -f ms\ntdll.mak | |
68 | ||
3189772e AP |
69 | If all is well it should compile and you will have some DLLs and |
70 | executables in out32dll. If you want to try the tests then do: | |
26abc8f0 | 71 | |
df8dae1d DSH |
72 | > nmake -f ms\ntdll.mak test |
73 | ||
74 | ||
3189772e | 75 | To install OpenSSL to the specified location do: |
df8dae1d | 76 | |
3189772e | 77 | > nmake -f ms\ntdll.mak install |
26abc8f0 RL |
78 | |
79 | Tweaks: | |
80 | ||
3189772e AP |
81 | There are various changes you can make to the Win32 compile |
82 | environment. By default the library is not compiled with debugging | |
83 | symbols. If you add 'debug' to the mk1mf.pl lines in the do_* batch | |
84 | file then debugging symbols will be compiled in. Note that mk1mf.pl | |
85 | expects the platform to be the last argument on the command line, so | |
86 | 'debug' must appear before that, as all other options. | |
26abc8f0 | 87 | |
df8dae1d | 88 | |
3189772e AP |
89 | By default in 0.9.8 OpenSSL will compile builtin ENGINES into the |
90 | libeay32.dll shared library. If you specify the "no-static-engine" | |
91 | option on the command line to Configure the shared library build | |
92 | (ms\ntdll.mak) will compile the engines as separate DLLs. | |
df8dae1d | 93 | |
26abc8f0 RL |
94 | The default Win32 environment is to leave out any Windows NT specific |
95 | features. | |
96 | ||
3189772e AP |
97 | If you want to enable the NT specific features of OpenSSL (currently |
98 | only the logging BIO) follow the instructions above but call the batch | |
99 | file do_nt.bat instead of do_ms.bat. | |
26abc8f0 RL |
100 | |
101 | You can also build a static version of the library using the Makefile | |
102 | ms\nt.mak | |
103 | ||
df8dae1d DSH |
104 | |
105 | ||
26abc8f0 RL |
106 | Borland C++ builder 5 |
107 | --------------------- | |
108 | ||
109 | * Configure for building with Borland Builder: | |
110 | > perl Configure BC-32 | |
111 | ||
112 | * Create the appropriate makefile | |
113 | > ms\do_nasm | |
114 | ||
115 | * Build | |
116 | > make -f ms\bcb.mak | |
117 | ||
118 | Borland C++ builder 3 and 4 | |
119 | --------------------------- | |
120 | ||
121 | * Setup PATH. First must be GNU make then bcb4/bin | |
122 | ||
123 | * Run ms\bcb4.bat | |
124 | ||
125 | * Run make: | |
126 | > make -f bcb.mak | |
127 | ||
128 | GNU C (Cygwin) | |
129 | -------------- | |
130 | ||
3189772e AP |
131 | Cygwin implements a Posix/Unix runtime system (cygwin1.dll) on top of |
132 | Win32 subsystem and provides a bash shell and GNU tools environment. | |
133 | Consequently, a make of OpenSSL with Cygwin is virtually identical to | |
134 | Unix procedure. It is also possible to create Win32 binaries that only | |
135 | use the Microsoft C runtime system (msvcrt.dll or crtdll.dll) using | |
136 | MinGW. MinGW can be used in the Cygwin development environment or in a | |
137 | standalone setup as described in the following section. | |
26abc8f0 RL |
138 | |
139 | To build OpenSSL using Cygwin: | |
140 | ||
141 | * Install Cygwin (see http://cygwin.com/) | |
142 | ||
143 | * Install Perl and ensure it is in the path. Both Cygwin perl | |
144 | (5.6.1-2 or newer) and ActivePerl work. | |
145 | ||
146 | * Run the Cygwin bash shell | |
147 | ||
148 | * $ tar zxvf openssl-x.x.x.tar.gz | |
149 | $ cd openssl-x.x.x | |
150 | ||
151 | To build the Cygwin version of OpenSSL: | |
152 | ||
153 | $ ./config | |
154 | [...] | |
155 | $ make | |
156 | [...] | |
157 | $ make test | |
158 | $ make install | |
159 | ||
160 | This will create a default install in /usr/local/ssl. | |
161 | ||
162 | To build the MinGW version (native Windows) in Cygwin: | |
163 | ||
164 | $ ./Configure mingw | |
165 | [...] | |
166 | $ make | |
167 | [...] | |
168 | $ make test | |
169 | $ make install | |
170 | ||
171 | Cygwin Notes: | |
172 | ||
173 | "make test" and normal file operations may fail in directories | |
174 | mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin | |
175 | stripping of carriage returns. To avoid this ensure that a binary | |
176 | mount is used, e.g. mount -b c:\somewhere /home. | |
177 | ||
178 | "bc" is not provided in older Cygwin distribution. This causes a | |
179 | non-fatal error in "make test" but is otherwise harmless. If | |
180 | desired and needed, GNU bc can be built with Cygwin without change. | |
181 | ||
3189772e | 182 | GNU C (MinGW/MSYS) |
26abc8f0 RL |
183 | ------------- |
184 | ||
3189772e | 185 | * Compiler and shell environment installation: |
26abc8f0 | 186 | |
3189772e AP |
187 | MinGW and MSYS are available from http://www.mingw.org/, both are |
188 | required. Run the installers and do whatever magic they say it takes | |
189 | to start MSYS bash shell with GNU tools on its PATH. | |
26abc8f0 RL |
190 | |
191 | * Compile OpenSSL: | |
192 | ||
3189772e AP |
193 | $ ./config |
194 | [...] | |
195 | $ make | |
196 | [...] | |
197 | $ make test | |
198 | ||
199 | This will create the library and binaries in root source directory | |
200 | and openssl.exe application in apps directory. | |
26abc8f0 | 201 | |
3189772e AP |
202 | It is also possible to cross-compile it on Linux by configuring |
203 | with './Configure --cross-compile-prefix=i386-mingw32- mingw ...'. | |
204 | 'make test' is naturally not applicable then. | |
26abc8f0 RL |
205 | |
206 | libcrypto.a and libssl.a are the static libraries. To use the DLLs, | |
207 | link with libeay32.a and libssl32.a instead. | |
208 | ||
3189772e AP |
209 | See troubleshooting if you get error messages about functions not |
210 | having a number assigned. | |
26abc8f0 RL |
211 | |
212 | Installation | |
213 | ------------ | |
214 | ||
215 | If you used the Cygwin procedure above, you have already installed and | |
216 | can skip this section. For all other procedures, there's currently no real | |
217 | installation procedure for Win32. There are, however, some suggestions: | |
218 | ||
219 | - do nothing. The include files are found in the inc32/ subdirectory, | |
220 | all binaries are found in out32dll/ or out32/ depending if you built | |
221 | dynamic or static libraries. | |
222 | ||
223 | - do as is written in INSTALL.Win32 that comes with modssl: | |
224 | ||
225 | $ md c:\openssl | |
226 | $ md c:\openssl\bin | |
227 | $ md c:\openssl\lib | |
228 | $ md c:\openssl\include | |
229 | $ md c:\openssl\include\openssl | |
0ad2c4f8 | 230 | $ copy /b inc32\openssl\* c:\openssl\include\openssl |
26abc8f0 RL |
231 | $ copy /b out32dll\ssleay32.lib c:\openssl\lib |
232 | $ copy /b out32dll\libeay32.lib c:\openssl\lib | |
233 | $ copy /b out32dll\ssleay32.dll c:\openssl\bin | |
234 | $ copy /b out32dll\libeay32.dll c:\openssl\bin | |
235 | $ copy /b out32dll\openssl.exe c:\openssl\bin | |
236 | ||
237 | Of course, you can choose another device than c:. C: is used here | |
238 | because that's usually the first (and often only) harddisk device. | |
239 | Note: in the modssl INSTALL.Win32, p: is used rather than c:. | |
240 | ||
241 | ||
242 | Troubleshooting | |
243 | --------------- | |
244 | ||
245 | Since the Win32 build is only occasionally tested it may not always compile | |
246 | cleanly. If you get an error about functions not having numbers assigned | |
247 | when you run ms\do_ms then this means the Win32 ordinal files are not up to | |
248 | date. You can do: | |
249 | ||
250 | > perl util\mkdef.pl crypto ssl update | |
251 | ||
252 | then ms\do_XXX should not give a warning any more. However the numbers that | |
253 | get assigned by this technique may not match those that eventually get | |
254 | assigned in the CVS tree: so anything linked against this version of the | |
255 | library may need to be recompiled. | |
256 | ||
257 | If you get errors about unresolved symbols there are several possible | |
258 | causes. | |
259 | ||
260 | If this happens when the DLL is being linked and you have disabled some | |
261 | ciphers then it is possible the DEF file generator hasn't removed all | |
262 | the disabled symbols: the easiest solution is to edit the DEF files manually | |
263 | to delete them. The DEF files are ms\libeay32.def ms\ssleay32.def. | |
264 | ||
265 | Another cause is if you missed or ignored the errors about missing numbers | |
266 | mentioned above. | |
267 | ||
268 | If you get warnings in the code then the compilation will halt. | |
269 | ||
270 | The default Makefile for Win32 halts whenever any warnings occur. Since VC++ | |
271 | has its own ideas about warnings which don't always match up to other | |
272 | environments this can happen. The best fix is to edit the file with the | |
273 | warning in and fix it. Alternatively you can turn off the halt on warnings by | |
274 | editing the CFLAG line in the Makefile and deleting the /WX option. | |
275 | ||
276 | You might get compilation errors. Again you will have to fix these or report | |
277 | them. | |
278 | ||
279 | One final comment about compiling applications linked to the OpenSSL library. | |
280 | If you don't use the multithreaded DLL runtime library (/MD option) your | |
281 | program will almost certainly crash because malloc gets confused -- the | |
282 | OpenSSL DLLs are statically linked to one version, the application must | |
283 | not use a different one. You might be able to work around such problems | |
284 | by adding CRYPTO_malloc_init() to your program before any calls to the | |
285 | OpenSSL libraries: This tells the OpenSSL libraries to use the same | |
286 | malloc(), free() and realloc() as the application. However there are many | |
287 | standard library functions used by OpenSSL that call malloc() internally | |
288 | (e.g. fopen()), and OpenSSL cannot change these; so in general you cannot | |
289 | rely on CRYPTO_malloc_init() solving your problem, and you should | |
290 | consistently use the multithreaded library. | |
b3836ed3 AP |
291 | |
292 | Linking your application | |
293 | ------------------------ | |
294 | ||
295 | If you link with static OpenSSL libraries [those built with ms/nt.mak], | |
296 | then you're expected to additionally link your application with | |
3189772e | 297 | WS2_32.LIB, ADVAPI32.LIB, GDI32.LIB and USER32.LIB. Those developing |
b3836ed3 | 298 | non-interactive service applications might feel concerned about linking |
3189772e AP |
299 | with the latter two, as they are justly associated with interactive |
300 | desktop, which is not available to service processes. The toolkit is | |
301 | designed to detect in which context it's currently executed, GUI, | |
302 | console app or service, and act accordingly, namely whether or not to | |
303 | actually make GUI calls. | |
b3836ed3 AP |
304 | |
305 | If you link with OpenSSL .DLLs, then you're expected to include into | |
306 | your application code small "shim" snippet, which provides glue between | |
307 | OpenSSL BIO layer and your compiler run-time. Look up OPENSSL_Applink | |
308 | reference page for further details. |