Windows.md

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