1(doc_windows)= 2 3# Installing PETSc On Microsoft Windows 4 5:::{admonition} Are You Sure? 6:class: yellow 7 8Are you sure you want to use Microsoft Windows? 9 10Developing HPC software is more difficult on Microsoft Windows than Linux and macOS systems. 11We recommend using a Microsoft Windows system for PETSc only when necessary. 12::: 13 14There are many ways to install PETSc on Microsoft Windows's systems. 15 16- {any}`sec_linux_on_windows` 17- {any}`sec_cygwin_gnu_on_windows` 18- {any}`sec_native_compilers_on_windows` 19- {any}`sec_msys2_mingw_compilers_on_windows` 20 21______________________________________________________________________ 22 23(sec_linux_on_windows)= 24 25## Linux on Microsoft Windows 26 27- Microsoft Windows Subsystem for Linux 2 ([WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10)). Be sure to use WSL2 for best performance. 28- [Docker](https://docs.docker.com/docker-for-windows/) for Microsoft 29 Windows. 30- Linux virtual machine via [VirtualBox](https://www.virtualbox.org/) or similar. One sample 31 tutorial is at <https://www.psychocats.net/ubuntu/virtualbox>. Google can provide more 32 tutorials. 33 34______________________________________________________________________ 35 36(sec_cygwin_gnu_on_windows)= 37 38## Cygwin/GNU Compilers on Microsoft Windows 39 40Cygwin/GNU compilers allow building standalone PETSc libraries and binaries 41that work on Microsoft Windows, with Cygwin pre-built libraries for BLAS, LAPACK, and Open MPI. 42 431. Install Cygwin: 44 45 Download and install Cygwin from <http://www.cygwin.com> and make sure the 46 following Cygwin components are installed: 47 48 - python3 49 - make 50 - gcc-core gcc-g++ gcc-fortran 51 - liblapack-devel 52 - openmpi libopenmpi-devel libhwloc-devel libevent-devel zlib-devel 53 542. To build with Cygwin installed BLAS, LAPACK, and Open MPI (from default locations), do (from `Cygwin64 Terminal`): 55 56 ```console 57 $ ./configure 58 ``` 59 603. Follow the Unix instructions for any additional configuration or build options. 61 62:::{note} 63- Libraries built with Cygwin/GNU compilers are **not** compatible and cannot be linked with Microsoft or Intel compilers. 64- Native libraries like MS-MPI, Intel MPI cannot be used from Cygwin/GNU compilers. 65- Most {ref}`external packages <doc_externalsoftware>` are likely to work, 66 however the `configure` option `--download-mpich` does not work. 67::: 68 69______________________________________________________________________ 70 71(sec_native_compilers_on_windows)= 72 73## Native Microsoft/Intel Windows Compilers 74 75Microsoft Windows does not provide a Unix shell environment. Also 76the native Microsoft/Intel compilers behave differently than other (Unix) compilers. So to 77install PETSc on Microsoft Windows with Microsoft or Intel compilers one has to install Cygwin (for the Unix environment) 78and use `win32fe` [^win32] compiler wrapper, to use the Microsoft/Intel compilers. 79 801. Install Cygwin: 81 82 Download and install Cygwin from <http://www.cygwin.com> and make sure the 83 following Cygwin components are installed: 84 85 - python3 86 - make 87 88 Additional Cygwin components like git and CMake can be useful for installing 89 {ref}`external packages <doc_externalsoftware>`. 90 912. Remove Cygwin link.exe: 92 93 Cygwin link.exe can conflict with Intel ifort compiler. If you are using ifort - 94 do (from `Cygwin64 Terminal`): 95 96 ```console 97 $ mv /usr/bin/link.exe /usr/bin/link-cygwin.exe 98 ``` 99 1003. Setup `Cygwin64 Terminal` with working compilers: 101 102 We require the compilers to be setup properly in a Cygwin bash command shell, so that 103 `cl foo.c` or `ifort foo.F` works from this shell. For example - if using `Visual Studio 2022 C` 104 and `Intel oneAPI 2022 Fortran`, one can do: 105 106 1. `Start` -> `Programs` -> `Intel oneAPI 2022` -> `Intel oneAPI command prompt for Intel 64 for Visual Studio 2022`. 107 This should start a `DOS Command shell` with working compilers. 108 109 2. Within this `DOS Command shell` - run `Cygwin64 Terminal`, i.e., `mintty.exe` as: 110 111 ```powershell 112 C:\cygwin64\bin\mintty.exe - 113 ``` 114 115 3. Verify if the compilers are usable (by running `cl` and `ifort` in this `Cygwin64 Terminal`). 116 117 4. Now run `configure` with compiler wrapper script `win32fe_cl` that uses `win32fe` [^win32] and then build the libraries with 118 `make` (as per the usual instructions). 119 120### Example Configure Usage With Microsoft Windows Compilers 121 122Use `configure` with `Visual Studio 2022 C` and `Intel oneAPI 2022 Fortran` (without MPI): 123 124```console 125$ ./configure --with-cc='win32fe_cl' --with-fc='win32fe_ifort' --with-cxx='win32fe_cl' --with-mpi=0 --download-fblaslapack 126``` 127 128If Fortran or C++ usage is not required, use: 129 130```console 131$ ./configure --with-cc='win32fe_cl' --with-fc=0 --with-cxx=0 --download-f2cblaslapack 132``` 133 134:::{note} 135- One can use Intel oneAPI C/C++ compiler `icl` or `icx` instead of Microsoft `cl`, for ex: `--with-cc=win32fe_icl --with-cxx=win32fe_icl`. 136- A shorter form `--with-cc=cl` that translates to `--with-cc=win32fe_cl` is also supported. Similarly for `icl`, `icx`, `ifort`, `ifx`. 137- Intel oneAPI `ifx` currently works with `--with-shared-libraries=0` only, `ifort` is recommended for default shared library build. 138- The `--download-package` option may work with some {ref}`external packages <doc_externalsoftware>` and fail with most packages. 139::: 140 141### Using MPI, MKL 142 143We support both MS-MPI (64-bit) and Intel MPI on Microsoft Windows. We also support using Intel MKL as BLAS and LAPACK implementations. 144For example usages, check `$PETSC_DIR/config/examples/arch-mswin*.py` 145 146:::{warning} 147**Avoid spaces in \$PATH** 148 149It is better to avoid spaces or similar special chars when specifying `configure` options. On 150Microsoft Windows - this usually affects specifying MPI or MKL. Microsoft Windows 151supports DOS short form for directory names - so it is better to use this notation. Cygwin 152tool `cygpath` can be used to get paths in this notation. For example: 153 154```console 155$ cygpath -u `cygpath -ms '/cygdrive/c/Program Files (x86)/Microsoft SDKs/MPI'` 156/cygdrive/c/PROGRA~2/MICROS~2/MPI 157$ cygpath -u `cygpath -ms '/cygdrive/c/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/mkl/lib/intel64'` 158/cygdrive/c/PROGRA~2/INTELS~1/COMPIL~2/windows/mkl/lib/intel64 159``` 160 161Then use in `configure` as follows: 162 163```console 164$ ./configure --with-cc='win32fe_cl' --with-fc='win32fe_ifort' --with-cxx='win32fe_cl' \ 165--with-shared-libraries=0 \ 166--with-mpi-include='[/cygdrive/c/PROGRA~2/MICROS~2/MPI/Include,/cygdrive/c/PROGRA~2/MICROS~2/MPI/Include/x64]' \ 167--with-mpi-lib='-L/cygdrive/c/PROGRA~2/MICROS~2/MPI/lib/x64 msmpifec.lib msmpi.lib' \ 168--with-mpiexec=/cygdrive/c/PROGRA~1/MICROS~2/Bin/mpiexec \ 169--with-blaslapack-lib='-L/cygdrive/c/PROGRA~2/INTELS~1/COMPIL~2/windows/mkl/lib/intel64 mkl_intel_lp64_dll.lib mkl_sequential_dll.lib mkl_core_dll.lib' 170``` 171::: 172 173### Project Files 174 175We cannot provide Microsoft Visual Studio project files for users as they are specific to 176the `configure` options, location of {ref}`external packages <doc_externalsoftware>`, 177compiler versions etc. used for any given build of PETSc, so they are potentially 178different for each build of PETSc. So if you need a project file for use with PETSc - 179do the following. 180 1811. Create an empty project file with one of the examples, say 182 `$PETSC_DIR/src/ksp/ksp/tutorials/ex2.c` 183 1842. Try compiling the example from Cygwin bash shell - using `make` - i.e.: 185 186 ```console 187 $ cd $PETSC_DIR/src/ksp/ksp/tutorials 188 $ make ex2 189 ``` 190 1913. If the above works - then make sure all the compiler/linker options used by `make` 192 are also present in the project file in the correct notation. 193 1944. If errors - redo the above step. If all the options are correctly specified, the 195 example should compile from Microsoft Visual Studio. 196 197______________________________________________________________________ 198 199(sec_msys2_mingw_compilers_on_windows)= 200 201## MSYS2/MinGW (GNU) Compilers on Microsoft Windows 202 203These allow building standalone Microsoft Windows libraries and 204applications that are compatible with the Microsoft and Intel compilers. 205 2061. Install MSYS2 and MS-MPI: 207 208 Download and install MSYS2 from <https://www.msys2.org>. 209 If you want to use MPI, we recommend you use MS-MPI from <https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi>. 210 2112. Update MSYS2 and install base packages: 212 213 First, launch a MSYS2 MinGW x64 shell. Double-check this is the proper type of shell by typing 214 215 ```console 216 $ echo $MINGW_PREFIX 217 /mingw64 218 ``` 219 220 If you see something else, e.g., `/clang64`, this is not the correct type 221 of shell, it may still work, but this is less tested. Then, update your 222 installation using `pacman` (you may be asked to quit and re-open your shell). 223 224 ```console 225 $ pacman -Syu 226 ``` 227 228 Install the following packages that are needed 229 by some PETSc dependencies. 230 231 ```console 232 $ pacman -S autoconf automake-wrapper bison bsdcpio make git \ 233 mingw-w64-x86_64-toolchain patch python flex \ 234 pkg-config pkgfile tar unzip mingw-w64-x86_64-cmake \ 235 mingw-w64-x86_64-msmpi mingw-w64-x86_64-openblas mingw-w64-x86_64-jq 236 ``` 237 2383. Configuring: 239 240 The two difficulties here are: 1) make sure PETSc configure picks up the proper Python installation, as there are more than one available in a MSYS2 MinGW shell and 2) tell PETSc where MS-MPI `mpiexec` is. We recommend not using shared libraries as it is easier to create standalone binaries that way. 241 242 ```console 243 $ /usr/bin/python ./configure --with-mpiexec='/C/Program\ Files/Microsoft\ MPI/Bin/mpiexec' \ 244 --with-shared-libraries=0 245 ``` 246 247:::{note} 248`MinGW` (GNU) compilers can also be installed/used via `Cygwin` (not just MSYS2). 249::: 250 251### Debugging on Microsoft Windows 252 253Running PETSc programs with `-start_in_debugger` is not supported on Microsoft Windows. Debuggers need to be initiated manually. 254Make sure your environment is properly configured to use the appropriate debugger for your compiler. 255The debuggers can be initiated using Microsoft Visual Studio: 256 257```console 258$ devenv ex1.exe 259``` 260 261Intel Enhanced Debugger: 262 263```console 264$ edb ex1.exe 265``` 266 267or GNU Debugger 268 269```console 270$ gdb ex1.exe 271``` 272 273```{rubric} Footnotes 274``` 275 276[^win32]: [PETSc Win32 Development Tool Front End](https://bitbucket.org/petsc/win32fe) (`win32fe`): This tool is used as a wrapper to Microsoft 277 and Intel compilers and associated tools - to enable building PETSc libraries using 278 Cygwin `make` and other Unix tools. For additional info, run 279 `${PETSC_DIR}/lib/petsc/bin/win32fe/win32fe --help` 280