1 Notes for Windows platforms
2 ===========================
4 - [Native builds using Visual C++](#native-builds-using-visual-c)
5 - [Native builds using Embarcadero C++Builder](
6 #native-builds-using-embarcadero-cbuilder)
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)
11 There are various options to build and run OpenSSL on the Windows platforms.
13 "Native" OpenSSL uses the Windows APIs directly at run time.
14 To build a native OpenSSL you can either use:
16 Microsoft Visual C++ (MSVC) C compiler on the command line
18 Embarcadero C++Builder
21 run on the GNU-like development environment MSYS2
22 or run on Linux or Cygwin
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.
28 Native builds using Visual C++
29 ==============================
31 The native builds using Visual C++ have a `VC-*` prefix.
36 In addition to the requirements and instructions listed in `INSTALL.md`,
37 these are required as well:
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.
47 ### Microsoft Visual C compiler.
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.
52 ### Netwide Assembler (NASM)
54 NASM is the only supported assembler. It is available from <https://www.nasm.us>.
63 3. Make sure both Perl and NASM are on your %PATH%
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`,
70 This sets up the environment variables needed for `nmake.exe`, `cl.exe`,
73 <https://docs.microsoft.com/cpp/build/building-on-the-command-line>
75 5. From the root of the OpenSSL source directory enter
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)
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
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
88 - `perl Configure` to let Configure figure out the platform
96 For the full installation instructions, or if anything goes wrong at any stage,
97 check the INSTALL.md file.
99 Installation directories
100 ------------------------
102 The default installation directories are derived from environment
105 For VC-WIN32, the following defaults are use:
107 PREFIX: %ProgramFiles(x86)%\OpenSSL
108 OPENSSLDIR: %CommonProgramFiles(x86)%\SSL
110 For VC-WIN64, the following defaults are use:
112 PREFIX: %ProgramW6432%\OpenSSL
113 OPENSSLDIR: %CommonProgramW6432%\SSL
115 Should those environment variables not exist (on a pure Win32
116 installation for examples), these fallbacks are used:
118 PREFIX: %ProgramFiles%\OpenSSL
119 OPENSSLDIR: %CommonProgramFiles%\SSL
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
124 Administrator" before running `nmake install`. The other solution
125 is, of course, to choose a different set of directories by using
126 `--prefix` and `--openssldir` when configuring.
128 Special notes for Universal Windows Platform builds, aka `VC-*-UWP`
129 -------------------------------------------------------------------
131 - UWP targets only support building the static and dynamic libraries.
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`.
137 Native builds using Embarcadero C++Builder
138 =========================================
140 This toolchain (a descendant of Turbo/Borland C++) is an alternative to MSVC.
141 OpenSSL currently includes an experimental 32-bit configuration targeting the
142 Clang-based compiler (`bcc32c.exe`) in v10.3.3 Community Edition.
143 <https://www.embarcadero.com/products/cbuilder/starter>
147 2. Open the RAD Studio Command Prompt.
149 3. Go to the root of the OpenSSL source directory and run:
150 `perl Configure BC-32 --prefix=%CD%`
156 6. Build your program against this OpenSSL:
157 * Set your include search path to the "include" subdirectory of OpenSSL.
158 * Set your library search path to the OpenSSL source directory.
160 Note that this is very experimental. Support for 64-bit and other Configure
161 options is still pending.
163 Native builds using MinGW
164 =========================
166 MinGW offers an alternative way to build native OpenSSL, by cross compilation.
168 * Usually the build is done on Windows in a GNU-like environment called MSYS2.
170 MSYS2 provides GNU tools, a Unix-like command prompt,
171 and a UNIX compatibility layer for applications.
172 However, in this context it is only used for building OpenSSL.
173 The resulting OpenSSL does not rely on MSYS2 to run and is fully native.
177 - MSYS2 shell, from <https://www.msys2.org/>
179 - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2
181 - make, installed using `pacman -S make` into the MSYS2 environment
183 - MinGW[64] compiler: `mingw-w64-i686-gcc` and/or `mingw-w64-x86_64-gcc`.
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.
188 In the MSYS2 shell do the configuration depending on the target architecture:
190 ./Configure mingw ...
194 ./Configure mingw64 ...
200 for the default architecture.
202 Apart from that, follow the Unix / Linux instructions in `INSTALL.md`.
204 * It is also possible to build mingw[64] on Linux or Cygwin.
206 In this case configure with the corresponding `--cross-compile-prefix=`
209 ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
213 ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
215 This requires that you've installed the necessary add-on packages for
216 mingw[64] cross compilation.
218 Linking native applications
219 ===========================
221 This section applies to all native builds.
223 If you link with static OpenSSL libraries, then you're expected to
224 additionally link your application with `WS2_32.LIB`, `GDI32.LIB`,
225 `ADVAPI32.LIB`, `CRYPT32.LIB` and `USER32.LIB`. Those developing
226 non-interactive service applications might feel concerned about
227 linking with `GDI32.LIB` and `USER32.LIB`, as they are justly associated
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,
231 namely whether to actually make GUI calls. Additionally, those
232 who wish to `/DELAYLOAD:GDI32.DLL` and `/DELAYLOAD:USER32.DLL` and
233 actually keep them off service process should consider implementing
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:
237 __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void)
241 if (ProcessIdToSessionId(GetCurrentProcessId(), &sess))
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.
251 Hosted builds using Cygwin
252 ==========================
254 Cygwin implements a POSIX/Unix runtime system (`cygwin1.dll`) on top of the
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
259 To build OpenSSL using Cygwin, you need to:
261 * Install Cygwin, see <https://cygwin.com/>
263 * Install Cygwin Perl, at least version 5.10.0
264 and ensure it is in the $PATH
266 * Run the Cygwin Bash shell
268 Apart from that, follow the Unix / Linux instructions in INSTALL.md.
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
272 stripping of carriage returns. To avoid this, ensure that a binary
273 mount is used, e.g. `mount -b c:\somewhere /home`.