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

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.