Adapt INSTALL and related notes for Windows

Reviewed-by: NRich Salz <rsalz@openssl.org>

INSTALL

@@ -3,7 +3,7 @@
  ---------------------------------
 
  [Installation on DOS (with djgpp), Windows, MacOS (before MacOS X)
-  and NetWare is described in INSTALL.DJGPP, INSTALL.WIN, INSTALL.MacOS
+  and NetWare is described in INSTALL.DJGPP, INSTALL.MacOS
   and INSTALL.NW.
   
   This document describes installation on the main supported operating
@@ -22,7 +22,8 @@
  For more details regarding specific platforms, there are these notes
  available:
 
-  * NOTES.VMS
+  * NOTES.VMS (OpenVMS)
+  * NOTES.WIN (any Windows except for Windows CE)
 
  Quick Start
  -----------
@@ -43,6 +44,12 @@
     $ mms test
     $ mms install
 
+  on Windows (only pick one of the targets for configuration):
+
+    $ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
+    $ nmake
+    $ nmake test
+
  [If any of these steps fails, see section Installation in Detail below.]
 
  This will build and install OpenSSL in the default location, which is:
@@ -50,6 +57,7 @@
   Unix:    normal installation directories under /usr/local
   OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the
            OpenSSL version number ('major'_'minor').
+  Windows: currently don't have an install function     <TBA>
 
  If you want to install it anywhere else, run config like this:
 
@@ -152,6 +160,8 @@
 
  1a. Configure OpenSSL for your operation system automatically:
 
+     NOTE: This is not available on Windows.
+
        $ ./config [options]                             # Unix
 
        or
@@ -235,6 +245,13 @@
 
        $ @[PATH.TO.OPENSSL.SOURCE]Configure {target} {options}
 
+     Windows example:
+
+       $ C:
+       $ mkdir \temp-openssl
+       $ cd \temp-openssl
+       $ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {target} {options}
+
      Paths can be relative just as well as absolute.  Configure will
      do its best to translate them to relative paths whenever possible.
 
@@ -242,6 +259,7 @@
 
        $ make                                           # Unix
        $ mms                                            ! (or mmk) OpenVMS
+       $ nmake                                          # Windows
 
      This will build the OpenSSL libraries (libcrypto.a and libssl.a on
      Unix, corresponding on other platforms) and the OpenSSL binary
@@ -268,6 +286,7 @@
 
        $ make test                                      # Unix
        $ mms test                                       ! OpenVMS
+       $ nmake test                                     # Windows
 
      If some tests fail, look at the output.  There may be reasons for
      the failure that isn't a problem in OpenSSL itself (like a
@@ -279,11 +298,15 @@
        $ DEFINE HARNESS_VERBOSE YES
        $ mms test                                       ! OpenVMS
 
+       $ set HARNESS_VERBOSE=yes
+       $ nmake test                                     # Windows
+
      If you want to run just one or a few specific tests, you can use
      the make variable TESTS to specify them, like this:
 
        $ make TESTS='test_rsa test_dsa' test            # Unix
        $ mms/macro="TESTS=test_rsa test_dsa" test       ! OpenVMS
+       $ nmake TESTS='test_rsa test_dsa' test           # Windows
 
      And of course, you can combine (Unix example shown):
        
@@ -293,6 +316,7 @@
 
        $ make list-tests                                # Unix
        $ mms list-tests                                 ! OpenVMS
+       $ nmake list-tests                               # Windows
 
      Have a look at the manual for the perl module Test::Harness to
      see what other HARNESS_* variables there are.

INSTALL.WIN → NOTES.WIN

 
- INSTALLATION ON WINDOWS PLATFORMS
- ---------------------------------
+ NOTES FOR THE WINDOWS PLATFORMS
+ ===============================
 
- [Instructions for building for Windows CE can be found in INSTALL.WCE]
+ [Notes for Windows CE can be found in INSTALL.WCE]
 
- Here are a few comments about building OpenSSL for Windows environments.
+ Requirement details for native (Visual C++) builds
+ --------------------------------------------------
 
- - you need Perl.  Unless you will build on Cygwin, you will need
-   ActiveState Perl, available from http://www.activestate.com/ActivePerl.  
+ - 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.
 
- - one of the following C compilers:
+ - You need a C compiler.  OpenSSL has been tested to build with these:
 
-  * Visual C++
-  * GNU C (Cygwin or MinGW)
+   * 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 now the only supported assembler. Without this the "Configure" step below
-  must be done with the "no-asm" option. The Microsoft provided assembler is NOT
-  supported.
+ - 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++
- ----------
+
+ 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. 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.
+
+ 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.
+
+ * 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.
+
+
+ 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 on its PATH.
+
+   Alternativelly, one can use MSYS2 from http://msys2.github.io/,
+   which includes MingW (32-bit and 64-bit).
+
+ * 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-.
+
+
+ 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++)
+ ----------------
+
+ [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
@@ -35,7 +117,7 @@
 
  For Win32:
 
- > perl Configure VC-WIN32 --prefix=c:\some\openssl\dir
+ > 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
@@ -45,12 +127,12 @@
 
  For Win64/x64:
 
- > perl Configure VC-WIN64A --prefix=c:\some\openssl\dir
+ > perl Configure VC-WIN64A --classic --prefix=c:\some\openssl\dir
  > ms\do_win64a
 
  For Win64/IA64:
 
- > perl Configure VC-WIN64I --prefix=c:\some\openssl\dir
+ > perl Configure VC-WIN64I --classic --prefix=c:\some\openssl\dir
  > ms\do_win64i
 
  Where the prefix argument specifies where OpenSSL will be installed to.
@@ -84,109 +166,3 @@
 
  You can also build a static version of the library using the Makefile
  ms\nt.mak
-
- 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. 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.
-
- To build OpenSSL using Cygwin:
-
- * 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.
-
- * Run the Cygwin bash shell
-
- * $ tar zxvf openssl-x.x.x.tar.gz
-   $ cd openssl-x.x.x
-
-   To build the Cygwin version of OpenSSL:
-
-   $ ./config
-   [...]
-   $ make
-   [...]
-   $ make test
-   $ make install
-
-   This will create a default install in /usr/local/ssl.
-
-   To build the MinGW version (native Windows) in Cygwin:
-
-   $ ./Configure mingw
-   [...]
-   $ make
-   [...]
-   $ make test
-   $ make install
-
- Cygwin Notes:
-
- "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.
-
- 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 on its PATH.
-
- * Compile OpenSSL:
-
-   $ ./config
-   [...]
-   $ make
-   [...]
-   $ make test
-
-   This will create the library and binaries in root source directory
-   and openssl.exe application in apps directory.
-
-   It is also possible to cross-compile it on Linux by configuring
-   with './Configure --cross-compile-prefix=i386-mingw32- mingw ...'. Other
-   possible targets include x86_64-w64-mingw32- and i686-w64-mingw32-.
-
-   libcrypto.a and libssl.a are the static libraries. To use the DLLs,
-   link with libcrypto32.a and libssl32.a instead.
-
- Linking your application
- ------------------------
-
- If you link with static OpenSSL libraries [those built with ms/nt.mak],
- 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.