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