From 97a479c6f835ba7e1e5b03de4ff59bf829a6eadd Mon Sep 17 00:00:00 2001 From: Andy Polyakov Date: Fri, 16 Mar 2018 15:39:51 +0100 Subject: [PATCH] NOTES.WIN: classify targets to "native" and "hosted" and restructure. Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/5647) --- NOTES.WIN | 135 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 80 insertions(+), 55 deletions(-) diff --git a/NOTES.WIN b/NOTES.WIN index ac215c3603..014036c712 100644 --- a/NOTES.WIN +++ b/NOTES.WIN @@ -2,21 +2,50 @@ NOTES FOR THE WINDOWS PLATFORMS =============================== - Requirement details for native (Visual C++) builds - -------------------------------------------------- + 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: - - You need Perl. We recommend ActiveState Perl, available from + - 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 NOTES.PERL for more information. - - You need a C compiler. OpenSSL has been tested to build with these: - - * Visual C++ + - 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. - Netwide Assembler, a.k.a. NASM, available from http://www.nasm.us, is required if you intend to utilize assembler modules. Note that NASM @@ -24,10 +53,8 @@ supported. - Visual C++ (native Windows) - --------------------------- - Installation directories + ------------------------ The default installation directories are derived from environment variables. @@ -55,62 +82,36 @@ is, of course, to choose a different set of directories by using --prefix and --openssldir when configuring. - 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 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. - - 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. + mingw and mingw64 + ================= + * MSYS2 shell and development environment installation: - GNU C (MinGW/MSYS) - ------------------ + 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... - * Compiler and shell environment installation: + * It is also possible to build mingw[64] on Linux or Cygwin by + configuring with corresponding --cross-compile-prefix= option. For + example - 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 must be used. + ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... - Alternatively, one can use MSYS2 from https://msys2.github.io/, - which includes MingW (32-bit and 64-bit). + or - * 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-. + ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ... + 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, GDI32.LIB, @@ -137,3 +138,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. -- 2.25.1