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 MinGW](#native-builds-using-mingw)
   6  - [Linking native applications](#linking-native-applications)
   7  - [Hosted builds using Cygwin](#hosted-builds-using-cygwin)
   8
   9
  10 There are various options to build and run OpenSSL on the Windows platforms.
  11
  12 "Native" OpenSSL uses the Windows APIs directly at run time.
  13 To build a native OpenSSL you can either use:
  14
  15     Microsoft Visual C++ (MSVC) C compiler on the command line
  16 or
  17     MinGW cross compiler
  18     run on the GNU-like development environment MSYS2
  19     or run on Linux or Cygwin
  20
  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.
  24
  25 Native builds using Visual C++
  26 ==============================
  27
  28 The native builds using Visual C++ have a VC-* prefix.
  29
  30 Requirement details
  31 -------------------
  32
  33 In addition to the requirements and instructions listed in INSTALL.md,
  34 these are required as well:
  35
  36 ### Perl
  37
  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.
  43
  44 ### Microsoft Visual C compiler.
  45
  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.
  48
  49 ### Netwide Assembler (NASM)
  50
  51 NASM is the only supported assembler. It is available from <https://www.nasm.us>.
  52
  53 Quick start
  54 -----------
  55
  56  1. Install Perl
  57
  58  2. Install NASM
  59
  60  3. Make sure both Perl and NASM are on your %PATH%
  61
  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.
  67     See also
  68     <https://docs.microsoft.com/cpp/build/building-on-the-command-line>
  69
  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
  74
  75  6. nmake
  76
  77  7. nmake test
  78
  79  8. nmake install
  80
  81 For the full installation instructions, or if anything goes wrong at any stage,
  82 check the INSTALL.md file.
  83
  84 Installation directories
  85 ------------------------
  86
  87 The default installation directories are derived from environment
  88 variables.
  89
  90 For VC-WIN32, the following defaults are use:
  91
  92     PREFIX:      %ProgramFiles(x86)%\OpenSSL
  93     OPENSSLDIR:  %CommonProgramFiles(x86)%\SSL
  94
  95 For VC-WIN64, the following defaults are use:
  96
  97     PREFIX:      %ProgramW6432%\OpenSSL
  98     OPENSSLDIR:  %CommonProgramW6432%\SSL
  99
 100 Should those environment variables not exist (on a pure Win32
 101 installation for examples), these fallbacks are used:
 102
 103     PREFIX:      %ProgramFiles%\OpenSSL
 104     OPENSSLDIR:  %CommonProgramFiles%\SSL
 105
 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.
 112
 113 Special notes for Universal Windows Platform builds, aka VC-*-UWP
 114 --------------------------------------------------------------------
 115
 116  - UWP targets only support building the static and dynamic libraries.
 117
 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".
 121
 122 Native builds using MinGW
 123 =========================
 124
 125 MinGW offers an alternative way to build native OpenSSL, by cross compilation.
 126
 127  * Usually the build is done on Windows in a GNU-like environment called MSYS2.
 128
 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.
 133
 134    Requirement details
 135
 136    - MSYS2 shell, from <https://www.msys2.org/>
 137
 138    - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2
 139
 140    - make, installed using "pacman -S make" into the MSYS2 environment
 141
 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.
 146
 147    In the MSYS2 shell do the configuration depending on the target architecture:
 148
 149        ./Configure mingw ...
 150    or
 151        ./Configure mingw64 ...
 152    or
 153        ./Configure ...
 154
 155    for the default architecture.
 156
 157    Apart from that, follow the Unix / Linux instructions in INSTALL.md.
 158
 159  * It is also possible to build mingw[64] on Linux or Cygwin.
 160
 161    In this case configure with the corresponding --cross-compile-prefix= option.
 162    For example
 163
 164        ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
 165    or
 166        ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
 167
 168    This requires that you've installed the necessary add-on packages for
 169    mingw[64] cross compilation.
 170
 171 Linking native applications
 172 ===========================
 173
 174 This section applies to all native builds.
 175
 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:
 189
 190        __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void)
 191        {
 192            DWORD sess;
 193
 194            if (ProcessIdToSessionId(GetCurrentProcessId(), &sess))
 195                return sess == 0;
 196            return FALSE;
 197        }
 198
 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.
 203
 204 Hosted builds using Cygwin
 205 ==========================
 206
 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
 210 Unix procedure.
 211
 212 To build OpenSSL using Cygwin, you need to:
 213
 214  * Install Cygwin, see <https://cygwin.com/>
 215
 216  * Install Cygwin Perl, at least version 5.10.0
 217    and ensure it is in the $PATH
 218
 219  * Run the Cygwin Bash shell
 220
 221 Apart from that, follow the Unix / Linux instructions in INSTALL.md.
 222
 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.