|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
NOTES FOR THE WINDOWS PLATFORMS
|
|
Packit Service |
084de1 |
===============================
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Windows targets can be classified as "native", ones that use Windows API
|
|
Packit Service |
084de1 |
directly, and "hosted" which rely on POSIX-compatible layer. "Native"
|
|
Packit Service |
084de1 |
targets are VC-* (where "VC" stems from abbreviating Microsoft Visual C
|
|
Packit Service |
084de1 |
compiler) and mingw[64]. "Hosted" platforms are Cygwin and MSYS[2]. Even
|
|
Packit Service |
084de1 |
though the latter is not directly supported by OpenSSL Team, it's #1
|
|
Packit Service |
084de1 |
popular choice for building MinGW targets. In the nutshell MinGW builds
|
|
Packit Service |
084de1 |
are always cross-compiled. On Linux and Cygwin they look exactly as such
|
|
Packit Service |
084de1 |
and require --cross-compile-prefix option. While on MSYS[2] it's solved
|
|
Packit Service |
084de1 |
rather by placing gcc that produces "MinGW binary" code 1st on $PATH.
|
|
Packit Service |
084de1 |
This is customarily source of confusion. "Hosted" applications "live" in
|
|
Packit Service |
084de1 |
emulated file system name space with POSIX-y root, mount points, /dev
|
|
Packit Service |
084de1 |
and even /proc. Confusion is intensified by the fact that MSYS2 shell
|
|
Packit Service |
084de1 |
(or rather emulated execve(2) call) examines the binary it's about to
|
|
Packit Service |
084de1 |
start, and if it's found *not* to be linked with MSYS2 POSIX-y thing,
|
|
Packit Service |
084de1 |
command line arguments that look like file names get translated from
|
|
Packit Service |
084de1 |
emulated name space to "native". For example '/c/some/where' becomes
|
|
Packit Service |
084de1 |
'c:\some\where', '/dev/null' - 'nul'. This creates an illusion that
|
|
Packit Service |
084de1 |
there is no difference between MSYS2 shell and "MinGW binary", but
|
|
Packit Service |
084de1 |
there is. Just keep in mind that "MinGW binary" "experiences" Windows
|
|
Packit Service |
084de1 |
system in exactly same way as one produced by VC, and in its essence
|
|
Packit Service |
084de1 |
is indistinguishable from the latter. (Which by the way is why
|
|
Packit Service |
084de1 |
it's referred to in quotes here, as "MinGW binary", it's just as
|
|
Packit Service |
084de1 |
"native" as it can get.)
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Visual C++ builds, a.k.a. VC-*
|
|
Packit Service |
084de1 |
==============================
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Requirement details
|
|
Packit Service |
084de1 |
-------------------
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
In addition to the requirements and instructions listed in INSTALL,
|
|
Packit Service |
084de1 |
these are required as well:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
- Perl. We recommend ActiveState Perl, available from
|
|
Packit Service |
084de1 |
https://www.activestate.com/ActivePerl. Another viable alternative
|
|
Packit Service |
084de1 |
appears to be Strawberry Perl, http://strawberryperl.com.
|
|
Packit Service |
084de1 |
You also need the perl module Text::Template, available on CPAN.
|
|
Packit Service |
084de1 |
Please read NOTES.PERL for more information.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
- Microsoft Visual C compiler. Since we can't test them all, there is
|
|
Packit Service |
084de1 |
unavoidable uncertainty about which versions are supported. Latest
|
|
Packit Service |
084de1 |
version along with couple of previous are certainly supported. On
|
|
Packit Service |
084de1 |
the other hand oldest one is known not to work. Everything between
|
|
Packit Service |
084de1 |
falls into best-effort category.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
- Netwide Assembler, a.k.a. NASM, available from https://www.nasm.us,
|
|
Packit Service |
084de1 |
is required. Note that NASM is the only supported assembler. Even
|
|
Packit Service |
084de1 |
though Microsoft provided assembler is NOT supported, contemporary
|
|
Packit Service |
084de1 |
64-bit version is exercised through continuous integration of
|
|
Packit Service |
084de1 |
VC-WIN64A-masm target.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Installation directories
|
|
Packit Service |
084de1 |
------------------------
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
The default installation directories are derived from environment
|
|
Packit Service |
084de1 |
variables.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
For VC-WIN32, the following defaults are use:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
PREFIX: %ProgramFiles(86)%\OpenSSL
|
|
Packit Service |
084de1 |
OPENSSLDIR: %CommonProgramFiles(86)%\SSL
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
For VC-WIN64, the following defaults are use:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
PREFIX: %ProgramW6432%\OpenSSL
|
|
Packit Service |
084de1 |
OPENSSLDIR: %CommonProgramW6432%\SSL
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Should those environment variables not exist (on a pure Win32
|
|
Packit Service |
084de1 |
installation for examples), these fallbacks are used:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
PREFIX: %ProgramFiles%\OpenSSL
|
|
Packit Service |
084de1 |
OPENSSLDIR: %CommonProgramFiles%\SSL
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
ALSO NOTE that those directories are usually write protected, even if
|
|
Packit Service |
084de1 |
your account is in the Administrators group. To work around that,
|
|
Packit Service |
084de1 |
start the command prompt by right-clicking on it and choosing "Run as
|
|
Packit Service |
084de1 |
Administrator" before running 'nmake install'. The other solution
|
|
Packit Service |
084de1 |
is, of course, to choose a different set of directories by using
|
|
Packit Service |
084de1 |
--prefix and --openssldir when configuring.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
mingw and mingw64
|
|
Packit Service |
084de1 |
=================
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
* MSYS2 shell and development environment installation:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Download MSYS2 from https://msys2.github.io/ and follow installation
|
|
Packit Service |
084de1 |
instructions. Once up and running install even make, perl, (git if
|
|
Packit Service |
084de1 |
needed,) mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc. You should
|
|
Packit Service |
084de1 |
have corresponding MinGW items on your start menu, use *them*, not
|
|
Packit Service |
084de1 |
generic MSYS2. As implied in opening note, difference between them
|
|
Packit Service |
084de1 |
is which compiler is found 1st on $PATH. At this point ./config
|
|
Packit Service |
084de1 |
should recognize correct target, roll as if it was Unix...
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
* It is also possible to build mingw[64] on Linux or Cygwin by
|
|
Packit Service |
084de1 |
configuring with corresponding --cross-compile-prefix= option. For
|
|
Packit Service |
084de1 |
example
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
or
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
This naturally implies that you've installed corresponding add-on
|
|
Packit Service |
084de1 |
packages.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Independently of the method chosen to build for mingw, the installation
|
|
Packit Service |
084de1 |
paths are similar to those used when building with VC-* targets, except
|
|
Packit Service |
084de1 |
that in case the fallbacks mentioned there aren't possible (typically
|
|
Packit Service |
084de1 |
when cross compiling on Linux), the paths will be the following:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
For mingw:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
PREFIX: C:/Program Files (x86)/OpenSSL
|
|
Packit Service |
084de1 |
OPENSSLDIR C:/Program Files (x86)/Common Files/SSL
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
For mingw64:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
PREFIX: C:/Program Files/OpenSSL
|
|
Packit Service |
084de1 |
OPENSSLDIR C:/Program Files/Common Files/SSL
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Linking your application
|
|
Packit Service |
084de1 |
========================
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
This section applies to all "native" builds.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
If you link with static OpenSSL libraries then you're expected to
|
|
Packit Service |
084de1 |
additionally link your application with WS2_32.LIB, GDI32.LIB,
|
|
Packit Service |
084de1 |
ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing
|
|
Packit Service |
084de1 |
non-interactive service applications might feel concerned about
|
|
Packit Service |
084de1 |
linking with GDI32.LIB and USER32.LIB, as they are justly associated
|
|
Packit Service |
084de1 |
with interactive desktop, which is not available to service
|
|
Packit Service |
084de1 |
processes. The toolkit is designed to detect in which context it's
|
|
Packit Service |
084de1 |
currently executed, GUI, console app or service, and act accordingly,
|
|
Packit Service |
084de1 |
namely whether or not to actually make GUI calls. Additionally those
|
|
Packit Service |
084de1 |
who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and
|
|
Packit Service |
084de1 |
actually keep them off service process should consider implementing
|
|
Packit Service |
084de1 |
and exporting from .exe image in question own _OPENSSL_isservice not
|
|
Packit Service |
084de1 |
relying on USER32.DLL. E.g., on Windows Vista and later you could:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
__declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void)
|
|
Packit Service |
084de1 |
{ DWORD sess;
|
|
Packit Service |
084de1 |
if (ProcessIdToSessionId(GetCurrentProcessId(),&sess))
|
|
Packit Service |
084de1 |
return sess==0;
|
|
Packit Service |
084de1 |
return FALSE;
|
|
Packit Service |
084de1 |
}
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
If you link with OpenSSL .DLLs, then you're expected to include into
|
|
Packit Service |
084de1 |
your application code small "shim" snippet, which provides glue between
|
|
Packit Service |
084de1 |
OpenSSL BIO layer and your compiler run-time. See the OPENSSL_Applink
|
|
Packit Service |
084de1 |
manual page for further details.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Cygwin, "hosted" environment
|
|
Packit Service |
084de1 |
============================
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Cygwin implements a Posix/Unix runtime system (cygwin1.dll) on top of the
|
|
Packit Service |
084de1 |
Windows subsystem and provides a bash shell and GNU tools environment.
|
|
Packit Service |
084de1 |
Consequently, a make of OpenSSL with Cygwin is virtually identical to the
|
|
Packit Service |
084de1 |
Unix procedure.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
To build OpenSSL using Cygwin, you need to:
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
* Install Cygwin (see https://cygwin.com/)
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
* Install Cygwin Perl and ensure it is in the path. Recall that
|
|
Packit Service |
084de1 |
as least 5.10.0 is required.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
* Run the Cygwin bash shell
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
Apart from that, follow the Unix instructions in INSTALL.
|
|
Packit Service |
084de1 |
|
|
Packit Service |
084de1 |
NOTE: "make test" and normal file operations may fail in directories
|
|
Packit Service |
084de1 |
mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin
|
|
Packit Service |
084de1 |
stripping of carriage returns. To avoid this ensure that a binary
|
|
Packit Service |
084de1 |
mount is used, e.g. mount -b c:\somewhere /home.
|