]>
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 | 187 | |
da64e0d8 AP |
188 | N.B. Since source tar-ball can contain symbolic links, it's essential |
189 | that you use accompanying MSYS tar to unpack the source. It will | |
190 | either handle them in one way or another or fail to extract them, | |
191 | which does the trick too. Latter means that you may safely ignore all | |
192 | "cannot create symlink" messages, as they will be "re-created" at | |
193 | configure stage by copying corresponding files. Alternative programs | |
194 | were observed to create empty files instead, which results in build | |
195 | failure. | |
196 | ||
26abc8f0 RL |
197 | * Compile OpenSSL: |
198 | ||
3189772e AP |
199 | $ ./config |
200 | [...] | |
201 | $ make | |
202 | [...] | |
203 | $ make test | |
204 | ||
205 | This will create the library and binaries in root source directory | |
206 | and openssl.exe application in apps directory. | |
26abc8f0 | 207 | |
3189772e AP |
208 | It is also possible to cross-compile it on Linux by configuring |
209 | with './Configure --cross-compile-prefix=i386-mingw32- mingw ...'. | |
210 | 'make test' is naturally not applicable then. | |
26abc8f0 RL |
211 | |
212 | libcrypto.a and libssl.a are the static libraries. To use the DLLs, | |
213 | link with libeay32.a and libssl32.a instead. | |
214 | ||
3189772e AP |
215 | See troubleshooting if you get error messages about functions not |
216 | having a number assigned. | |
26abc8f0 RL |
217 | |
218 | Installation | |
219 | ------------ | |
220 | ||
221 | If you used the Cygwin procedure above, you have already installed and | |
222 | can skip this section. For all other procedures, there's currently no real | |
223 | installation procedure for Win32. There are, however, some suggestions: | |
224 | ||
225 | - do nothing. The include files are found in the inc32/ subdirectory, | |
226 | all binaries are found in out32dll/ or out32/ depending if you built | |
227 | dynamic or static libraries. | |
228 | ||
229 | - do as is written in INSTALL.Win32 that comes with modssl: | |
230 | ||
231 | $ md c:\openssl | |
232 | $ md c:\openssl\bin | |
233 | $ md c:\openssl\lib | |
234 | $ md c:\openssl\include | |
235 | $ md c:\openssl\include\openssl | |
0ad2c4f8 | 236 | $ copy /b inc32\openssl\* c:\openssl\include\openssl |
26abc8f0 RL |
237 | $ copy /b out32dll\ssleay32.lib c:\openssl\lib |
238 | $ copy /b out32dll\libeay32.lib c:\openssl\lib | |
239 | $ copy /b out32dll\ssleay32.dll c:\openssl\bin | |
240 | $ copy /b out32dll\libeay32.dll c:\openssl\bin | |
241 | $ copy /b out32dll\openssl.exe c:\openssl\bin | |
242 | ||
243 | Of course, you can choose another device than c:. C: is used here | |
244 | because that's usually the first (and often only) harddisk device. | |
245 | Note: in the modssl INSTALL.Win32, p: is used rather than c:. | |
246 | ||
247 | ||
248 | Troubleshooting | |
249 | --------------- | |
250 | ||
251 | Since the Win32 build is only occasionally tested it may not always compile | |
252 | cleanly. If you get an error about functions not having numbers assigned | |
253 | when you run ms\do_ms then this means the Win32 ordinal files are not up to | |
254 | date. You can do: | |
255 | ||
256 | > perl util\mkdef.pl crypto ssl update | |
257 | ||
258 | then ms\do_XXX should not give a warning any more. However the numbers that | |
259 | get assigned by this technique may not match those that eventually get | |
260 | assigned in the CVS tree: so anything linked against this version of the | |
261 | library may need to be recompiled. | |
262 | ||
263 | If you get errors about unresolved symbols there are several possible | |
264 | causes. | |
265 | ||
266 | If this happens when the DLL is being linked and you have disabled some | |
267 | ciphers then it is possible the DEF file generator hasn't removed all | |
268 | the disabled symbols: the easiest solution is to edit the DEF files manually | |
269 | to delete them. The DEF files are ms\libeay32.def ms\ssleay32.def. | |
270 | ||
271 | Another cause is if you missed or ignored the errors about missing numbers | |
272 | mentioned above. | |
273 | ||
274 | If you get warnings in the code then the compilation will halt. | |
275 | ||
276 | The default Makefile for Win32 halts whenever any warnings occur. Since VC++ | |
277 | has its own ideas about warnings which don't always match up to other | |
278 | environments this can happen. The best fix is to edit the file with the | |
279 | warning in and fix it. Alternatively you can turn off the halt on warnings by | |
280 | editing the CFLAG line in the Makefile and deleting the /WX option. | |
281 | ||
282 | You might get compilation errors. Again you will have to fix these or report | |
283 | them. | |
284 | ||
285 | One final comment about compiling applications linked to the OpenSSL library. | |
286 | If you don't use the multithreaded DLL runtime library (/MD option) your | |
287 | program will almost certainly crash because malloc gets confused -- the | |
288 | OpenSSL DLLs are statically linked to one version, the application must | |
289 | not use a different one. You might be able to work around such problems | |
290 | by adding CRYPTO_malloc_init() to your program before any calls to the | |
291 | OpenSSL libraries: This tells the OpenSSL libraries to use the same | |
292 | malloc(), free() and realloc() as the application. However there are many | |
293 | standard library functions used by OpenSSL that call malloc() internally | |
294 | (e.g. fopen()), and OpenSSL cannot change these; so in general you cannot | |
295 | rely on CRYPTO_malloc_init() solving your problem, and you should | |
296 | consistently use the multithreaded library. | |
b3836ed3 AP |
297 | |
298 | Linking your application | |
299 | ------------------------ | |
300 | ||
301 | If you link with static OpenSSL libraries [those built with ms/nt.mak], | |
302 | then you're expected to additionally link your application with | |
3189772e | 303 | WS2_32.LIB, ADVAPI32.LIB, GDI32.LIB and USER32.LIB. Those developing |
b3836ed3 | 304 | non-interactive service applications might feel concerned about linking |
3189772e AP |
305 | with the latter two, as they are justly associated with interactive |
306 | desktop, which is not available to service processes. The toolkit is | |
307 | designed to detect in which context it's currently executed, GUI, | |
308 | console app or service, and act accordingly, namely whether or not to | |
653215a1 AP |
309 | actually make GUI calls. Additionally those who wish to |
310 | /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and actually keep them | |
311 | off service process should consider implementing and exporting from | |
312 | .exe image in question own _OPENSSL_isservice not relying on USER32.DLL. | |
313 | E.g., on Windows Vista and later you could: | |
314 | ||
315 | __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) | |
316 | { DWORD sess; | |
317 | if (ProcessIdToSessionId(GetCurrentProcessId(),&sess)) | |
318 | return sess==0; | |
319 | return FALSE; | |
320 | } | |
b3836ed3 AP |
321 | |
322 | If you link with OpenSSL .DLLs, then you're expected to include into | |
323 | your application code small "shim" snippet, which provides glue between | |
324 | OpenSSL BIO layer and your compiler run-time. Look up OPENSSL_Applink | |
325 | reference page for further details. |