Clarify NOTES.WIN.

Reviewed-by: Richard Levitte <levitte@openssl.org>

1 files changed, 43 insertions, 37 deletions

diff --git a/NOTES.WIN b/NOTES.WIN
index c20427855b..969923914a 100644
--- a/NOTES.WIN
+++ b/NOTES.WIN
@@ -28,17 +28,14 @@
  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.
+ Unix procedure.
 
  To build OpenSSL using Cygwin, you need to:
 
  * Install Cygwin (see http://cygwin.com/)
 
- * Install Perl and ensure it is in the path. Both Cygwin perl
-   (5.6.1-2 or newer) and ActivePerl work.
+ * Install Cygwin Perl and ensure it is in the path. Recall that
+   as least 5.10.0 is required.
 
  * Run the Cygwin bash shell
 
@@ -49,6 +46,12 @@
  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)
  -------------
@@ -57,7 +60,9 @@
 
    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.
+   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.
 
    Alternativelly, one can use MSYS2 from http://msys2.github.io/,
    which includes MingW (32-bit and 64-bit).
@@ -68,36 +73,6 @@
    and i686-w64-mingw32-.
 
 
- Linking your application
- ------------------------
-
- 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:
-
-	__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 small "shim" snippet, which provides glue between
- OpenSSL BIO layer and your compiler run-time. See the OPENSSL_Applink
- manual page for further details.
-
-
  "Classic" builds (Visual C++)
  ----------------
 
@@ -166,3 +141,34 @@
 
  You can also build a static version of the library using the Makefile
  ms\nt.mak
+
+ Linking your application
+ ------------------------
+
+ This section applies to non-Cygwin 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:
+
+	__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 small "shim" snippet, which provides glue between
+ OpenSSL BIO layer and your compiler run-time. See the OPENSSL_Applink
+ manual page for further details.