]>
Commit | Line | Data |
---|---|---|
26abc8f0 | 1 | |
b32b8961 RL |
2 | NOTES FOR THE WINDOWS PLATFORMS |
3 | =============================== | |
26abc8f0 | 4 | |
97a479c6 AP |
5 | Windows targets can be classified as "native", ones that use Windows API |
6 | directly, and "hosted" which rely on POSIX-compatible layer. "Native" | |
7 | targets are VC-* (where "VC" stems from abbreviating Microsoft Visual C | |
8 | compiler) and mingw[64]. "Hosted" platforms are Cygwin and MSYS[2]. Even | |
9 | though the latter is not directly supported by OpenSSL Team, it's #1 | |
10 | popular choice for building MinGW targets. In the nutshell MinGW builds | |
11 | are always cross-compiled. On Linux and Cygwin they look exactly as such | |
12 | and require --cross-compile-prefix option. While on MSYS[2] it's solved | |
13 | rather by placing gcc that produces "MinGW binary" code 1st on $PATH. | |
14 | This is customarily source of confusion. "Hosted" applications "live" in | |
15 | emulated file system name space with POSIX-y root, mount points, /dev | |
16 | and even /proc. Confusion is intensified by the fact that MSYS2 shell | |
17 | (or rather emulated execve(2) call) examines the binary it's about to | |
18 | start, and if it's found *not* to be linked with MSYS2 POSIX-y thing, | |
19 | command line arguments that look like file names get translated from | |
20 | emulated name space to "native". For example '/c/some/where' becomes | |
21 | 'c:\some\where', '/dev/null' - 'nul'. This creates an illusion that | |
22 | there is no difference between MSYS2 shell and "MinGW binary", but | |
23 | there is. Just keep in mind that "MinGW binary" "experiences" Windows | |
24 | system in exactly same way as one produced by VC, and in its essence | |
25 | is indistinguishable from the latter. (Which by the way is why | |
26 | it's referred to in quotes here, as "MinGW binary", it's just as | |
27 | "native" as it can get.) | |
28 | ||
29 | Visual C++ builds, a.k.a. VC-* | |
30 | ============================== | |
31 | ||
32 | Requirement details | |
33 | ------------------- | |
26abc8f0 | 34 | |
07930a75 | 35 | In addition to the requirements and instructions listed in INSTALL, |
1d7f3350 | 36 | these are required as well: |
07930a75 | 37 | |
97a479c6 | 38 | - Perl. We recommend ActiveState Perl, available from |
3a80bd29 AP |
39 | https://www.activestate.com/ActivePerl. Another viable alternative |
40 | appears to be Strawberry Perl, http://strawberryperl.com. | |
d36ab9ce | 41 | You also need the perl module Text::Template, available on CPAN. |
07930a75 | 42 | Please read NOTES.PERL for more information. |
3189772e | 43 | |
97a479c6 AP |
44 | - Microsoft Visual C compiler. Since we can't test them all, there is |
45 | unavoidable uncertainty about which versions are supported. Latest | |
46 | version along with couple of previous are certainly supported. On | |
47 | the other hand oldest one is known not to work. Everything between | |
48 | falls into best-effort category. | |
26abc8f0 | 49 | |
f529b5cf AP |
50 | - Netwide Assembler, a.k.a. NASM, available from https://www.nasm.us, |
51 | is required. Note that NASM is the only supported assembler. Even | |
52 | though Microsoft provided assembler is NOT supported, contemporary | |
53 | 64-bit version is exercised through continuous integration of | |
54 | VC-WIN64A-masm target. | |
26abc8f0 | 55 | |
b32b8961 | 56 | |
8c16829e | 57 | Installation directories |
97a479c6 | 58 | ------------------------ |
8c16829e RL |
59 | |
60 | The default installation directories are derived from environment | |
61 | variables. | |
62 | ||
63 | For VC-WIN32, the following defaults are use: | |
64 | ||
65 | PREFIX: %ProgramFiles(86)%\OpenSSL | |
66 | OPENSSLDIR: %CommonProgramFiles(86)%\SSL | |
67 | ||
e7b69227 | 68 | For VC-WIN64, the following defaults are use: |
8c16829e RL |
69 | |
70 | PREFIX: %ProgramW6432%\OpenSSL | |
71 | OPENSSLDIR: %CommonProgramW6432%\SSL | |
72 | ||
73 | Should those environment variables not exist (on a pure Win32 | |
74 | installation for examples), these fallbacks are used: | |
75 | ||
76 | PREFIX: %ProgramFiles%\OpenSSL | |
77 | OPENSSLDIR: %CommonProgramFiles%\SSL | |
78 | ||
1c7bfec5 RL |
79 | ALSO NOTE that those directories are usually write protected, even if |
80 | your account is in the Administrators group. To work around that, | |
81 | start the command prompt by right-clicking on it and choosing "Run as | |
82 | Administrator" before running 'nmake install'. The other solution | |
83 | is, of course, to choose a different set of directories by using | |
84 | --prefix and --openssldir when configuring. | |
8c16829e | 85 | |
5ded1ca6 M |
86 | |
87 | Special notes for Universal Windows Platform builds, a.k.a. VC-*-UWP | |
88 | -------------------------------------------------------------------- | |
89 | ||
90 | - UWP targets only support building the static and dynamic libraries. | |
91 | ||
5ded1ca6 M |
92 | - You should define the platform type to "uwp" and the target arch via |
93 | "vcvarsall.bat" before you compile. For example, if you want to build | |
94 | "arm64" builds, you should type "vcvarsall.bat x86_arm64 uwp". | |
95 | ||
97a479c6 AP |
96 | mingw and mingw64 |
97 | ================= | |
b32b8961 | 98 | |
97a479c6 | 99 | * MSYS2 shell and development environment installation: |
3e67b333 | 100 | |
97a479c6 AP |
101 | Download MSYS2 from https://msys2.github.io/ and follow installation |
102 | instructions. Once up and running install even make, perl, (git if | |
103 | needed,) mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc. You should | |
104 | have corresponding MinGW items on your start menu, use *them*, not | |
105 | generic MSYS2. As implied in opening note, difference between them | |
106 | is which compiler is found 1st on $PATH. At this point ./config | |
107 | should recognize correct target, roll as if it was Unix... | |
b32b8961 | 108 | |
97a479c6 AP |
109 | * It is also possible to build mingw[64] on Linux or Cygwin by |
110 | configuring with corresponding --cross-compile-prefix= option. For | |
111 | example | |
b32b8961 | 112 | |
97a479c6 | 113 | ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... |
b32b8961 | 114 | |
97a479c6 | 115 | or |
b32b8961 | 116 | |
97a479c6 | 117 | ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ... |
b32b8961 | 118 | |
97a479c6 AP |
119 | This naturally implies that you've installed corresponding add-on |
120 | packages. | |
b32b8961 | 121 | |
ad839325 | 122 | Linking your application |
97a479c6 | 123 | ======================== |
ad839325 | 124 | |
97a479c6 | 125 | This section applies to all "native" builds. |
ad839325 AP |
126 | |
127 | If you link with static OpenSSL libraries then you're expected to | |
531e9dcc RL |
128 | additionally link your application with WS2_32.LIB, GDI32.LIB, |
129 | ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing | |
130 | non-interactive service applications might feel concerned about | |
131 | linking with GDI32.LIB and USER32.LIB, as they are justly associated | |
132 | with interactive desktop, which is not available to service | |
133 | processes. The toolkit is designed to detect in which context it's | |
134 | currently executed, GUI, console app or service, and act accordingly, | |
135 | namely whether or not to actually make GUI calls. Additionally those | |
136 | who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and | |
137 | actually keep them off service process should consider implementing | |
138 | and exporting from .exe image in question own _OPENSSL_isservice not | |
139 | relying on USER32.DLL. E.g., on Windows Vista and later you could: | |
ad839325 AP |
140 | |
141 | __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) | |
142 | { DWORD sess; | |
143 | if (ProcessIdToSessionId(GetCurrentProcessId(),&sess)) | |
144 | return sess==0; | |
145 | return FALSE; | |
146 | } | |
147 | ||
148 | If you link with OpenSSL .DLLs, then you're expected to include into | |
149 | your application code small "shim" snippet, which provides glue between | |
150 | OpenSSL BIO layer and your compiler run-time. See the OPENSSL_Applink | |
151 | manual page for further details. | |
97a479c6 AP |
152 | |
153 | Cygwin, "hosted" environment | |
154 | ============================ | |
155 | ||
156 | Cygwin implements a Posix/Unix runtime system (cygwin1.dll) on top of the | |
157 | Windows subsystem and provides a bash shell and GNU tools environment. | |
158 | Consequently, a make of OpenSSL with Cygwin is virtually identical to the | |
159 | Unix procedure. | |
160 | ||
161 | To build OpenSSL using Cygwin, you need to: | |
162 | ||
163 | * Install Cygwin (see https://cygwin.com/) | |
164 | ||
165 | * Install Cygwin Perl and ensure it is in the path. Recall that | |
166 | as least 5.10.0 is required. | |
167 | ||
168 | * Run the Cygwin bash shell | |
169 | ||
170 | Apart from that, follow the Unix instructions in INSTALL. | |
171 | ||
172 | NOTE: "make test" and normal file operations may fail in directories | |
173 | mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin | |
174 | stripping of carriage returns. To avoid this ensure that a binary | |
175 | mount is used, e.g. mount -b c:\somewhere /home. |