Adapt INSTALL and related notes for Windows

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

1 files changed, 168 insertions, 0 deletions

diff --git a/NOTES.WIN b/NOTES.WIN
new file mode 100644
index 0000000000..c20427855b
--- /dev/null
+++ b/NOTES.WIN
@@ -0,0 +1,168 @@
+
+ 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.
+   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. 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
+ 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:
+
+ > ms\do_ms
+
+ For Win64/x64:
+
+ > perl Configure VC-WIN64A --classic --prefix=c:\some\openssl\dir
+ > ms\do_win64a
+
+ For Win64/IA64:
+
+ > perl Configure VC-WIN64I --classic --prefix=c:\some\openssl\dir
+ > ms\do_win64i
+
+ Where the prefix argument specifies where OpenSSL will be installed to.
+
+ 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.
+
+ > nmake -f ms\ntdll.mak
+
+ 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:
+
+ > nmake -f ms\ntdll.mak test
+
+ To install OpenSSL to the specified location do:
+
+ > nmake -f ms\ntdll.mak install
+
+ Tweaks:
+
+ 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.
+
+ 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.
+
+ You can also build a static version of the library using the Makefile
+ ms\nt.mak