1Notes 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-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) 10 11There are various options to build and run OpenSSL on the Windows platforms. 12 13"Native" OpenSSL uses the Windows APIs directly at run time. 14To build a native OpenSSL you can either use: 15 16 Microsoft Visual C++ (MSVC) C compiler on the command line 17or 18 Embarcadero C++Builder 19or 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 25for building (using GNU/Unix shell, compiler, and tools) and at run time. 26For this option, you can use Cygwin. 27 28Native builds using Visual C++ 29============================== 30 31The native builds using Visual C++ have a `VC-*` prefix. 32 33Requirement details 34------------------- 35 36In addition to the requirements and instructions listed in `INSTALL.md`, 37these are required as well: 38 39### Perl 40 41We recommend Strawberry Perl, available from <http://strawberryperl.com/> 42Please read NOTES.PERL for more information, including the use of CPAN. 43An alternative is ActiveState Perl, <https://www.activestate.com/ActivePerl> 44for which you may need to explicitly build the Perl module Win32/Console.pm 45via <https://platform.activestate.com/ActiveState> and then download it. 46 47### Microsoft Visual C compiler. 48 49Since these are proprietary and ever-changing we cannot test them all. 50Older versions may not work. Use a recent version wherever possible. 51 52### Netwide Assembler (NASM) 53 54NASM is the only supported assembler. It is available from <https://www.nasm.us>. 55 56Quick 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`, 69 or `amd64_arm64`. 70 This sets up the environment variables needed for `nmake.exe`, `cl.exe`, 71 etc. 72 See also 73 <https://docs.microsoft.com/cpp/build/building-on-the-command-line> 74 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) 79 OpenSSL or 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 89 90 a. If you don't plan to develop OpenSSL yourself and don't need to rebuild, 91 in other words, if you always do a new build, turning off the build 92 dependency feature can speed up build times by up to 50%: 93 `perl Configure no-makedepend` 94 95 6. `nmake` 96 97 7. `nmake test` 98 99 8. `nmake install` 100 101For the full installation instructions, or if anything goes wrong at any stage, 102check the INSTALL.md file. 103 104Installation directories 105------------------------ 106 107On most Unix platforms installation directories are determined at build time via 108constant defines. On Windows platforms however, installation directories are 109determined via registry keys, as it is common practice to build OpenSSL and 110install it to a variety of locations. 111 112The following keys: 113 114 `\\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OpenSSL-<version>-<ctx>\OPENSSLDIR` 115 `\\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OpenSSL-<version>-<ctx>\ENGINESDIR` 116 `\\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OpenSSL-<version>-<ctx>\MODULESDIR` 117 118Can be administratively set, and openssl will take the paths found there as the 119values for OPENSSLDIR, ENGINESDIR and MODULESDIR respectively. 120 121To enable the reading of registry keys from windows builds, add 122`-DOSSL_WINCTX=<string>`to the Configure command line. This define is used 123at build-time to construct library build specific registry key paths of the 124format: 125`\\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432node\OpenSSL-<version>-<ctx>` 126 127Where `<version>` is the major.minor version of the library being 128built, and `<ctx>` is the value specified by `-DOPENSSL_WINCTX`. This allows 129for multiple openssl builds to be created and installed on a single system, in 130which each library can use its own set of registry keys. 131 132Note the installer available at <https://github.com/openssl/installer> will set 133these keys when the installer is run. 134 135A summary table of behavior on Windows platforms 136 137|`OSSL_WINCTX`|Registry key|OpenSSL Behavior | 138|-------------|------------|------------------------------------------| 139|Defined | Defined |OpenSSL Reads Paths from Registry | 140|Defined | Undefined |OpenSSL returns errors on module/conf load| 141|Undefined | N/A |OpenSSL uses build time defaults | 142 143Special notes for Universal Windows Platform builds, aka `VC-*-UWP` 144------------------------------------------------------------------- 145 146 - UWP targets only support building the static and dynamic libraries. 147 148 - You should define the platform type to `uwp` and the target arch via 149 `vcvarsall.bat` before you compile. For example, if you want to build 150 `arm64` builds, you should run `vcvarsall.bat x86_arm64 uwp`. 151 152Native builds using Embarcadero C++Builder 153========================================= 154 155This toolchain (a descendant of Turbo/Borland C++) is an alternative to MSVC. 156OpenSSL currently includes experimental 32-bit and 64-bit configurations targeting the 157Clang-based compiler (`bcc32c.exe` and `bcc64.exe`) in v10.3.3 Community Edition. 158<https://www.embarcadero.com/products/cbuilder/starter> 159 160 1. Install Perl. 161 162 2. Open the RAD Studio Command Prompt. 163 164 3. Go to the root of the OpenSSL source directory and run: 165 `perl Configure BC-32 --prefix=%CD%` 166 for Win64 builds use: 167 `perl Configure BC-64 --prefix=%CD%` 168 169 4. `make -N` 170 171 5. `make -N test` 172 173 6. Build your program against this OpenSSL: 174 * Set your include search path to the "include" subdirectory of OpenSSL. 175 * Set your library search path to the OpenSSL source directory. 176 177Note that this is very experimental. Support for 64-bit and other Configure 178options is still pending. 179 180Native builds using MinGW 181========================= 182 183MinGW offers an alternative way to build native OpenSSL, by cross compilation. 184 185 * Usually the build is done on Windows in a GNU-like environment called MSYS2. 186 187 MSYS2 provides GNU tools, a Unix-like command prompt, 188 and a UNIX compatibility layer for applications. 189 However, in this context it is only used for building OpenSSL. 190 The resulting OpenSSL does not rely on MSYS2 to run and is fully native. 191 192 Requirement details 193 194 - MSYS2 shell, from <https://www.msys2.org/> 195 196 - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2 197 198 - make, installed using `pacman -S make` into the MSYS2 environment 199 200 - MinGW[64] compiler: `mingw-w64-i686-gcc` and/or `mingw-w64-x86_64-gcc`. 201 These compilers must be on your MSYS2 $PATH. 202 A common error is to not have these on your $PATH. 203 The MSYS2 version of gcc will not work correctly here. 204 205 In the MSYS2 shell do the configuration depending on the target architecture: 206 207 ./Configure mingw ... 208 209 or 210 211 ./Configure mingw64 ... 212 213 or 214 215 ./Configure ... 216 217 for the default architecture. 218 219 Apart from that, follow the Unix / Linux instructions in `INSTALL.md`. 220 221 * It is also possible to build mingw[64] on Linux or Cygwin. 222 223 In this case configure with the corresponding `--cross-compile-prefix=` 224 option. For example 225 226 ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... 227 228 or 229 230 ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ... 231 232 This requires that you've installed the necessary add-on packages for 233 mingw[64] cross compilation. 234 235Linking native applications 236=========================== 237 238This section applies to all native builds. 239 240If you link with static OpenSSL libraries, then you're expected to 241additionally link your application with `WS2_32.LIB`, `GDI32.LIB`, 242`ADVAPI32.LIB`, `CRYPT32.LIB` and `USER32.LIB`. Those developing 243non-interactive service applications might feel concerned about 244linking with `GDI32.LIB` and `USER32.LIB`, as they are justly associated 245with interactive desktop, which is not available to service 246processes. The toolkit is designed to detect in which context it's 247currently executed, GUI, console app or service, and act accordingly, 248namely whether to actually make GUI calls. Additionally, those 249who wish to `/DELAYLOAD:GDI32.DLL` and `/DELAYLOAD:USER32.DLL` and 250actually keep them off service process should consider implementing 251and exporting from .exe image in question own `_OPENSSL_isservice` not 252relying on `USER32.DLL`. E.g., on Windows Vista and later you could: 253 254 __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) 255 { 256 DWORD sess; 257 258 if (ProcessIdToSessionId(GetCurrentProcessId(), &sess)) 259 return sess == 0; 260 return FALSE; 261 } 262 263If you link with OpenSSL .DLLs, then you're expected to include into 264your application code a small "shim" snippet, which provides 265the glue between the OpenSSL BIO layer and your compiler run-time. 266See also the OPENSSL_Applink manual page. 267 268Hosted builds using Cygwin 269========================== 270 271Cygwin implements a POSIX/Unix runtime system (`cygwin1.dll`) on top of the 272Windows subsystem and provides a Bash shell and GNU tools environment. 273Consequently, a build of OpenSSL with Cygwin is virtually identical to the 274Unix procedure. 275 276To build OpenSSL using Cygwin, you need to: 277 278 * Install Cygwin, see <https://cygwin.com/> 279 280 * Install Cygwin Perl, at least version 5.10.0 281 and ensure it is in the $PATH 282 283 * Run the Cygwin Bash shell 284 285Apart from that, follow the Unix / Linux instructions in INSTALL.md. 286 287NOTE: `make test` and normal file operations may fail in directories 288mounted as text (i.e. `mount -t c:\somewhere /home`) due to Cygwin 289stripping of carriage returns. To avoid this, ensure that a binary 290mount is used, e.g. `mount -b c:\somewhere /home`. 291