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