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