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