Windows.md

   1 This wiki page contains information about how to use deal.II on the
   2  - [Windows subsystem for Linux](#using-dealii-with-the-windows-subsystem-for-windows)
   3  - [Using deal.II on native Windows](#using-dealii-on-native-windows)
   4
   5 For an overview of different ways to use deal.II on Windows have a look at
   6 the corresponding [FAQ entry](https://github.com/dealii/dealii/wiki/Frequently-Asked-Questions#can-i-use-dealii-on-a-windows-platform).
   7
   8 # Using deal.II with the Windows Subsystem for Linux
   9
  10 **Warning: please be aware that the following is experimental and you will
  11 likely encounter bugs in compilers and deal.II itself. Only continue if you
  12 are willing to experiment.**
  13
  14 Windows 10 has gained a compatibility layer for running Linux binaries
  15 natively on Windows. You can find more information on the
  16 [Wikipedia page](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux).
  17
  18 In the following section a detailed HowTo is given to install the subsystem
  19 and a Linux distribution on top of it. Our choice at hand is [Debian
  20 GNU/Linux](https://www.microsoft.com/en-us/store/p/debian-gnu-linux/9msvkqc78pk6)
  21 because it already contains the latest deal.II release in binary form.
  22 (<b>Note:</b> The same is true for the Ubuntu distribution.)
  23
  24 ## (Required) Installing the subsystem and Debian GNU/Linux
  25
  26 Have a look at the excellent documentation about the Linux subsystem on the
  27 [Windows help pages](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
  28
  29 1. (As described in detail on the Windows help pages, we first have to
  30    install the subsystem. For this, locate the Windows PowerShell in your
  31    Start menu (`Start` -> `Windows PowerShell`), right click on `Windows PowerShell`
  32   -> `More` -> `Run as administrator`
  33
  34 2. Install the subsystem by using the following command
  35    ```console
  36    Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
  37    ```
  38    and restart
  39
  40 3. Open the Microsoft Store and search for "Debian", and install "Get Debian
  41    GNU/Linux". When finished start the application. You will be prompted to
  42    enter a username and password.
  43
  44 4. Switch to the "root" account by running
  45    ```console
  46    user@computer% sudo -s
  47    ```
  48    Enter the password that you used in step 3.
  49
  50 5. Edit the package manager configuration by using nano (or an editor of
  51    your choice):
  52    ```console
  53    root@computer# nano /etc/apt/sources.list
  54    ```
  55    You should see three lines. If they contain the release name `stretch`,
  56    remove all three lines and replace them with a single line:
  57    ```
  58    deb http://deb.debian.org/debian buster main contrib non-free
  59    ```
  60
  61 6. Now update/upgrade the system by running
  62    ```console
  63    root@computer# apt update
  64    [...]
  65
  66    root@computer# apt dist-upgrade
  67    [...]
  68    Do you want to continue? [Y/n] <Enter>
  69    [...]
  70
  71    root@computer# apt autoremove
  72    [...]
  73    Do you want to continue? [Y/n] <Enter>
  74    [...]
  75    ```
  76
  77 ## (Required) Installing the deal.II library and tools
  78
  79 We continue the installation process by installing the deal.II library with
  80 development headers and documentation. The packages in Debian (or Ubuntu)
  81 are called `libdeal.ii-dev` and `libdeal.ii-doc`:
  82
  83 1. As root user (see above) run:
  84    ```console
  85    root@computer# apt install libdeal.ii-dev libdeal.ii-doc
  86    [... long list ...]
  87    0 upgraded, 443 newly installed, 0 to remove and 0 not upgraded.
  88    Need to get 441 MB of archives.
  89    After this operation, 2,016 MB of additional disk space will be used.
  90    Do you want to continue? [Y/n] <Enter>
  91    [...]
  92    ```
  93
  94    At this point, let us install a number of useful, additional tools:
  95    ```console
  96    root@computer# apt install build-essential cmake ninja-build gdb clang clang-format
  97    [...]
  98    Do you want to continue? [Y/n] <Enter>
  99    [...]
 100    ```
 101
 102    If you plan to use graphical tools, a number of useful programs are:
 103    ```console
 104    root@computer# apt install xterm gnuplot
 105    [...]
 106    Do you want to continue? [Y/n] <Enter>
 107    [...]
 108    ```
 109    You can also install gnuplot and ParaView natively on Windows to view the files created by deal.II.
 110
 111    If you plan to use MSVC, you will also need to install ssh, rsync, zip and
 112    unzip:
 113    ```console
 114    root@computer# apt install ssh zip unzip rsync
 115    [...]
 116    Do you want to continue? [Y/n] <Enter>
 117    [...]
 118    ```
 119    You will also need to install git:
 120    ```console
 121    root@computer# apt-get install git-core
 122    [...]
 123    Do you want to contiue? [Y/n] <Enter>
 124    [...]
 125    ```
 126
 127    If you would like to use the CMake version managed by Microsoft, run the following:
 128    ```console
 129    git clone https://github.com/Microsoft/CMake.git
 130    […]
 131    cd cmake
 132    mkdir out
 133    cd out
 134    cmake ../
 135    […]
 136    make
 137    […]
 138    sudo make install
 139    […]
 140    ```
 141
 142    Now, exit the root account:
 143    ```console
 144    root@computer# exit
 145    user@computer$
 146    ```
 147
 148 2. Do a quick "smoke test" whether everything installed fine by compiling
 149    and running the first example step:
 150    ```console
 151    user@computer$ cd
 152    user@computer$ cp -r /usr/share/doc/libdeal.ii-doc/examples/step-55 .
 153    user@computer$ cd step-55
 154    user@computer$ cmake .
 155    user@computer$ make release
 156    user@computer$ make run
 157    [...]
 158    [100%] Built target run
 159    ```
 160
 161 ## (Recommended) Installing an X server
 162
 163 In order to run graphical applications from within the Linux Subsystem a
 164 so-called X server has to be installed. This step is in particular
 165 necessary, if you plan to install
 166 [Eclipse](https://github.com/dealii/dealii/wiki/Eclipse), or
 167 [KDevelop](https://github.com/dealii/dealii/wiki/KDevelop) via the Linux
 168 subsystem.
 169
 170 1. Download and install [xming](https://sourceforge.net/projects/xming/).
 171
 172 2. Start xming. A styliced X should appear in the task bar.
 173
 174 3. Open a Linux terminal and try to run xterm:
 175    ```console
 176    user@computer$ export DISPLAY=:0
 177    user@computer$ xterm
 178    ```
 179    This should spawn a new window with a shell. Simply close the shell
 180    again.
 181
 182 4. In order to avoid to have to export `DISPLAY=:0` every single time, it
 183    is convenient to append
 184    ```
 185    export DISPLAY=:0
 186    ```
 187    to the end of the `.bashrc` file.
 188
 189 You should now be able to proceed and run all graphical and command lines
 190 tools that are mentioned in the documentation and video lectures about
 191 deal.II.
 192
 193
 194 ## (Optional) Installing Microsoft Visual Studio Community Edition
 195
 196 This step is optional and only needed if you intent to use MSVC for code
 197 development. (Great alternatives are
 198 [Eclipse](https://github.com/dealii/dealii/wiki/Eclipse), or
 199 [KDevelop](https://github.com/dealii/dealii/wiki/KDevelop).)
 200
 201 1. Go to the [Microsoft website](https://www.visualstudio.com/downloads)
 202    and download Microsoft Visual Studio Community Edition. Visual Studio versions below 15.8.0 will have problems with IntelliSense. You might need to install the Preview edition of Visual Studio to get version 15.8.0.
 203
 204 2. Launch the web installer. Make sure to select "Linux development with C++"
 205
 206 3. Restart.
 207
 208 4. To fix occasional IntelliSense bugs, install the Visual Studio tool IntelliSense Extender.
 209
 210 ### Create MSVC project
 211
 212 Next, let us create a small example project with MSVC. First, you have to
 213 decide where the MSVC project shall be located. For this example we will
 214 use the directory `workspace` in the (Windows) documents directory of the
 215 current user located on driver C.  The corresponding path to access this
 216 directory from Linux is `/mnt/c/Users/<user>/Documents/workspace`. (Substitute
 217 `<user>` with your Windows username in the following console listings!)
 218
 219 1. Copy an example step to the Windows user directory. For this, start the Linux
 220    terminal again and `cd` to the user directory and copy and example step:
 221    ```console
 222    user@computer$ mkdir -p /mnt/c/Users/<user>/Documents/workspace
 223    user@computer$ cd /mnt/c/Users/<user>/Documents/workspace
 224    user@computer$ cp -r /usr/share/doc/libdeal.ii-doc/examples/step-6 .
 225    user@computer$ cd step-6
 226    user@computer$ cmake .
 227    ```
 228
 229 2. (Only once) Download a script for generating Visual C++ Linux project files:
 230    ```console
 231    user@computer$ cd /mnt/c/Users/<user>/Documents/workspace
 232    user@computer$ git clone https://github.com/robotdad/vclinux
 233    ```
 234
 235 3. Generate the Visual C++ Linux project file:
 236    ```console
 237    user@computer$ cd /mnt/c/Users/<user>/Documents/workspace/step-6
 238    user@computer$ ../vclinux/bash/genvcxproj.sh . step-6.vcxproj
 239    ```
 240
 241 4. Start the sshd server:
 242    ```console
 243    root@computer$ sudo service ssh start
 244    ```
 245    Make sure to keep the terminal open and the sshd server running while working in Visual Studio
 246
 247 5. Open Visual Studio and navigate to `Tools` -> `Options` -> `Cross Platform` -> `Connection Manager`
 248     * The Host name should be 'localhost'
 249     * The Port should be 22
 250     * The User Name and Password are the ones you used to set up Debian
 251     * Hit okay and wait for Visual Studio to run through setting up the connection
 252
 253 6. Configure the project in Visual Studio
 254     * Open the project file `c:\Users\<user>\Documents\workspace\step-6.vcxproj` in Visual Studio.
 255     * In the `Solution Explorer` right-click on the project and select `Properties`
 256     * Go to the `Debugging` page and set `Program` to `/mnt/c/Users/<user>/Documents/workspace/step-6/step-6` and set `Working Directory` to `/mnt/c/Users/<user>/Documents/workspace/step-6/`
 257     * Go to the `Remote Build` page and set `Build Command Line` to `cd /mnt/c/Users/<user>/Documents/workspace/step-6/; cmake .; make`.
 258
 259 7. Run the executable via `Debug` -> `Start Debugging` (or press `F5`) and celebrate!
 260
 261 # Using deal.II on native Windows
 262
 263 **Warning: please be aware that the following is experimental and you will
 264 likely encounter bugs in compilers and deal.II itself. Only continue if you
 265 are willing to experiment.**
 266
 267 ## Visual Studio
 268
 269 Since deal.II 8.4.0 we have experimental support for the newer Visual
 270 Studio C++ compilers (2017 or newer), but this is still work in progress.
 271 You can check the current development status
 272 [here](https://github.com/dealii/dealii/issues/1921)
 273
 274 Installation instructions:
 275
 276 1. Download and install Visual Studio 2017:
 277    https://www.visualstudio.com/vs/ and make sure you select the C++
 278    compiler
 279 2. Install cmake from https://cmake.org/download/ (pick the windows
 280    installer)
 281 3. Extract deal.II to a folder, for example c:\dealii (or clone the git
 282    development version)
 283 4. Configure using cmake by opening the 64bit command line shortcut and
 284    run:
 285
 286    ```
 287    set PreferredToolArchitecture=x64
 288    cd c:\dealii
 289    mkdir build
 290    cd c:\dealii\build
 291    cmake -G "Visual Studio 15 2017 Win64" ..
 292    ```
 293    <b>Note:</b> Setting the tool architecture to 64 bit works around problems of
 294    the compiler or linker running out of memory and leads to much quicker
 295    compile times.
 296    <b>Note:</b> Use generator ``"Visual Studio 15 2017 Win64"`` for Visual Studio
 297    2017.
 298
 299 6. Compile and install the library by opening ``deal.II.sln`` in
 300    c:\dealii\build, pick the install target and compile. Note: you need to
 301    either compile in the same terminal as above (using ``cmake --build .``)
 302    or open ``devenv.exe`` from the same terminal, to use the 64 bit tool
 303    architecture.
 304
 305 7. in cmd go to one of the examples in c:\dealii\examples\step-xy:
 306    ```
 307    cmake -D DEAL_II_DIR=c:\dealii\build -G "Visual Studio 15 2017 Win64" .
 308    ```
 309
 310 8. Open the newly created solution (step-xy.sln) in that directory and
 311    compile/run/debug.
 312
 313 ## Running build tests on Windows:
 314
 315 Install git and mingw (for perl etc). Then create a .bat file:
 316 ```
 317 git pull origin master
 318 rmdir /Q /S buildtest17
 319 mkdir buildtest17
 320 cd buildtest17
 321 ctest -C Debug -DMAKEOPTS="/m:1" -DCTEST_CMAKE_GENERATOR="Visual Studio 15 2017" -S ../tests/run_buildtest.cmake -V
 322 cd ..
 323 ```
 324
 325 ## Cygwin / MingGW
 326
 327 Cygwin and forks such as MinGW and MinGW-64 are unsupported due to multiple
 328 unresolved miscompilation issues.
 329
 330 ## Other Windows compilers
 331
 332 We haven't had much success with any other compiler on Windows (Intel,
 333 Borland, ...).