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