NOTES-Windows.txt

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