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, 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 84For the full installation instructions, or if anything goes wrong at any stage, 85check the INSTALL.md file. 86 87Installation directories 88------------------------ 89 90The default installation directories are derived from environment 91variables. 92 93For VC-WIN32, the following defaults are use: 94 95 PREFIX: %ProgramFiles(x86)%\OpenSSL 96 OPENSSLDIR: %CommonProgramFiles(x86)%\SSL 97 98For VC-WIN64, the following defaults are use: 99 100 PREFIX: %ProgramW6432%\OpenSSL 101 OPENSSLDIR: %CommonProgramW6432%\SSL 102 103Should those environment variables not exist (on a pure Win32 104installation for examples), these fallbacks are used: 105 106 PREFIX: %ProgramFiles%\OpenSSL 107 OPENSSLDIR: %CommonProgramFiles%\SSL 108 109ALSO NOTE that those directories are usually write protected, even if 110your account is in the Administrators group. To work around that, 111start the command prompt by right-clicking on it and choosing "Run as 112Administrator" before running 'nmake install'. The other solution 113is, of course, to choose a different set of directories by using 114--prefix and --openssldir when configuring. 115 116Special 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 125Native builds using Embarcadero C++Builder 126========================================= 127 128This toolchain (a descendant of Turbo/Borland C++) is an alternative to MSVC. 129OpenSSL currently includes an experimental 32-bit configuration targeting the 130Clang-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 148Note that this is very experimental. Support for 64-bit and other Configure 149options is still pending. 150 151Native builds using MinGW 152========================= 153 154MinGW 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 200Linking native applications 201=========================== 202 203This section applies to all native builds. 204 205If you link with static OpenSSL libraries then you're expected to 206additionally link your application with WS2_32.LIB, GDI32.LIB, 207ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing 208non-interactive service applications might feel concerned about 209linking with GDI32.LIB and USER32.LIB, as they are justly associated 210with interactive desktop, which is not available to service 211processes. The toolkit is designed to detect in which context it's 212currently executed, GUI, console app or service, and act accordingly, 213namely whether or not to actually make GUI calls. Additionally those 214who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and 215actually keep them off service process should consider implementing 216and exporting from .exe image in question own _OPENSSL_isservice not 217relying 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 228If you link with OpenSSL .DLLs, then you're expected to include into 229your application code a small "shim" snippet, which provides 230the glue between the OpenSSL BIO layer and your compiler run-time. 231See also the OPENSSL_Applink manual page. 232 233Hosted builds using Cygwin 234========================== 235 236Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the 237Windows subsystem and provides a Bash shell and GNU tools environment. 238Consequently, a build of OpenSSL with Cygwin is virtually identical to the 239Unix procedure. 240 241To 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 250Apart from that, follow the Unix / Linux instructions in INSTALL.md. 251 252NOTE: "make test" and normal file operations may fail in directories 253mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin 254stripping of carriage returns. To avoid this ensure that a binary 255mount is used, e.g. mount -b c:\somewhere /home. 256