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 --- INSTALL | 28 ++++++++- INSTALL.WIN | 192 ------------------------------------------------------------ NOTES.WIN | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 194 insertions(+), 194 deletions(-) delete mode 100644 INSTALL.WIN create mode 100644 NOTES.WIN diff --git a/INSTALL b/INSTALL index a96eb8ffe2..4799d62dd9 100644 --- a/INSTALL +++ b/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 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. diff --git a/INSTALL.WIN b/INSTALL.WIN deleted file mode 100644 index 084388e7a6..0000000000 --- a/INSTALL.WIN +++ /dev/null @@ -1,192 +0,0 @@ - - INSTALLATION ON WINDOWS PLATFORMS - --------------------------------- - - [Instructions for building for Windows CE can be found in INSTALL.WCE] - - Here are a few comments about building OpenSSL for Windows environments. - - - you need Perl. Unless you will build on Cygwin, you will need - 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: - - * Visual C++ - * GNU C (Cygwin or MinGW) - -- 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. - - Visual C++ - ---------- - - 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 --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 --prefix=c:\some\openssl\dir - > ms\do_win64a - - For Win64/IA64: - - > perl Configure VC-WIN64I --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 - - 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. 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.3