NOTES-WINDOWS.md

   1 Notes 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
  11
  12 There are various options to build and run OpenSSL on the Windows platforms.
  13
  14 "Native" OpenSSL uses the Windows APIs directly at run time.
  15 To build a native OpenSSL you can either use:
  16
  17     Microsoft Visual C++ (MSVC) C compiler on the command line
  18 or
  19     Embarcadero C++Builder
  20 or
  21     MinGW cross compiler
  22     run on the GNU-like development environment MSYS2
  23     or run on Linux or Cygwin
  24
  25 "Hosted" OpenSSL relies on an external POSIX compatibility layer
  26 for building (using GNU/Unix shell, compiler, and tools) and at run time.
  27 For this option you can use Cygwin.
  28
  29 Native builds using Visual C++
  30 ==============================
  31
  32 The native builds using Visual C++ have a VC-* prefix.
  33
  34 Requirement details
  35 -------------------
  36
  37 In addition to the requirements and instructions listed in INSTALL.md,
  38 these are required as well:
  39
  40 ### Perl
  41
  42 We recommend Strawberry Perl, available from <http://strawberryperl.com/>
  43 Please read NOTES.PERL for more information, including the use of CPAN.
  44 An alternative is ActiveState Perl, <https://www.activestate.com/ActivePerl>
  45 for which you may need to explicitly build the Perl module Win32/Console.pm
  46 via <https://platform.activestate.com/ActiveState> and then download it.
  47
  48 ### Microsoft Visual C compiler.
  49
  50 Since these are proprietary and ever-changing we cannot test them all.
  51 Older versions may not work. Use a recent version wherever possible.
  52
  53 ### Netwide Assembler (NASM)
  54
  55 NASM is the only supported assembler. It is available from <https://www.nasm.us>.
  56
  57 Quick start
  58 -----------
  59
  60  1. Install Perl
  61
  62  2. Install NASM
  63
  64  3. Make sure both Perl and NASM are on your %PATH%
  65
  66  4. Use Visual Studio Developer Command Prompt with administrative privileges,
  67     choosing one of its variants depending on the intended architecture.
  68     Or run "cmd" and execute "vcvarsall.bat" with one of the options x86,
  69     x86_amd64, x86_arm, x86_arm64, amd64, amd64_x86, amd64_arm, or amd64_arm64.
  70     This sets up the environment variables needed for nmake.exe, cl.exe, etc.
  71     See also
  72     <https://docs.microsoft.com/cpp/build/building-on-the-command-line>
  73
  74  5. From the root of the OpenSSL source directory enter
  75     perl Configure VC-WIN32    if you want 32-bit OpenSSL or
  76     perl Configure VC-WIN64A   if you want 64-bit OpenSSL or
  77     perl Configure             to let Configure figure out the platform
  78
  79  6. nmake
  80
  81  7. nmake test
  82
  83  8. nmake install
  84
  85 For the full installation instructions, or if anything goes wrong at any stage,
  86 check the INSTALL.md file.
  87
  88 Installation directories
  89 ------------------------
  90
  91 The default installation directories are derived from environment
  92 variables.
  93
  94 For VC-WIN32, the following defaults are use:
  95
  96     PREFIX:      %ProgramFiles(x86)%\OpenSSL
  97     OPENSSLDIR:  %CommonProgramFiles(x86)%\SSL
  98
  99 For VC-WIN64, the following defaults are use:
 100
 101     PREFIX:      %ProgramW6432%\OpenSSL
 102     OPENSSLDIR:  %CommonProgramW6432%\SSL
 103
 104 Should those environment variables not exist (on a pure Win32
 105 installation for examples), these fallbacks are used:
 106
 107     PREFIX:      %ProgramFiles%\OpenSSL
 108     OPENSSLDIR:  %CommonProgramFiles%\SSL
 109
 110 ALSO NOTE that those directories are usually write protected, even if
 111 your account is in the Administrators group.  To work around that,
 112 start the command prompt by right-clicking on it and choosing "Run as
 113 Administrator" before running 'nmake install'.  The other solution
 114 is, of course, to choose a different set of directories by using
 115 --prefix and --openssldir when configuring.
 116
 117 Special notes for Universal Windows Platform builds, aka VC-*-UWP
 118 --------------------------------------------------------------------
 119
 120  - UWP targets only support building the static and dynamic libraries.
 121
 122  - You should define the platform type to "uwp" and the target arch via
 123    "vcvarsall.bat" before you compile. For example, if you want to build
 124    "arm64" builds, you should run "vcvarsall.bat x86_arm64 uwp".
 125
 126 Native builds using Embarcadero C++Builder
 127 =========================================
 128
 129 This toolchain (a descendant of Turbo/Borland C++) is an alternative to MSVC.
 130 OpenSSL currently includes an experimental 32-bit static-build configuration
 131 targeting the Clang-based compiler (bcc32c.exe) in v10.3.3 Community Edition.
 132 <https://www.embarcadero.com/products/cbuilder/starter>
 133
 134  1. Install Perl.
 135
 136  2. Open the RAD Studio Command Prompt.
 137
 138  3. Go to the root of the OpenSSL source directory and run:
 139     perl Configure BC-32 --prefix=%CD%
 140
 141  4. make -N
 142
 143  5. Build your program against this OpenSSL:
 144     * Set your include search path to the "include" subdirectory of OpenSSL.
 145     * Set your library search path to the OpenSSL source directory.
 146
 147 Note that this is very experimental. Support for 64-bit, dynamic library, and
 148 other Configure options is still pending.
 149
 150 Native builds using MinGW
 151 =========================
 152
 153 MinGW offers an alternative way to build native OpenSSL, by cross compilation.
 154
 155  * Usually the build is done on Windows in a GNU-like environment called MSYS2.
 156
 157    MSYS2 provides GNU tools, a Unix-like command prompt,
 158    and a UNIX compatibility layer for applications.
 159    However, in this context it is only used for building OpenSSL.
 160    The resulting OpenSSL does not rely on MSYS2 to run and is fully native.
 161
 162    Requirement details
 163
 164    - MSYS2 shell, from <https://www.msys2.org/>
 165
 166    - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2
 167
 168    - make, installed using "pacman -S make" into the MSYS2 environment
 169
 170    - MinGW[64] compiler: mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc.
 171      These compilers must be on your MSYS2 $PATH.
 172      A common error is to not have these on your $PATH.
 173      The MSYS2 version of gcc will not work correctly here.
 174
 175    In the MSYS2 shell do the configuration depending on the target architecture:
 176
 177        ./Configure mingw ...
 178    or
 179        ./Configure mingw64 ...
 180    or
 181        ./Configure ...
 182
 183    for the default architecture.
 184
 185    Apart from that, follow the Unix / Linux instructions in INSTALL.md.
 186
 187  * It is also possible to build mingw[64] on Linux or Cygwin.
 188
 189    In this case configure with the corresponding --cross-compile-prefix= option.
 190    For example
 191
 192        ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
 193    or
 194        ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
 195
 196    This requires that you've installed the necessary add-on packages for
 197    mingw[64] cross compilation.
 198
 199 Linking native applications
 200 ===========================
 201
 202 This section applies to all native builds.
 203
 204 If you link with static OpenSSL libraries then you're expected to
 205 additionally link your application with WS2_32.LIB, GDI32.LIB,
 206 ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing
 207 non-interactive service applications might feel concerned about
 208 linking with GDI32.LIB and USER32.LIB, as they are justly associated
 209 with interactive desktop, which is not available to service
 210 processes. The toolkit is designed to detect in which context it's
 211 currently executed, GUI, console app or service, and act accordingly,
 212 namely whether or not to actually make GUI calls. Additionally those
 213 who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and
 214 actually keep them off service process should consider implementing
 215 and exporting from .exe image in question own _OPENSSL_isservice not
 216 relying on USER32.DLL. E.g., on Windows Vista and later you could:
 217
 218        __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void)
 219        {
 220            DWORD sess;
 221
 222            if (ProcessIdToSessionId(GetCurrentProcessId(), &sess))
 223                return sess == 0;
 224            return FALSE;
 225        }
 226
 227 If you link with OpenSSL .DLLs, then you're expected to include into
 228 your application code a small "shim" snippet, which provides
 229 the glue between the OpenSSL BIO layer and your compiler run-time.
 230 See also the OPENSSL_Applink manual page.
 231
 232 Hosted builds using Cygwin
 233 ==========================
 234
 235 Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the
 236 Windows subsystem and provides a Bash shell and GNU tools environment.
 237 Consequently, a build of OpenSSL with Cygwin is virtually identical to the
 238 Unix procedure.
 239
 240 To build OpenSSL using Cygwin, you need to:
 241
 242  * Install Cygwin, see <https://cygwin.com/>
 243
 244  * Install Cygwin Perl, at least version 5.10.0
 245    and ensure it is in the $PATH
 246
 247  * Run the Cygwin Bash shell
 248
 249 Apart from that, follow the Unix / Linux instructions in INSTALL.md.
 250
 251 NOTE: "make test" and normal file operations may fail in directories
 252 mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin
 253 stripping of carriage returns. To avoid this ensure that a binary
 254 mount is used, e.g. mount -b c:\somewhere /home.