diff options
Diffstat (limited to 'NOTES-WINDOWS.md')
| -rw-r--r-- | NOTES-WINDOWS.md | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/NOTES-WINDOWS.md b/NOTES-WINDOWS.md new file mode 100644 index 0000000000..cb62e1d9bd --- /dev/null +++ b/NOTES-WINDOWS.md @@ -0,0 +1,214 @@ +NOTES FOR WINDOWS PLATFORMS +=========================== + + There are various options to build and run OpenSSL on the Windows platforms. + + "Native" OpenSSL uses the Windows APIs directly at run time. + To build a native OpenSSL you can either use: + + Microsoft Visual C++ (MSVC) C compiler on the command line + or + MinGW cross compiler + run on the GNU-like development environment MSYS2 + or run on Linux or Cygwin + + "Hosted" OpenSSL relies on an external POSIX compatibility layer + for building (using GNU/Unix shell, compiler, and tools) and at run time. + For this option you can use Cygwin. + + Visual C++ native builds, aka VC-* + ===================================== + + Requirement details + ------------------- + + In addition to the requirements and instructions listed in INSTALL.md, + these are required as well: + + - Perl. + We recommend Strawberry Perl, available from <http://strawberryperl.com/> + Please read NOTES.PERL for more information, including the use of CPAN. + An alternative is ActiveState Perl, <https://www.activestate.com/ActivePerl> + for which you may need to explicitly build the Perl module Win32/Console.pm + via <https://platform.activestate.com/ActiveState> and then download it. + + - Microsoft Visual C compiler. + Since these are proprietary and ever-changing we cannot test them all. + Older versions may not work. Use a recent version wherever possible. + + - Netwide Assembler (NASM), available from <https://www.nasm.us> + Note that NASM is the only supported assembler. + + Quick start + ----------- + + 1. Install Perl + + 2. Install NASM + + 3. Make sure both Perl and NASM are on your %PATH% + + 4. Use Visual Studio Developer Command Prompt with administrative privileges, + choosing one of its variants depending on the intended architecture. + Or run "cmd" and execute "vcvarsall.bat" with one of the options x86, + x86_amd64, x86_arm, x86_arm64, amd64, amd64_x86, amd64_arm, or amd64_arm64. + This sets up the environment variables needed for nmake.exe, cl.exe, etc. + See also + <https://docs.microsoft.com/cpp/build/building-on-the-command-line> + + 5. From the root of the OpenSSL source directory enter + perl Configure VC-WIN32 if you want 32-bit OpenSSL or + perl Configure VC-WIN64A if you want 64-bit OpenSSL or + perl Configure to let Configure figure out the platform + + 6. nmake + + 7. nmake test + + 8. nmake install + + For the full installation instructions, or if anything goes wrong at any stage, + check the INSTALL.md file. + + Installation directories + ------------------------ + + The default installation directories are derived from environment + variables. + + For VC-WIN32, the following defaults are use: + + PREFIX: %ProgramFiles(86)%\OpenSSL + OPENSSLDIR: %CommonProgramFiles(86)%\SSL + + For VC-WIN64, the following defaults are use: + + PREFIX: %ProgramW6432%\OpenSSL + OPENSSLDIR: %CommonProgramW6432%\SSL + + Should those environment variables not exist (on a pure Win32 + installation for examples), these fallbacks are used: + + PREFIX: %ProgramFiles%\OpenSSL + OPENSSLDIR: %CommonProgramFiles%\SSL + + ALSO NOTE that those directories are usually write protected, even if + your account is in the Administrators group. To work around that, + start the command prompt by right-clicking on it and choosing "Run as + Administrator" before running 'nmake install'. The other solution + is, of course, to choose a different set of directories by using + --prefix and --openssldir when configuring. + + Special notes for Universal Windows Platform builds, aka VC-*-UWP + -------------------------------------------------------------------- + + - UWP targets only support building the static and dynamic libraries. + + - You should define the platform type to "uwp" and the target arch via + "vcvarsall.bat" before you compile. For example, if you want to build + "arm64" builds, you should run "vcvarsall.bat x86_arm64 uwp". + + Native OpenSSL built using MinGW + ================================ + + MinGW offers an alternative way to build native OpenSSL, by cross compilation. + + * Usually the build is done on Windows in a GNU-like environment called MSYS2. + + MSYS2 provides GNU tools, a Unix-like command prompt, + and a UNIX compatibility layer for applications. + However, in this context it is only used for building OpenSSL. + The resulting OpenSSL does not rely on MSYS2 to run and is fully native. + + Requirement details + + - MSYS2 shell, from <https://www.msys2.org/> + + - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2 + + - make, installed using "pacman -S make" into the MSYS2 environment + + - MinGW[64] compiler: mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc. + These compilers must be on your MSYS2 $PATH. + A common error is to not have these on your $PATH. + The MSYS2 version of gcc will not work correctly here. + + In the MSYS2 shell do the configuration depending on the target architecture: + + ./Configure mingw ... + or + ./Configure mingw64 ... + or + ./Configure ... + for the default architecture. + + Apart from that, follow the Unix / Linux instructions in INSTALL.md. + + * It is also possible to build mingw[64] on Linux or Cygwin. + + In this case configure with the corresponding --cross-compile-prefix= option. + For example + + ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... + or + ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ... + + This requires that you've installed the necessary add-on packages for + mingw[64] cross compilation. + + Linking your application + ======================== + + This section applies to all "native" builds. + + If you link with static OpenSSL libraries then you're expected to + additionally link your application with WS2_32.LIB, GDI32.LIB, + ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing + non-interactive service applications might feel concerned about + linking with GDI32.LIB and USER32.LIB, as they are justly associated + with interactive desktop, which is not available to service + processes. The toolkit is designed to detect in which context it's + currently executed, GUI, console app or service, and act accordingly, + namely whether or not to actually make GUI calls. Additionally those + who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and + actually keep them off service process should consider implementing + and exporting from .exe image in question own _OPENSSL_isservice not + relying on USER32.DLL. E.g., on Windows Vista and later you could: + + __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) + { + DWORD sess; + + if (ProcessIdToSessionId(GetCurrentProcessId(), &sess)) + return sess == 0; + return FALSE; + } + + If you link with OpenSSL .DLLs, then you're expected to include into + your application code a small "shim" snippet, which provides + the glue between the OpenSSL BIO layer and your compiler run-time. + See also the OPENSSL_Applink manual page. + + Hosted OpenSSL built using Cygwin + ================================= + + Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the + Windows subsystem and provides a Bash shell and GNU tools environment. + Consequently, a build of OpenSSL with Cygwin is virtually identical to the + Unix procedure. + + To build OpenSSL using Cygwin, you need to: + + * Install Cygwin, see <https://cygwin.com/> + + * Install Cygwin Perl, at least version 5.10.0 + and ensure it is in the $PATH + + * Run the Cygwin Bash shell + + Apart from that, follow the Unix / Linux instructions in INSTALL.md. + + NOTE: "make test" and normal file operations may fail in directories + mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin + stripping of carriage returns. To avoid this ensure that a binary + mount is used, e.g. mount -b c:\somewhere /home. |