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