1 Notes for Windows platforms
2 ===========================
4 - [Native builds using Visual C++](#native-builds-using-visual-c++)
5 - [Native builds using MinGW](#native-builds-using-mingw)
6 - [Linking native applications](#linking-native-applications)
7 - [Hosted builds using Cygwin](#hosted-builds-using-cygwin)
10 There are various options to build and run OpenSSL on the Windows platforms.
12 "Native" OpenSSL uses the Windows APIs directly at run time.
13 To build a native OpenSSL you can either use:
15 Microsoft Visual C++ (MSVC) C compiler on the command line
18 run on the GNU-like development environment MSYS2
19 or run on Linux or Cygwin
21 "Hosted" OpenSSL relies on an external POSIX compatibility layer
22 for building (using GNU/Unix shell, compiler, and tools) and at run time.
23 For this option you can use Cygwin.
25 Native builds using Visual C++
26 ==============================
28 The native builds using Visual C++ have a VC-* prefix.
33 In addition to the requirements and instructions listed in INSTALL.md,
34 these are required as well:
38 We recommend Strawberry Perl, available from <http://strawberryperl.com/>
39 Please read NOTES.PERL for more information, including the use of CPAN.
40 An alternative is ActiveState Perl, <https://www.activestate.com/ActivePerl>
41 for which you may need to explicitly build the Perl module Win32/Console.pm
42 via <https://platform.activestate.com/ActiveState> and then download it.
44 ### Microsoft Visual C compiler.
46 Since these are proprietary and ever-changing we cannot test them all.
47 Older versions may not work. Use a recent version wherever possible.
49 ### Netwide Assembler (NASM)
51 NASM is the only supported assembler. It is available from <https://www.nasm.us>.
60 3. Make sure both Perl and NASM are on your %PATH%
62 4. Use Visual Studio Developer Command Prompt with administrative privileges,
63 choosing one of its variants depending on the intended architecture.
64 Or run "cmd" and execute "vcvarsall.bat" with one of the options x86,
65 x86_amd64, x86_arm, x86_arm64, amd64, amd64_x86, amd64_arm, or amd64_arm64.
66 This sets up the environment variables needed for nmake.exe, cl.exe, etc.
68 <https://docs.microsoft.com/cpp/build/building-on-the-command-line>
70 5. From the root of the OpenSSL source directory enter
71 perl Configure VC-WIN32 if you want 32-bit OpenSSL or
72 perl Configure VC-WIN64A if you want 64-bit OpenSSL or
73 perl Configure to let Configure figure out the platform
81 For the full installation instructions, or if anything goes wrong at any stage,
82 check the INSTALL.md file.
84 Installation directories
85 ------------------------
87 The default installation directories are derived from environment
90 For VC-WIN32, the following defaults are use:
92 PREFIX: %ProgramFiles(x86)%\OpenSSL
93 OPENSSLDIR: %CommonProgramFiles(x86)%\SSL
95 For VC-WIN64, the following defaults are use:
97 PREFIX: %ProgramW6432%\OpenSSL
98 OPENSSLDIR: %CommonProgramW6432%\SSL
100 Should those environment variables not exist (on a pure Win32
101 installation for examples), these fallbacks are used:
103 PREFIX: %ProgramFiles%\OpenSSL
104 OPENSSLDIR: %CommonProgramFiles%\SSL
106 ALSO NOTE that those directories are usually write protected, even if
107 your account is in the Administrators group. To work around that,
108 start the command prompt by right-clicking on it and choosing "Run as
109 Administrator" before running 'nmake install'. The other solution
110 is, of course, to choose a different set of directories by using
111 --prefix and --openssldir when configuring.
113 Special notes for Universal Windows Platform builds, aka VC-*-UWP
114 --------------------------------------------------------------------
116 - UWP targets only support building the static and dynamic libraries.
118 - You should define the platform type to "uwp" and the target arch via
119 "vcvarsall.bat" before you compile. For example, if you want to build
120 "arm64" builds, you should run "vcvarsall.bat x86_arm64 uwp".
122 Native builds using MinGW
123 =========================
125 MinGW offers an alternative way to build native OpenSSL, by cross compilation.
127 * Usually the build is done on Windows in a GNU-like environment called MSYS2.
129 MSYS2 provides GNU tools, a Unix-like command prompt,
130 and a UNIX compatibility layer for applications.
131 However, in this context it is only used for building OpenSSL.
132 The resulting OpenSSL does not rely on MSYS2 to run and is fully native.
136 - MSYS2 shell, from <https://www.msys2.org/>
138 - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2
140 - make, installed using "pacman -S make" into the MSYS2 environment
142 - MinGW[64] compiler: mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc.
143 These compilers must be on your MSYS2 $PATH.
144 A common error is to not have these on your $PATH.
145 The MSYS2 version of gcc will not work correctly here.
147 In the MSYS2 shell do the configuration depending on the target architecture:
149 ./Configure mingw ...
151 ./Configure mingw64 ...
155 for the default architecture.
157 Apart from that, follow the Unix / Linux instructions in INSTALL.md.
159 * It is also possible to build mingw[64] on Linux or Cygwin.
161 In this case configure with the corresponding --cross-compile-prefix= option.
164 ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
166 ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
168 This requires that you've installed the necessary add-on packages for
169 mingw[64] cross compilation.
171 Linking native applications
172 ===========================
174 This section applies to all native builds.
176 If you link with static OpenSSL libraries then you're expected to
177 additionally link your application with WS2_32.LIB, GDI32.LIB,
178 ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing
179 non-interactive service applications might feel concerned about
180 linking with GDI32.LIB and USER32.LIB, as they are justly associated
181 with interactive desktop, which is not available to service
182 processes. The toolkit is designed to detect in which context it's
183 currently executed, GUI, console app or service, and act accordingly,
184 namely whether or not to actually make GUI calls. Additionally those
185 who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and
186 actually keep them off service process should consider implementing
187 and exporting from .exe image in question own _OPENSSL_isservice not
188 relying on USER32.DLL. E.g., on Windows Vista and later you could:
190 __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void)
194 if (ProcessIdToSessionId(GetCurrentProcessId(), &sess))
199 If you link with OpenSSL .DLLs, then you're expected to include into
200 your application code a small "shim" snippet, which provides
201 the glue between the OpenSSL BIO layer and your compiler run-time.
202 See also the OPENSSL_Applink manual page.
204 Hosted builds using Cygwin
205 ==========================
207 Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the
208 Windows subsystem and provides a Bash shell and GNU tools environment.
209 Consequently, a build of OpenSSL with Cygwin is virtually identical to the
212 To build OpenSSL using Cygwin, you need to:
214 * Install Cygwin, see <https://cygwin.com/>
216 * Install Cygwin Perl, at least version 5.10.0
217 and ensure it is in the $PATH
219 * Run the Cygwin Bash shell
221 Apart from that, follow the Unix / Linux instructions in INSTALL.md.
223 NOTE: "make test" and normal file operations may fail in directories
224 mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin
225 stripping of carriage returns. To avoid this ensure that a binary
226 mount is used, e.g. mount -b c:\somewhere /home.