X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=NOTES.WIN;h=4d39d06f32ad10229318708c80d9454157ff234b;hp=969923914ae9bd9ab5270647f3bb201b8ae62b65;hb=ed48d2032d29a82c6aebbddf0fbf530ac2d2521d;hpb=ad839325e13fe7541d248a88d6cf3556787b0e02 diff --git a/NOTES.WIN b/NOTES.WIN index 969923914a..4d39d06f32 100644 --- a/NOTES.WIN +++ b/NOTES.WIN @@ -2,164 +2,131 @@ NOTES FOR THE WINDOWS PLATFORMS =============================== - [Notes for Windows CE can be found in INSTALL.WCE] - - Requirement details for native (Visual C++) builds - -------------------------------------------------- - - - You need Perl. We recommend ActiveState Perl, available from - http://www.activestate.com/ActivePerl. + Windows targets can be classified as "native", ones that use Windows API + directly, and "hosted" which rely on POSIX-compatible layer. "Native" + targets are VC-* (where "VC" stems from abbreviating Microsoft Visual C + compiler) and mingw[64]. "Hosted" platforms are Cygwin and MSYS[2]. Even + though the latter is not directly supported by OpenSSL Team, it's #1 + popular choice for building MinGW targets. In the nutshell MinGW builds + are always cross-compiled. On Linux and Cygwin they look exactly as such + and require --cross-compile-prefix option. While on MSYS[2] it's solved + rather by placing gcc that produces "MinGW binary" code 1st on $PATH. + This is customarily source of confusion. "Hosted" applications "live" in + emulated file system name space with POSIX-y root, mount points, /dev + and even /proc. Confusion is intensified by the fact that MSYS2 shell + (or rather emulated execve(2) call) examines the binary it's about to + start, and if it's found *not* to be linked with MSYS2 POSIX-y thing, + command line arguments that look like file names get translated from + emulated name space to "native". For example '/c/some/where' becomes + 'c:\some\where', '/dev/null' - 'nul'. This creates an illusion that + there is no difference between MSYS2 shell and "MinGW binary", but + there is. Just keep in mind that "MinGW binary" "experiences" Windows + system in exactly same way as one produced by VC, and in its essence + is indistinguishable from the latter. (Which by the way is why + it's referred to in quotes here, as "MinGW binary", it's just as + "native" as it can get.) + + Visual C++ builds, a.k.a. VC-* + ============================== + + Requirement details + ------------------- + + In addition to the requirements and instructions listed in INSTALL, + these are required as well: + + - Perl. We recommend ActiveState Perl, available from + https://www.activestate.com/ActivePerl. Another viable alternative + appears to be Strawberry Perl, http://strawberryperl.com. You also need the perl module Text::Template, available on CPAN. - Please read README.PERL for more information. - - - You need a C compiler. OpenSSL has been tested to build with these: - - * 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. - - - GNU C (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 make of OpenSSL with Cygwin is virtually identical to the - Unix procedure. - - To build OpenSSL using Cygwin, you need to: - - * Install Cygwin (see http://cygwin.com/) - - * Install Cygwin Perl and ensure it is in the path. Recall that - as least 5.10.0 is required. - - * Run the Cygwin bash shell - - Apart from that, follow the Unix instructions in INSTALL. - - 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. - - 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. - - GNU C (MinGW/MSYS) - ------------- - - * Compiler and shell environment installation: - - 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. + Please read NOTES.PERL for more information. - Alternativelly, one can use MSYS2 from http://msys2.github.io/, - which includes MingW (32-bit and 64-bit). + - Microsoft Visual C compiler. Since we can't test them all, there is + unavoidable uncertainty about which versions are supported. Latest + version along with couple of previous are certainly supported. On + the other hand oldest one is known not to work. Everything between + falls into best-effort category. - * 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-. + - Netwide Assembler, a.k.a. NASM, available from https://www.nasm.us, + is required. Note that NASM is the only supported assembler. Even + though Microsoft provided assembler is NOT supported, contemporary + 64-bit version is exercised through continuous integration of + VC-WIN64A-masm target. - "Classic" builds (Visual C++) - ---------------- - - [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. - - NOTE: this won't be available for long.] - - 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%. - - 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. - - For Win32: - - > 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: + Installation directories + ------------------------ - > ms\do_ms + The default installation directories are derived from environment + variables. - For Win64/x64: + For VC-WIN32, the following defaults are use: - > perl Configure VC-WIN64A --classic --prefix=c:\some\openssl\dir - > ms\do_win64a + PREFIX: %ProgramFiles(86)%\OpenSSL + OPENSSLDIR: %CommonProgramFiles(86)%\SSL - For Win64/IA64: + For VC-WIN64, the following defaults are use: - > perl Configure VC-WIN64I --classic --prefix=c:\some\openssl\dir - > ms\do_win64i + PREFIX: %ProgramW6432%\OpenSSL + OPENSSLDIR: %CommonProgramW6432%\SSL - Where the prefix argument specifies where OpenSSL will be installed to. + Should those environment variables not exist (on a pure Win32 + installation for examples), these fallbacks are used: - 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. + PREFIX: %ProgramFiles%\OpenSSL + OPENSSLDIR: %CommonProgramFiles%\SSL - > nmake -f ms\ntdll.mak + 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 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 and mingw64 + ================= - > nmake -f ms\ntdll.mak test + * MSYS2 shell and development environment installation: - To install OpenSSL to the specified location do: + Download MSYS2 from https://msys2.github.io/ and follow installation + instructions. Once up and running install even make, perl, (git if + needed,) mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc. You should + have corresponding MinGW items on your start menu, use *them*, not + generic MSYS2. As implied in opening note, difference between them + is which compiler is found 1st on $PATH. At this point ./config + should recognize correct target, roll as if it was Unix... - > nmake -f ms\ntdll.mak install + * It is also possible to build mingw[64] on Linux or Cygwin by + configuring with corresponding --cross-compile-prefix= option. For + example - Tweaks: + ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... - 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. + or - 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 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 naturally implies that you've installed corresponding add-on + packages. 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; @@ -172,3 +139,27 @@ 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. + + Cygwin, "hosted" environment + ============================ + + 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. + + To build OpenSSL using Cygwin, you need to: + + * Install Cygwin (see https://cygwin.com/) + + * Install Cygwin Perl and ensure it is in the path. Recall that + as least 5.10.0 is required. + + * Run the Cygwin bash shell + + Apart from that, follow the Unix instructions in INSTALL. + + 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.