DOC: Mention Configure consistently
[openssl.git] / NOTES.WIN
1
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
21  Visual C++ native builds, a.k.a. VC-*
22  =====================================
23
24  Requirement details
25  -------------------
26
27  In addition to the requirements and instructions listed in INSTALL.md,
28  these are required as well:
29
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
62     perl Configure VC-WIN64A   if you want 64-bit OpenSSL
63
64  6. nmake
65
66  7. nmake test
67
68  8. nmake install
69
70  For the full installation instructions, or if anything goes wrong at any stage,
71  check the INSTALL.md file.
72
73  Installation directories
74  ------------------------
75
76  The default installation directories are derived from environment
77  variables.
78
79  For VC-WIN32, the following defaults are use:
80
81      PREFIX:      %ProgramFiles(86)%\OpenSSL
82      OPENSSLDIR:  %CommonProgramFiles(86)%\SSL
83
84  For VC-WIN64, the following defaults are use:
85
86      PREFIX:      %ProgramW6432%\OpenSSL
87      OPENSSLDIR:  %CommonProgramW6432%\SSL
88
89  Should those environment variables not exist (on a pure Win32
90  installation for examples), these fallbacks are used:
91
92      PREFIX:      %ProgramFiles%\OpenSSL
93      OPENSSLDIR:  %CommonProgramFiles%\SSL
94
95  ALSO NOTE that those directories are usually write protected, even if
96  your account is in the Administrators group.  To work around that,
97  start the command prompt by right-clicking on it and choosing "Run as
98  Administrator" before running 'nmake install'.  The other solution
99  is, of course, to choose a different set of directories by using
100  --prefix and --openssldir when configuring.
101
102  Special notes for Universal Windows Platform builds, a.k.a. VC-*-UWP
103  --------------------------------------------------------------------
104
105  - UWP targets only support building the static and dynamic libraries.
106
107  - You should define the platform type to "uwp" and the target arch via
108    "vcvarsall.bat" before you compile. For example, if you want to build
109    "arm64" builds, you should run "vcvarsall.bat x86_arm64 uwp".
110
111
112  Native OpenSSL built using MinGW
113  ================================
114
115  MinGW offers an alternative way to build native OpenSSL, by cross compilation.
116
117  * Usually the build is done on Windows in a GNU-like environment called MSYS2.
118
119    MSYS2 provides GNU tools, a Unix-like command prompt,
120    and a UNIX compatibility layer for applications.
121    However in this context it is only used for building OpenSSL.
122    The resulting OpenSSL does not rely on MSYS2 to run and is fully native.
123
124    Requirement details
125
126    - MSYS2 shell, from https://www.msys2.org/
127
128    - Perl, at least version 5.10.0, which usually comes pre-installed with MSYS2
129
130    - make, installed using "pacman -S make" into the MSYS2 environment
131
132    - MinGW[64] compiler: mingw-w64-i686-gcc and/or mingw-w64-x86_64-gcc.
133      These compilers must be on your MSYS2 $PATH.
134      A common error is to not have these on your $PATH.
135      The MSYS2 version of gcc will not work correctly here.
136
137    In the MSYS2 shell do the configuration depending on the target architecture:
138
139      ./Configure mingw ...
140    or
141      ./Configure mingw64 ...
142    or
143      ./Configure ...
144    for the default architecture.
145
146    Apart from that, follow the Unix / Linux instructions in INSTALL.md.
147
148  * It is also possible to build mingw[64] on Linux or Cygwin.
149
150    In this case configure with the corresponding --cross-compile-prefix= option.
151    For example
152
153      ./Configure mingw --cross-compile-prefix=i686-w64-mingw32- ...
154    or
155      ./Configure mingw64 --cross-compile-prefix=x86_64-w64-mingw32- ...
156
157    This requires that you've installed the necessary add-on packages for
158    mingw[64] cross compilation.
159
160  Linking your application
161  ========================
162
163  This section applies to all "native" builds.
164
165  If you link with static OpenSSL libraries then you're expected to
166  additionally link your application with WS2_32.LIB, GDI32.LIB,
167  ADVAPI32.LIB, CRYPT32.LIB and USER32.LIB. Those developing
168  non-interactive service applications might feel concerned about
169  linking with GDI32.LIB and USER32.LIB, as they are justly associated
170  with interactive desktop, which is not available to service
171  processes. The toolkit is designed to detect in which context it's
172  currently executed, GUI, console app or service, and act accordingly,
173  namely whether or not to actually make GUI calls. Additionally those
174  who wish to /DELAYLOAD:GDI32.DLL and /DELAYLOAD:USER32.DLL and
175  actually keep them off service process should consider implementing
176  and exporting from .exe image in question own _OPENSSL_isservice not
177  relying on USER32.DLL. E.g., on Windows Vista and later you could:
178
179         __declspec(dllexport) __cdecl BOOL _OPENSSL_isservice(void)
180         {   DWORD sess;
181             if (ProcessIdToSessionId(GetCurrentProcessId(),&sess))
182                 return sess==0;
183             return FALSE;
184         }
185
186  If you link with OpenSSL .DLLs, then you're expected to include into
187  your application code a small "shim" snippet, which provides
188  the glue between the OpenSSL BIO layer and your compiler run-time.
189  See also the OPENSSL_Applink manual page.
190
191
192  Hosted OpenSSL built using Cygwin
193  =================================
194
195  Cygwin implements a POSIX/Unix runtime system (cygwin1.dll) on top of the
196  Windows subsystem and provides a Bash shell and GNU tools environment.
197  Consequently, a build of OpenSSL with Cygwin is virtually identical to the
198  Unix procedure.
199
200  To build OpenSSL using Cygwin, you need to:
201
202  * Install Cygwin, see https://cygwin.com/
203
204  * Install Cygwin Perl, at least version 5.10.0
205    and ensure it is in the $PATH
206
207  * Run the Cygwin Bash shell
208
209  Apart from that, follow the Unix / Linux instructions in INSTALL.md.
210
211  NOTE: "make test" and normal file operations may fail in directories
212  mounted as text (i.e. mount -t c:\somewhere /home) due to Cygwin
213  stripping of carriage returns. To avoid this ensure that a binary
214  mount is used, e.g. mount -b c:\somewhere /home.