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