]>
Commit | Line | Data |
---|---|---|
dc589dae | 1 | Notes for Windows platforms |
474853c3 | 2 | =========================== |
26abc8f0 | 3 | |
cf6342bc | 4 | - [Native builds using Visual C++](#native-builds-using-visual-c) |
55aa235e | 5 | - [Native builds using Embarcadero C++Builder]( |
cf6342bc | 6 | #native-builds-using-embarcadero-cbuilder) |
dc589dae DMSP |
7 | - [Native builds using MinGW](#native-builds-using-mingw) |
8 | - [Linking native applications](#linking-native-applications) | |
9 | - [Hosted builds using Cygwin](#hosted-builds-using-cygwin) | |
df4c1d80 | 10 | |
dc589dae | 11 | There are various options to build and run OpenSSL on the Windows platforms. |
df4c1d80 | 12 | |
dc589dae DMSP |
13 | "Native" OpenSSL uses the Windows APIs directly at run time. |
14 | To build a native OpenSSL you can either use: | |
df4c1d80 | 15 | |
dc589dae | 16 | Microsoft Visual C++ (MSVC) C compiler on the command line |
55aa235e TI |
17 | or |
18 | Embarcadero C++Builder | |
dc589dae DMSP |
19 | or |
20 | MinGW cross compiler | |
21 | run on the GNU-like development environment MSYS2 | |
22 | or run on Linux or Cygwin | |
97a479c6 | 23 | |
dc589dae DMSP |
24 | "Hosted" OpenSSL relies on an external POSIX compatibility layer |
25 | for building (using GNU/Unix shell, compiler, and tools) and at run time. | |
af33b200 | 26 | For this option, you can use Cygwin. |
26abc8f0 | 27 | |
dc589dae DMSP |
28 | Native builds using Visual C++ |
29 | ============================== | |
07930a75 | 30 | |
bd28a23e | 31 | The native builds using Visual C++ have a `VC-*` prefix. |
df4c1d80 | 32 | |
dc589dae DMSP |
33 | Requirement details |
34 | ------------------- | |
df4c1d80 | 35 | |
bd28a23e | 36 | In addition to the requirements and instructions listed in `INSTALL.md`, |
dc589dae | 37 | these are required as well: |
df4c1d80 | 38 | |
dc589dae DMSP |
39 | ### Perl |
40 | ||
41 | We recommend Strawberry Perl, available from <http://strawberryperl.com/> | |
42 | Please read NOTES.PERL for more information, including the use of CPAN. | |
43 | An alternative is ActiveState Perl, <https://www.activestate.com/ActivePerl> | |
44 | for which you may need to explicitly build the Perl module Win32/Console.pm | |
45 | via <https://platform.activestate.com/ActiveState> and then download it. | |
46 | ||
47 | ### Microsoft Visual C compiler. | |
48 | ||
49 | Since these are proprietary and ever-changing we cannot test them all. | |
50 | Older versions may not work. Use a recent version wherever possible. | |
51 | ||
52 | ### Netwide Assembler (NASM) | |
53 | ||
54 | NASM is the only supported assembler. It is available from <https://www.nasm.us>. | |
55 | ||
56 | Quick start | |
57 | ----------- | |
df4c1d80 DDO |
58 | |
59 | 1. Install Perl | |
60 | ||
61 | 2. Install NASM | |
62 | ||
63 | 3. Make sure both Perl and NASM are on your %PATH% | |
64 | ||
65 | 4. Use Visual Studio Developer Command Prompt with administrative privileges, | |
66 | choosing one of its variants depending on the intended architecture. | |
bd28a23e TM |
67 | Or run `cmd` and execute `vcvarsall.bat` with one of the options `x86`, |
68 | `x86_amd64`, `x86_arm`, `x86_arm64`, `amd64`, `amd64_x86`, `amd64_arm`, | |
69 | or `amd64_arm64`. | |
70 | This sets up the environment variables needed for `nmake.exe`, `cl.exe`, | |
71 | etc. | |
474853c3 RS |
72 | See also |
73 | <https://docs.microsoft.com/cpp/build/building-on-the-command-line> | |
df4c1d80 DDO |
74 | |
75 | 5. From the root of the OpenSSL source directory enter | |
bd28a23e TM |
76 | - `perl Configure VC-WIN32` if you want 32-bit OpenSSL or |
77 | - `perl Configure VC-WIN64A` if you want 64-bit OpenSSL or | |
78 | - `perl Configure VC-WIN64-ARM` if you want Windows on Arm (win-arm64) | |
79 | OpenSSL or | |
e9460bb4 EC |
80 | - `perl Configure VC-WIN64-CLANGASM-ARM` if you want Windows on Arm (win-arm64) |
81 | OpenSSL with assembly support using clang-cl as assembler or | |
82 | - `perl Configure VC-CLANG-WIN64-CLANGASM-ARM` if you want Windows on Arm (win-arm64) | |
83 | OpenSSL using clang-cl as both compiler and assembler or | |
4a3b6266 | 84 | - `perl Configure VC-WIN32-HYBRIDCRT` if you want 32-bit OpenSSL dependent |
85 | on the Universal CRT or | |
86 | - `perl Configure VC-WIN64A-HYBRIDCRT` if you want 64-bit OpenSSL dependent | |
87 | on the Universal CRT or | |
bd28a23e | 88 | - `perl Configure` to let Configure figure out the platform |
df4c1d80 | 89 | |
bd28a23e | 90 | 6. `nmake` |
3189772e | 91 | |
bd28a23e | 92 | 7. `nmake test` |
26abc8f0 | 93 | |
bd28a23e | 94 | 8. `nmake install` |
26abc8f0 | 95 | |
dc589dae DMSP |
96 | For the full installation instructions, or if anything goes wrong at any stage, |
97 | check the INSTALL.md file. | |
b32b8961 | 98 | |
dc589dae DMSP |
99 | Installation directories |
100 | ------------------------ | |
8c16829e | 101 | |
dc589dae DMSP |
102 | The default installation directories are derived from environment |
103 | variables. | |
8c16829e | 104 | |
dc589dae | 105 | For VC-WIN32, the following defaults are use: |
8c16829e | 106 | |
70f23648 JS |
107 | PREFIX: %ProgramFiles(x86)%\OpenSSL |
108 | OPENSSLDIR: %CommonProgramFiles(x86)%\SSL | |
8c16829e | 109 | |
dc589dae | 110 | For VC-WIN64, the following defaults are use: |
8c16829e | 111 | |
dc589dae DMSP |
112 | PREFIX: %ProgramW6432%\OpenSSL |
113 | OPENSSLDIR: %CommonProgramW6432%\SSL | |
8c16829e | 114 | |
dc589dae DMSP |
115 | Should those environment variables not exist (on a pure Win32 |
116 | installation for examples), these fallbacks are used: | |
8c16829e | 117 | |
dc589dae DMSP |
118 | PREFIX: %ProgramFiles%\OpenSSL |
119 | OPENSSLDIR: %CommonProgramFiles%\SSL | |
8c16829e | 120 | |
dc589dae DMSP |
121 | ALSO NOTE that those directories are usually write protected, even if |
122 | your account is in the Administrators group. To work around that, | |
123 | start the command prompt by right-clicking on it and choosing "Run as | |
bd28a23e | 124 | Administrator" before running `nmake install`. The other solution |
dc589dae | 125 | is, of course, to choose a different set of directories by using |
bd28a23e | 126 | `--prefix` and `--openssldir` when configuring. |
8c16829e | 127 | |
bd28a23e TM |
128 | Special notes for Universal Windows Platform builds, aka `VC-*-UWP` |
129 | ------------------------------------------------------------------- | |
5ded1ca6 M |
130 | |
131 | - UWP targets only support building the static and dynamic libraries. | |
132 | ||
bd28a23e TM |
133 | - You should define the platform type to `uwp` and the target arch via |
134 | `vcvarsall.bat` before you compile. For example, if you want to build | |
135 | `arm64` builds, you should run `vcvarsall.bat x86_arm64 uwp`. | |
5ded1ca6 | 136 | |
55aa235e TI |
137 | Native builds using Embarcadero C++Builder |
138 | ========================================= | |
139 | ||
140 | This toolchain (a descendant of Turbo/Borland C++) is an alternative to MSVC. | |
5fee3fe2 | 141 | OpenSSL currently includes an experimental 32-bit configuration targeting the |
bd28a23e | 142 | Clang-based compiler (`bcc32c.exe`) in v10.3.3 Community Edition. |
55aa235e TI |
143 | <https://www.embarcadero.com/products/cbuilder/starter> |
144 | ||
145 | 1. Install Perl. | |
146 | ||
147 | 2. Open the RAD Studio Command Prompt. | |
148 | ||
149 | 3. Go to the root of the OpenSSL source directory and run: | |
bd28a23e | 150 | `perl Configure BC-32 --prefix=%CD%` |
55aa235e | 151 | |
bd28a23e | 152 | 4. `make -N` |
55aa235e | 153 | |
bd28a23e | 154 | 5. `make -N test` |
5fee3fe2 TI |
155 | |
156 | 6. Build your program against this OpenSSL: | |
55aa235e TI |
157 | * Set your include search path to the "include" subdirectory of OpenSSL. |
158 | * Set your library search path to the OpenSSL source directory. | |
159 | ||
5fee3fe2 TI |
160 | Note that this is very experimental. Support for 64-bit and other Configure |
161 | options is still pending. | |
55aa235e | 162 | |
dc589dae DMSP |
163 | Native builds using MinGW |
164 | ========================= | |
3e67b333 | 165 | |
dc589dae | 166 | MinGW offers an alternative way to build native OpenSSL, by cross compilation. |
b32b8961 | 167 | |
df4c1d80 | 168 | * Usually the build is done on Windows in a GNU-like environment called MSYS2. |
b32b8961 | 169 | |
df4c1d80 DDO |
170 | MSYS2 provides GNU tools, a Unix-like command prompt, |
171 | and a UNIX compatibility layer for applications. | |
8c1cbc72 | 172 | However, in this context it is only used for building OpenSSL. |
df4c1d80 DDO |
173 | The resulting OpenSSL does not rely on MSYS2 to run and is fully native. |
174 | ||
175 | Requirement details | |
176 | ||
474853c3 | 177 | - MSYS2 shell, from <https://www.msys2.org/> |
df4c1d80 DDO |
178 | |
179 | - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2 | |
180 | ||
bd28a23e | 181 | - make, installed using `pacman -S make` into the MSYS2 environment |
df4c1d80 | 182 | |
bd28a23e | 183 | - MinGW[64] compiler: `mingw-w64-i686-gcc` and/or `mingw-w64-x86_64-gcc`. |
df4c1d80 DDO |
184 | These compilers must be on your MSYS2 $PATH. |
185 | A common error is to not have these on your $PATH. | |
186 | The MSYS2 version of gcc will not work correctly here. | |
187 | ||
188 | In the MSYS2 shell do the configuration depending on the target architecture: | |
b32b8961 | 189 | |
dc589dae | 190 | ./Configure mingw ... |
bd28a23e | 191 | |
97a479c6 | 192 | or |
bd28a23e | 193 | |
dc589dae | 194 | ./Configure mingw64 ... |
bd28a23e | 195 | |
df4c1d80 | 196 | or |
bd28a23e | 197 | |
dc589dae DMSP |
198 | ./Configure ... |
199 | ||
df4c1d80 DDO |
200 | for the default architecture. |
201 | ||
bd28a23e | 202 | Apart from that, follow the Unix / Linux instructions in `INSTALL.md`. |
df4c1d80 DDO |
203 | |
204 | * It is also possible to build mingw[64] on Linux or Cygwin. | |
205 | ||
bd28a23e TM |
206 | In this case configure with the corresponding `--cross-compile-prefix=` |
207 | option. For example | |
b32b8961 | 208 | |
dc589dae | 209 | ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... |
bd28a23e | 210 | |
df4c1d80 | 211 | or |
bd28a23e | 212 | |
dc589dae | 213 | ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ... |
b32b8961 | 214 | |
df4c1d80 DDO |
215 | This requires that you've installed the necessary add-on packages for |
216 | mingw[64] cross compilation. | |
b32b8961 | 217 | |
dc589dae DMSP |
218 | Linking native applications |
219 | =========================== | |
220 | ||
221 | This section applies to all native builds. | |
222 | ||
af33b200 | 223 | If you link with static OpenSSL libraries, then you're expected to |
bd28a23e TM |
224 | additionally link your application with `WS2_32.LIB`, `GDI32.LIB`, |
225 | `ADVAPI32.LIB`, `CRYPT32.LIB` and `USER32.LIB`. Those developing | |
dc589dae | 226 | non-interactive service applications might feel concerned about |
bd28a23e | 227 | linking with `GDI32.LIB` and `USER32.LIB`, as they are justly associated |
dc589dae DMSP |
228 | with interactive desktop, which is not available to service |
229 | processes. The toolkit is designed to detect in which context it's | |
230 | currently executed, GUI, console app or service, and act accordingly, | |
af33b200 | 231 | namely whether to actually make GUI calls. Additionally, those |
bd28a23e | 232 | who wish to `/DELAYLOAD:GDI32.DLL` and `/DELAYLOAD:USER32.DLL` and |
dc589dae | 233 | actually keep them off service process should consider implementing |
bd28a23e TM |
234 | and exporting from .exe image in question own `_OPENSSL_isservice` not |
235 | relying on `USER32.DLL`. E.g., on Windows Vista and later you could: | |
dc589dae DMSP |
236 | |
237 | __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) | |
238 | { | |
239 | DWORD sess; | |
240 | ||
241 | if (ProcessIdToSessionId(GetCurrentProcessId(), &sess)) | |
242 | return sess == 0; | |
243 | return FALSE; | |
244 | } | |
245 | ||
246 | If you link with OpenSSL .DLLs, then you're expected to include into | |
247 | your application code a small "shim" snippet, which provides | |
248 | the glue between the OpenSSL BIO layer and your compiler run-time. | |
249 | See also the OPENSSL_Applink manual page. | |
250 | ||
251 | Hosted builds using Cygwin | |
252 | ========================== | |
253 | ||
bd28a23e | 254 | Cygwin implements a POSIX/Unix runtime system (`cygwin1.dll`) on top of the |
dc589dae DMSP |
255 | Windows subsystem and provides a Bash shell and GNU tools environment. |
256 | Consequently, a build of OpenSSL with Cygwin is virtually identical to the | |
257 | Unix procedure. | |
258 | ||
259 | To build OpenSSL using Cygwin, you need to: | |
97a479c6 | 260 | |
474853c3 | 261 | * Install Cygwin, see <https://cygwin.com/> |
97a479c6 | 262 | |
df4c1d80 DDO |
263 | * Install Cygwin Perl, at least version 5.10.0 |
264 | and ensure it is in the $PATH | |
97a479c6 | 265 | |
df4c1d80 | 266 | * Run the Cygwin Bash shell |
97a479c6 | 267 | |
dc589dae | 268 | Apart from that, follow the Unix / Linux instructions in INSTALL.md. |
97a479c6 | 269 | |
bd28a23e TM |
270 | NOTE: `make test` and normal file operations may fail in directories |
271 | mounted as text (i.e. `mount -t c:\somewhere /home`) due to Cygwin | |
af33b200 | 272 | stripping of carriage returns. To avoid this, ensure that a binary |
bd28a23e | 273 | mount is used, e.g. `mount -b c:\somewhere /home`. |