]>
Commit | Line | Data |
---|---|---|
26abc8f0 | 1 | |
df4c1d80 DDO |
2 | NOTES FOR WINDOWS PLATFORMS |
3 | =========================== | |
4 | ||
5 | There are various options to build and run OpenSSL on the Windows platforms. | |
6 | ||
7 | "Native" OpenSSL uses the Windows APIs directly at run time. | |
8 | To build a native OpenSSL you can either use: | |
9 | ||
10 | Microsoft Visual C++ (MSVC) C compiler on the command line | |
11 | or | |
12 | MinGW cross compiler | |
13 | run on the GNU-like development environment MSYS2 | |
14 | or run on Linux or Cygwin | |
15 | ||
16 | "Hosted" OpenSSL relies on an external POSIX compatibility layer | |
17 | for building (using GNU/Unix shell, compiler, and tools) and at run time. | |
18 | For this option you can use Cygwin. | |
19 | ||
20 | ||
8c1cbc72 | 21 | Visual C++ native builds, aka VC-* |
df4c1d80 | 22 | ===================================== |
97a479c6 AP |
23 | |
24 | Requirement details | |
25 | ------------------- | |
26abc8f0 | 26 | |
df4c1d80 | 27 | In addition to the requirements and instructions listed in INSTALL.md, |
1d7f3350 | 28 | these are required as well: |
07930a75 | 29 | |
df4c1d80 DDO |
30 | - Perl. |
31 | We recommend Strawberry Perl, available from http://strawberryperl.com/ | |
32 | Please read NOTES.PERL for more information, including the use of CPAN. | |
33 | An alternative is ActiveState Perl, https://www.activestate.com/ActivePerl | |
34 | for which you may need to explicitly build the Perl module Win32/Console.pm | |
35 | via https://platform.activestate.com/ActiveState and then download it. | |
36 | ||
37 | - Microsoft Visual C compiler. | |
38 | Since these are proprietary and ever-changing we cannot test them all. | |
39 | Older versions may not work. Use a recent version wherever possible. | |
40 | ||
41 | - Netwide Assembler (NASM), available from https://www.nasm.us | |
42 | Note that NASM is the only supported assembler. | |
43 | ||
44 | Quick start | |
45 | ----------- | |
46 | ||
47 | 1. Install Perl | |
48 | ||
49 | 2. Install NASM | |
50 | ||
51 | 3. Make sure both Perl and NASM are on your %PATH% | |
52 | ||
53 | 4. Use Visual Studio Developer Command Prompt with administrative privileges, | |
54 | choosing one of its variants depending on the intended architecture. | |
55 | Or run "cmd" and execute "vcvarsall.bat" with one of the options x86, | |
56 | x86_amd64, x86_arm, x86_arm64, amd64, amd64_x86, amd64_arm, or amd64_arm64. | |
57 | This sets up the environment variables needed for nmake.exe, cl.exe, etc. | |
58 | See also https://docs.microsoft.com/cpp/build/building-on-the-command-line | |
59 | ||
60 | 5. From the root of the OpenSSL source directory enter | |
61 | perl Configure VC-WIN32 if you want 32-bit OpenSSL or | |
16328e9f RL |
62 | perl Configure VC-WIN64A if you want 64-bit OpenSSL or |
63 | perl Configure to let Configure figure out the platform | |
df4c1d80 DDO |
64 | |
65 | 6. nmake | |
3189772e | 66 | |
df4c1d80 | 67 | 7. nmake test |
26abc8f0 | 68 | |
df4c1d80 | 69 | 8. nmake install |
26abc8f0 | 70 | |
df4c1d80 DDO |
71 | For the full installation instructions, or if anything goes wrong at any stage, |
72 | check the INSTALL.md file. | |
b32b8961 | 73 | |
8c16829e | 74 | Installation directories |
97a479c6 | 75 | ------------------------ |
8c16829e RL |
76 | |
77 | The default installation directories are derived from environment | |
78 | variables. | |
79 | ||
80 | For VC-WIN32, the following defaults are use: | |
81 | ||
82 | PREFIX: %ProgramFiles(86)%\OpenSSL | |
83 | OPENSSLDIR: %CommonProgramFiles(86)%\SSL | |
84 | ||
e7b69227 | 85 | For VC-WIN64, the following defaults are use: |
8c16829e RL |
86 | |
87 | PREFIX: %ProgramW6432%\OpenSSL | |
88 | OPENSSLDIR: %CommonProgramW6432%\SSL | |
89 | ||
90 | Should those environment variables not exist (on a pure Win32 | |
91 | installation for examples), these fallbacks are used: | |
92 | ||
93 | PREFIX: %ProgramFiles%\OpenSSL | |
94 | OPENSSLDIR: %CommonProgramFiles%\SSL | |
95 | ||
1c7bfec5 RL |
96 | ALSO NOTE that those directories are usually write protected, even if |
97 | your account is in the Administrators group. To work around that, | |
98 | start the command prompt by right-clicking on it and choosing "Run as | |
99 | Administrator" before running 'nmake install'. The other solution | |
100 | is, of course, to choose a different set of directories by using | |
101 | --prefix and --openssldir when configuring. | |
8c16829e | 102 | |
8c1cbc72 | 103 | Special notes for Universal Windows Platform builds, aka VC-*-UWP |
5ded1ca6 M |
104 | -------------------------------------------------------------------- |
105 | ||
106 | - UWP targets only support building the static and dynamic libraries. | |
107 | ||
5ded1ca6 M |
108 | - You should define the platform type to "uwp" and the target arch via |
109 | "vcvarsall.bat" before you compile. For example, if you want to build | |
df4c1d80 | 110 | "arm64" builds, you should run "vcvarsall.bat x86_arm64 uwp". |
5ded1ca6 | 111 | |
b32b8961 | 112 | |
df4c1d80 DDO |
113 | Native OpenSSL built using MinGW |
114 | ================================ | |
3e67b333 | 115 | |
df4c1d80 | 116 | MinGW offers an alternative way to build native OpenSSL, by cross compilation. |
b32b8961 | 117 | |
df4c1d80 | 118 | * Usually the build is done on Windows in a GNU-like environment called MSYS2. |
b32b8961 | 119 | |
df4c1d80 DDO |
120 | MSYS2 provides GNU tools, a Unix-like command prompt, |
121 | and a UNIX compatibility layer for applications. | |
8c1cbc72 | 122 | However, in this context it is only used for building OpenSSL. |
df4c1d80 DDO |
123 | The resulting OpenSSL does not rely on MSYS2 to run and is fully native. |
124 | ||
125 | Requirement details | |
126 | ||
127 | - MSYS2 shell, from https://www.msys2.org/ | |
128 | ||
129 | - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2 | |
130 | ||
131 | - make, installed using "pacman -S make" into the MSYS2 environment | |
132 | ||
133 | - MinGW[64] compiler: mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc. | |
134 | These compilers must be on your MSYS2 $PATH. | |
135 | A common error is to not have these on your $PATH. | |
136 | The MSYS2 version of gcc will not work correctly here. | |
137 | ||
138 | In the MSYS2 shell do the configuration depending on the target architecture: | |
b32b8961 | 139 | |
df4c1d80 | 140 | ./Configure mingw ... |
97a479c6 | 141 | or |
df4c1d80 DDO |
142 | ./Configure mingw64 ... |
143 | or | |
16b0e0fc | 144 | ./Configure ... |
df4c1d80 DDO |
145 | for the default architecture. |
146 | ||
147 | Apart from that, follow the Unix / Linux instructions in INSTALL.md. | |
148 | ||
149 | * It is also possible to build mingw[64] on Linux or Cygwin. | |
150 | ||
151 | In this case configure with the corresponding --cross-compile-prefix= option. | |
152 | For example | |
b32b8961 | 153 | |
df4c1d80 DDO |
154 | ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ... |
155 | or | |
97a479c6 | 156 | ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ... |
b32b8961 | 157 | |
df4c1d80 DDO |
158 | This requires that you've installed the necessary add-on packages for |
159 | mingw[64] cross compilation. | |
b32b8961 | 160 | |
ad839325 | 161 | Linking your application |
97a479c6 | 162 | ======================== |
ad839325 | 163 | |
97a479c6 | 164 | This section applies to all "native" builds. |
ad839325 AP |
165 | |
166 | If you link with static OpenSSL libraries then you're expected to | |
531e9dcc RL |
167 | additionally link your application with WS2_32.LIB, GDI32.LIB, |
168 | ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing | |
169 | non-interactive service applications might feel concerned about | |
170 | linking with GDI32.LIB and USER32.LIB, as they are justly associated | |
171 | with interactive desktop, which is not available to service | |
172 | processes. The toolkit is designed to detect in which context it's | |
173 | currently executed, GUI, console app or service, and act accordingly, | |
174 | namely whether or not to actually make GUI calls. Additionally those | |
175 | who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and | |
176 | actually keep them off service process should consider implementing | |
177 | and exporting from .exe image in question own _OPENSSL_isservice not | |
178 | relying on USER32.DLL. E.g., on Windows Vista and later you could: | |
ad839325 AP |
179 | |
180 | __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void) | |
181 | { DWORD sess; | |
182 | if (ProcessIdToSessionId(GetCurrentProcessId(),&sess)) | |
183 | return sess==0; | |
184 | return FALSE; | |
185 | } | |
186 | ||
187 | If you link with OpenSSL .DLLs, then you're expected to include into | |
df4c1d80 DDO |
188 | your application code a small "shim" snippet, which provides |
189 | the glue between the OpenSSL BIO layer and your compiler run-time. | |
190 | See also the OPENSSL_Applink manual page. | |
191 | ||
97a479c6 | 192 | |
df4c1d80 DDO |
193 | Hosted OpenSSL built using Cygwin |
194 | ================================= | |
97a479c6 | 195 | |
df4c1d80 DDO |
196 | Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the |
197 | Windows subsystem and provides a Bash shell and GNU tools environment. | |
198 | Consequently, a build of OpenSSL with Cygwin is virtually identical to the | |
97a479c6 AP |
199 | Unix procedure. |
200 | ||
201 | To build OpenSSL using Cygwin, you need to: | |
202 | ||
df4c1d80 | 203 | * Install Cygwin, see https://cygwin.com/ |
97a479c6 | 204 | |
df4c1d80 DDO |
205 | * Install Cygwin Perl, at least version 5.10.0 |
206 | and ensure it is in the $PATH | |
97a479c6 | 207 | |
df4c1d80 | 208 | * Run the Cygwin Bash shell |
97a479c6 | 209 | |
df4c1d80 | 210 | Apart from that, follow the Unix / Linux instructions in INSTALL.md. |
97a479c6 AP |
211 | |
212 | NOTE: "make test" and normal file operations may fail in directories | |
213 | mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin | |
214 | stripping of carriage returns. To avoid this ensure that a binary | |
215 | mount is used, e.g. mount -b c:\somewhere /home. |