- NOTES FOR THE WINDOWS PLATFORMS
- ===============================
+ NOTES FOR WINDOWS PLATFORMS
+ ===========================
- [Notes for Windows CE can be found in INSTALL.WCE]
+ There are various options to build and run OpenSSL on the Windows platforms.
- Requirement details for native (Visual C++) builds
- --------------------------------------------------
+ "Native" OpenSSL uses the Windows APIs directly at run time.
+ To build a native OpenSSL you can either use:
- - You need Perl. We recommend ActiveState Perl, available from
- http://www.activestate.com/ActivePerl.
- You also need the perl module Text::Template, available on CPAN.
- Please read README.PERL for more information.
+ 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
- - You need a C compiler. OpenSSL has been tested to build with these:
+ "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++
- - Netwide Assembler, a.k.a. NASM, available from http://www.nasm.us,
- is required if you intend to utilize assembler modules. Note that NASM
- is the only supported assembler. The Microsoft provided assembler is NOT
- supported.
+ Visual C++ native builds, a.k.a. VC-*
+ =====================================
+ Requirement details
+ -------------------
- GNU C (Cygwin)
- --------------
+ In addition to the requirements and instructions listed in INSTALL.md,
+ these are required as well:
- 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 make of OpenSSL with Cygwin is virtually identical to the
- Unix procedure.
+ - 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.
- To build OpenSSL using Cygwin, you need to:
+ - 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.
- * Install Cygwin (see http://cygwin.com/)
+ - Netwide Assembler (NASM), available from https://www.nasm.us
+ Note that NASM is the only supported assembler.
- * Install Cygwin Perl and ensure it is in the path. Recall that
- as least 5.10.0 is required.
+ Quick start
+ -----------
- * Run the Cygwin bash shell
+ 1. Install Perl
- Apart from that, follow the Unix instructions in INSTALL.
+ 2. Install NASM
- 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.
+ 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
- It is also possible to create "conventional" Windows binaries that use
- the Microsoft C runtime system (msvcrt.dll or crtdll.dll) using MinGW
- development add-on for Cygwin. MinGW is supported even as a standalone
- setup as described in the following section. In the context you should
- recognize that binaries targeting Cygwin itself are not interchangeable
- with "conventional" Windows binaries you generate with/for MinGW.
+ 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
- GNU C (MinGW/MSYS)
- -------------
+ 6. nmake
- * Compiler and shell environment installation:
+ 7. nmake test
- MinGW and MSYS are available from http://www.mingw.org/, both are
- required. Run the installers and do whatever magic they say it takes
- to start MSYS bash shell with GNU tools and matching Perl on its PATH.
- "Matching Perl" refers to chosen "shell environment", i.e. if built
- under MSYS, then Perl compiled for MSYS is highly recommended.
+ 8. nmake install
- Alternativelly, one can use MSYS2 from http://msys2.github.io/,
- which includes MingW (32-bit and 64-bit).
+ For the full installation instructions, or if anything goes wrong at any stage,
+ check the INSTALL.md file.
- * It is also possible to cross-compile it on Linux by configuring
- with './Configure --cross-compile-prefix=i386-mingw32- mingw ...'.
- Other possible cross compile prefixes include x86_64-w64-mingw32-
- and i686-w64-mingw32-.
+ 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:
- "Classic" builds (Visual C++)
- ----------------
+ PREFIX: %ProgramW6432%\OpenSSL
+ OPENSSLDIR: %CommonProgramW6432%\SSL
- [OpenSSL was classically built using a script called mk1mf. This is
- still available by configuring with --classic. The notes below are
- using this flag, and are tentative. Use with care.
+ Should those environment variables not exist (on a pure Win32
+ installation for examples), these fallbacks are used:
- NOTE: this won't be available for long.]
+ PREFIX: %ProgramFiles%\OpenSSL
+ OPENSSLDIR: %CommonProgramFiles%\SSL
- If you want to compile in the assembly language routines with Visual
- C++, then you will need the Netwide Assembler binary, nasmw.exe or nasm.exe, to
- be available on your %PATH%.
+ 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.
- Firstly you should run Configure and generate the Makefiles. If you don't want
- the assembly language files then add the "no-asm" option (without quotes) to
- the Configure lines below.
+ Special notes for Universal Windows Platform builds, a.k.a. VC-*-UWP
+ --------------------------------------------------------------------
- For Win32:
+ - UWP targets only support building the static and dynamic libraries.
- > perl Configure VC-WIN32 --classic --prefix=c:\some\openssl\dir
- > ms\do_nasm
+ - 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".
- Note: replace the last line above with the following if not using the assembly
- language files:
- > ms\do_ms
+ Native OpenSSL built using MinGW
+ ================================
- For Win64/x64:
+ MinGW offers an alternative way to build native OpenSSL, by cross compilation.
- > perl Configure VC-WIN64A --classic --prefix=c:\some\openssl\dir
- > ms\do_win64a
+ * Usually the build is done on Windows in a GNU-like environment called MSYS2.
- For Win64/IA64:
+ 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.
- > perl Configure VC-WIN64I --classic --prefix=c:\some\openssl\dir
- > ms\do_win64i
+ Requirement details
- Where the prefix argument specifies where OpenSSL will be installed to.
+ - MSYS2 shell, from https://www.msys2.org/
- Then from the VC++ environment at a prompt do the following. Note, your %PATH%
- and other environment variables should be set up for 32-bit or 64-bit
- development as appropriate.
+ - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2
- > nmake -f ms\ntdll.mak
+ - make, installed using "pacman -S make" into the MSYS2 environment
- If all is well it should compile and you will have some DLLs and
- executables in out32dll. If you want to try the tests then do:
+ - 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.
- > nmake -f ms\ntdll.mak test
+ In the MSYS2 shell do the configuration depending on the target architecture:
- To install OpenSSL to the specified location do:
+ ./Configure mingw ...
+ or
+ ./Configure mingw64 ...
+ or
+ ./config ...
+ for the default architecture.
- > nmake -f ms\ntdll.mak install
+ Apart from that, follow the Unix / Linux instructions in INSTALL.md.
- Tweaks:
+ * It is also possible to build mingw[64] on Linux or Cygwin.
- There are various changes you can make to the Windows compile
- environment. By default the library is not compiled with debugging
- symbols. If you add --debug to the Configure lines above then debugging symbols
- will be compiled in.
+ In this case configure with the corresponding --cross-compile-prefix= option.
+ For example
- By default in 1.1.0 OpenSSL will compile builtin ENGINES into separate shared
- libraries. If you specify the "enable-static-engine" option on the command line
- to Configure the shared library build (ms\ntdll.mak) will compile the engines
- into libcrypto32.dll instead.
+ ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
+ or
+ ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
- You can also build a static version of the library using the Makefile
- ms\nt.mak
+ This requires that you've installed the necessary add-on packages for
+ mingw[64] cross compilation.
Linking your application
- ------------------------
+ ========================
- This section applies to non-Cygwin builds.
+ 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, ADVAPI32.LIB,
- GDI32.LIB and USER32.LIB. Those developing non-interactive service
- applications might feel concerned about linking with the latter two,
- 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:
+ 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 you link with OpenSSL .DLLs, then you're expected to include into
- your application code small "shim" snippet, which provides glue between
- OpenSSL BIO layer and your compiler run-time. See the OPENSSL_Applink
- manual page for further details.
+ 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.
projects / openssl.git / blobdiff