dde914b8e27bab584887029e581db085c0762255
[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    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 user name 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. Start the sshd server:
200    ```console
201    user@computer$ sudo -s
202    root@computer# /etc/init.d/sshd start
203    root@computer# exit
204    ```
205
206 (<i>TODO: Write rest.</i>)
207
208
209
210 # Using deal.II on native Windows
211
212 **Warning: please be aware that the following is experimental and you will
213 likely encounter bugs in compilers and deal.II itself. Only continue if you
214 are willing to experiment.**
215
216 ## Visual Studio
217
218 Since deal.II 8.4.0 we have experimental support for the newer Visual
219 Studio C++ compilers (2017 or newer), but this is still work in progress.
220 You can check the current development status
221 [here](https://github.com/dealii/dealii/issues/1921)
222
223 Installation instructions:
224
225 1. Download and install Visual Studio 2017:
226    https://www.visualstudio.com/vs/ and make sure you select the C++
227    compiler
228 2. Install cmake from https://cmake.org/download/ (pick the windows
229    installer)
230 3. Extract deal.II to a folder, for example c:\dealii (or clone the git
231    development version)
232 4. Configure using cmake by opening the 64bit command line shortcut and
233    run:
234
235    ```
236    set PreferredToolArchitecture=x64
237    cd c:\dealii
238    mkdir build
239    cd c:\dealii\build
240    cmake -G "Visual Studio 15 2017 Win64" ..
241    ```
242    <b>Note:</b> Setting the tool architecture to 64 bit works around problems of
243    the compiler or linker running out of memory and leads to much quicker
244    compile times.
245    <b>Note:</b> Use generator ``"Visual Studio 15 2017 Win64"`` for Visual Studio
246    2017.
247
248 6. Compile and install the library by opening ``deal.II.sln`` in
249    c:\dealii\build, pick the install target and compile. Note: you need to
250    either compile in the same terminal as above (using ``cmake --build .``)
251    or open ``devenv.exe`` from the same terminal, to use the 64 bit tool
252    architecture.
253
254 7. in cmd go to one of the examples in c:\dealii\examples\step-xy:
255    ```
256    cmake -D DEAL_II_DIR=c:\dealii\build -G "Visual Studio 15 2017 Win64" .
257    ```
258
259 8. Open the newly created solution (step-xy.sln) in that directory and
260    compile/run/debug.
261
262 ## Running build tests on Windows:
263
264 Install git and mingw (for perl etc). Then create a .bat file:
265 ```
266 git pull origin master
267 rmdir /Q /S buildtest17
268 mkdir buildtest17
269 cd buildtest17
270 ctest -C Debug -DMAKEOPTS="/m:1" -DCTEST_CMAKE_GENERATOR="Visual Studio 15 2017" -S ../tests/run_buildtest.cmake -V
271 cd ..
272 ```
273
274 ## Cygwin / MingGW
275
276 Cygwin and forks such as MinGW and MinGW-64 are unsupported due to multiple
277 unresolved miscompilation issues.
278
279 ## Other Windows compilers
280
281 We haven't had much success with any other compiler on Windows (Intel,
282 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.