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    At this point, let us install a number of useful, additional tools:
  93    ```console
  94    root@computer# apt install build-essential cmake ninja-build gdb clang clang-format
  95    [...]
  96    Do you want to continue? [Y/n] <Enter>
  97    ```
  98
  99    If you plan to use graphical tools, a number of useful programs are:
 100    ```console
 101    root@computer# apt install xterm gnuplot
 102    [...]
 103    Do you want to continue? [Y/n] <Enter>
 104    ```
 105
 106    If you plan to use MSVC, you will also need to install ssh, zip and
 107    unzip:
 108    ```console
 109    root@computer# apt install ssh zip unzip
 110    [...]
 111    Do you want to continue? [Y/n] <Enter>
 112    ```
 113
 114    Now, exit the root account:
 115    ```console
 116    root@computer# exit
 117    user@computer$
 118    ```
 119
 120 2. Do a quick "smoke test" whether everything installed fine by compiling
 121    and running the first example step:
 122    ```console
 123    user@computer$ cd
 124    user@computer$ cp -r /usr/share/doc/libdeal.ii-doc/examples/step-55 .
 125    user@computer$ cd step-55
 126    user@computer$ cmake .
 127    user@computer$ make release
 128    user@computer$ make run
 129    [...]
 130    [100%] Built target run
 131    ```
 132
 133 ## (Recommended) Installing an X server
 134
 135 In order to run graphical applications from within the Linux Subsystem a
 136 so-called X server has to be installed. This step is in particular
 137 necessary, if you plan to install
 138 [Eclipse](https://github.com/dealii/dealii/wiki/Eclipse), or
 139 [KDevelop](https://github.com/dealii/dealii/wiki/KDevelop) via the Linux
 140 subsystem.
 141
 142 1. Download and install [xming](https://sourceforge.net/projects/xming/).
 143
 144 2. Start xming. A styliced X should appear in the task bar.
 145
 146 3. Open a Linux terminal and try to run xterm:
 147    ```console
 148    user@computer$ export DISPLAY=:0
 149    user@computer$ xterm
 150    ```
 151    This should spawn a new window with a shell. Simply close the shell
 152    again.
 153
 154 4. In order to avoid to have to export `DISPLAY=:0` every single time, it
 155    is convenient to append
 156    ```
 157    export DISPLAY=:0
 158    ```
 159    to the end of the `.bashrc` file.
 160
 161 You should now be able to proceed and run all graphical and command lines
 162 tools that are mentioned in the documentation and video lectures about
 163 deal.II.
 164
 165
 166 ## (Optional) Installing Microsoft Visual Studio Community Edition
 167
 168 This step is optional and only needed if you intent to use MSVC for code
 169 development. (Great alternatives are
 170 [Eclipse](https://github.com/dealii/dealii/wiki/Eclipse), or
 171 [KDevelop](https://github.com/dealii/dealii/wiki/KDevelop).)
 172
 173 1. Go to the [Microsoft website](https://www.visualstudio.com/downloads)
 174    and download Microsoft Visual Studio Community Edition
 175
 176 2. Launch the web installer. Make sure to select "Linux development with C++"
 177
 178 3. Restart.
 179
 180 ### Create MSVC project
 181
 182 Next, let us create a small example project with MSVC. First, you have to
 183 decide where the MSVC project shall be located. For this example we will
 184 use the directory `workspace` in the (Windows) documents directory of the
 185 current user located on driver C.  The corresponding path to access this
 186 directory from Linux is `/mnt/c/Users/<user>/Documents/workspace`. (Substitute
 187 `<user>` with your Windows username in the following console listings!)
 188
 189 1. Copy an example step to the Windows user directory. For this, start the Linux
 190    terminal again and `cd` to the user directory and copy and example step:
 191    ```console
 192    user@computer$ mkdir -p /mnt/c/Users/<user>/Documents/workspace
 193    user@computer$ cd /mnt/c/Users/<user>/Documents/workspace
 194    user@computer$ cp -r /usr/share/doc/libdeal.ii-doc/examples/step-6 .
 195    user@computer$ cd step-6
 196    user@computer$ cmake .
 197    ```
 198
 199 2. (Only once) Download a script for generating Visual C++ Linux project files:
 200    ```console
 201    user@computer$ cd /mnt/c/Users/<user>/Documents/workspace
 202    user@computer$ git clone https://github.com/robotdad/vclinux
 203    ```
 204
 205 3. Generate the Visual C++ Linux project file:
 206    ```console
 207    user@computer$ cd /mnt/c/Users/<user>/Documents/workspace/step-6
 208    user@computer$ ../vclinux/bash/genvcxproj.sh . step-6.vcxproj
 209    ```
 210
 211 4. Start the sshd server:
 212    ```console
 213    root@computer$ sudo service ssh start
 214    ```
 215    Make sure to keep the terminal open and the sshd server running while working in Visual Studio
 216
 217 5. Configure the project in Visual Studio
 218     * Open the project file `c:\Users\<user>\Documents\workspace\step-6.vcxproj` in Visual Studio.
 219     * In the `Solution Explorer` right-click on the project and select `Properties`
 220     * Go to the `Debugging` page and set `Program` to `/mnt/c/Users/<user>/Documents/workspace/step-6/step-6`.
 221     * Go to the `Build` page and set `Build Command Line` to `cd /mnt/c/Users/<user>/Documents/workspace/step-6/; cmake .; make`.
 222
 223 6. Run the executable via `Debug` -> `Start Debugging` (or press `F5`) and celebrate!
 224
 225 # Using deal.II on native Windows
 226
 227 **Warning: please be aware that the following is experimental and you will
 228 likely encounter bugs in compilers and deal.II itself. Only continue if you
 229 are willing to experiment.**
 230
 231 ## Visual Studio
 232
 233 Since deal.II 8.4.0 we have experimental support for the newer Visual
 234 Studio C++ compilers (2017 or newer), but this is still work in progress.
 235 You can check the current development status
 236 [here](https://github.com/dealii/dealii/issues/1921)
 237
 238 Installation instructions:
 239
 240 1. Download and install Visual Studio 2017:
 241    https://www.visualstudio.com/vs/ and make sure you select the C++
 242    compiler
 243 2. Install cmake from https://cmake.org/download/ (pick the windows
 244    installer)
 245 3. Extract deal.II to a folder, for example c:\dealii (or clone the git
 246    development version)
 247 4. Configure using cmake by opening the 64bit command line shortcut and
 248    run:
 249
 250    ```
 251    set PreferredToolArchitecture=x64
 252    cd c:\dealii
 253    mkdir build
 254    cd c:\dealii\build
 255    cmake -G "Visual Studio 15 2017 Win64" ..
 256    ```
 257    <b>Note:</b> Setting the tool architecture to 64 bit works around problems of
 258    the compiler or linker running out of memory and leads to much quicker
 259    compile times.
 260    <b>Note:</b> Use generator ``"Visual Studio 15 2017 Win64"`` for Visual Studio
 261    2017.
 262
 263 6. Compile and install the library by opening ``deal.II.sln`` in
 264    c:\dealii\build, pick the install target and compile. Note: you need to
 265    either compile in the same terminal as above (using ``cmake --build .``)
 266    or open ``devenv.exe`` from the same terminal, to use the 64 bit tool
 267    architecture.
 268
 269 7. in cmd go to one of the examples in c:\dealii\examples\step-xy:
 270    ```
 271    cmake -D DEAL_II_DIR=c:\dealii\build -G "Visual Studio 15 2017 Win64" .
 272    ```
 273
 274 8. Open the newly created solution (step-xy.sln) in that directory and
 275    compile/run/debug.
 276
 277 ## Running build tests on Windows:
 278
 279 Install git and mingw (for perl etc). Then create a .bat file:
 280 ```
 281 git pull origin master
 282 rmdir /Q /S buildtest17
 283 mkdir buildtest17
 284 cd buildtest17
 285 ctest -C Debug -DMAKEOPTS="/m:1" -DCTEST_CMAKE_GENERATOR="Visual Studio 15 2017" -S ../tests/run_buildtest.cmake -V
 286 cd ..
 287 ```
 288
 289 ## Cygwin / MingGW
 290
 291 Cygwin and forks such as MinGW and MinGW-64 are unsupported due to multiple
 292 unresolved miscompilation issues.
 293
 294 ## Other Windows compilers
 295
 296 We haven't had much success with any other compiler on Windows (Intel,
 297 Borland, ...).