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