X-Git-Url: https://git.openssl.org/?a=blobdiff_plain;ds=sidebyside;f=NOTES.WIN;h=bc6e3d2c32d9df8d7382d385228457b372c6b36a;hb=db9592c1f723841586960912c387a925e4547a26;hp=c20427855b83e40e2ccc31ecde703f0ea06a2a00;hpb=b32b896166199b497bf98da6a5c5b50d8811851f;p=openssl.git diff --git a/NOTES.WIN b/NOTES.WIN index c20427855b..bc6e3d2c32 100644 --- a/NOTES.WIN +++ b/NOTES.WIN @@ -1,168 +1,214 @@ - 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. It is also possible to create Windows binaries that only - use the Microsoft C runtime system (msvcrt.dll or crtdll.dll) using - MinGW. MinGW can be used in the Cygwin development environment or in a - standalone setup as described in the following section. + - 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: - - * Install Cygwin (see http://cygwin.com/) + - 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 Perl and ensure it is in the path. Both Cygwin perl - (5.6.1-2 or newer) and ActivePerl work. + - Netwide Assembler (NASM), available from https://www.nasm.us + Note that NASM is the only supported assembler. - * Run the Cygwin bash shell + Quick start + ----------- - Apart from that, follow the Unix instructions in INSTALL. + 1. Install Perl - 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. + 2. Install NASM + 3. Make sure both Perl and NASM are on your %PATH% - GNU C (MinGW/MSYS) - ------------- + 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 - * Compiler and shell environment installation: + 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 - 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 on its PATH. + 6. nmake - Alternativelly, one can use MSYS2 from http://msys2.github.io/, - which includes MingW (32-bit and 64-bit). + 7. nmake test - * 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-. + 8. nmake install + For the full installation instructions, or if anything goes wrong at any stage, + check the INSTALL.md file. - Linking your application + Installation directories ------------------------ - 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: + The default installation directories are derived from environment + variables. - __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) - { DWORD sess; - if (ProcessIdToSessionId(GetCurrentProcessId(),&sess)) - return sess==0; - return FALSE; - } + For VC-WIN32, the following defaults are use: - 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. + PREFIX: %ProgramFiles(86)%\OpenSSL + OPENSSLDIR: %CommonProgramFiles(86)%\SSL + + For VC-WIN64, the following defaults are use: + PREFIX: %ProgramW6432%\OpenSSL + OPENSSLDIR: %CommonProgramW6432%\SSL - "Classic" builds (Visual C++) - ---------------- + Should those environment variables not exist (on a pure Win32 + installation for examples), these fallbacks are used: - [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. + PREFIX: %ProgramFiles%\OpenSSL + OPENSSLDIR: %CommonProgramFiles%\SSL - NOTE: this won't be available for long.] + 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. - 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%. + Special notes for Universal Windows Platform builds, a.k.a. VC-*-UWP + -------------------------------------------------------------------- - 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. + - UWP targets only support building the static and dynamic libraries. - For Win32: + - 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". - > perl Configure VC-WIN32 --classic --prefix=c:\some\openssl\dir - > ms\do_nasm - Note: replace the last line above with the following if not using the assembly - language files: + Native OpenSSL built using MinGW + ================================ - > ms\do_ms + MinGW offers an alternative way to build native OpenSSL, by cross compilation. - For Win64/x64: + * Usually the build is done on Windows in a GNU-like environment called MSYS2. - > perl Configure VC-WIN64A --classic --prefix=c:\some\openssl\dir - > ms\do_win64a + 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. - For Win64/IA64: + Requirement details - > perl Configure VC-WIN64I --classic --prefix=c:\some\openssl\dir - > ms\do_win64i + - MSYS2 shell, from https://www.msys2.org/ - Where the prefix argument specifies where OpenSSL will be installed to. + - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2 - 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. + - make, installed using "pacman -S make" into the MSYS2 environment - > nmake -f ms\ntdll.mak + - 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. - 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: + In the MSYS2 shell do the configuration depending on the target architecture: - > nmake -f ms\ntdll.mak test + ./Configure mingw ... + or + ./Configure mingw64 ... + or + ./config ... + for the default architecture. - To install OpenSSL to the specified location do: + Apart from that, follow the Unix / Linux instructions in INSTALL.md. - > nmake -f ms\ntdll.mak install + * It is also possible to build mingw[64] on Linux or Cygwin. - Tweaks: + In this case configure with the corresponding --cross-compile-prefix= option. + For example - 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. + ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... + or + ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ... - 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. + This requires that you've installed the necessary add-on packages for + mingw[64] cross compilation. - You can also build a static version of the library using the Makefile - ms\nt.mak + 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.