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