From b32b896166199b497bf98da6a5c5b50d8811851f Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Tue, 8 Mar 2016 14:44:46 +0100 Subject: Adapt INSTALL and related notes for Windows Reviewed-by: Rich Salz --- NOTES.WIN | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 NOTES.WIN (limited to 'NOTES.WIN') 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 -- cgit v1.2.1