a bit more wiki (Linux subsystem)
[dealii.wiki.git] / 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 ## 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    (<i>TODO: replace with `testing`</i>)
50
51 6. Now update/upgrade the system by running
52    ```console
53    root@computer# apt update
54    [...]
55
56    root@computer# apt dist-upgrade
57    [...]
58    Do you want to continue? [Y/n] <Enter>
59    [...]
60
61    root@computer# apt autoremove
62    [...]
63    Do you want to continue? [Y/n] <Enter>
64    [...]
65    ```
66
67 ## Installing the deal.II library and tools
68
69 We continue the installation process by installing the deal.II library with
70 development headers and documentation. The packages in Debian (or Ubuntu)
71 are called `libdeal.ii-dev` and `libdeal.ii-doc`:
72
73 1. As root user (see above) run:
74    ```console
75    root@computer# apt install libdeal.ii-dev libdeal.ii-doc
76    [... long list ...]
77    0 upgraded, 443 newly installed, 0 to remove and 0 not upgraded.
78    Need to get 441 MB of archives.
79    After this operation, 2,016 MB of additional disk space will be used.
80    Do you want to continue? [Y/n] <Enter>
81    ```
82
83    At this point, let us install a number of useful, additional tools:
84    ```console
85    root@computer# apt install build-essential cmake ninja-build gdb clang clang-format
86    [...]
87    Do you want to continue? [Y/n] <Enter>
88    ```
89
90    If you plan to use MSVC, you will also need to install ssh, zip and
91    unzip:
92    ```console
93    root@computer# apt install ssh zip unzip
94    [...]
95    Do you want to continue? [Y/n] <Enter>
96    ```
97
98    Now, exit the root account:
99    ```console
100    root@computer# exit
101    user@computer$
102    ```
103
104 2. Do a quick "smoke test" whether everything installed fine by compiling
105    and running the first example step:
106    ```console
107    user@computer$ cd
108    user@computer$ cp -r /usr/share/doc/libdeal.ii-doc/examples/step-55 .
109    user@computer$ cd step-55
110    user@computer$ cmake .
111    user@computer$ make release
112    user@computer$ make run
113    [...]
114    [100%] Built target run
115    ```
116
117 ## Installing Microsoft Visual Studio Community Edition
118
119 1. Go to the [Microsoft website](https://www.visualstudio.com/downloads)
120    and download Microsoft Visual Studio Community Edition
121
122 2. Launch the web installer. Make sure to select "Linux development with C++"
123
124 3. Restart.
125
126 ### Create MSVC project
127
128 Next, let us create a small example project with MSVC. First, you have to
129 decide where the MSVC project shall be located. For this example we will
130 use the directory `workspace` in the (Windows) documents directory of the
131 current user located on driver C.  The corresponding path to access this
132 directory from Linux is `/mnt/c/Users/<user>/Documents/workspace`. (Substitute
133 `<user>` with your Windows user name in the following console listings!)
134
135 1. Copy an example step to the Windows user directory. For this, start the Linux
136    terminal again and `cd` to the user directory and copy and example step:
137    ```console
138    user@computer$ mkdir -p /mnt/c/Users/<user>/Documents/workspace
139    user@computer$ cd /mnt/c/Users/<user>/Documents/workspace
140    user@computer$ cp -r /usr/share/doc/libdeal.ii-doc/examples/step-6 .
141    user@computer$ cd step-6
142    user@computer$ cmake .
143    ```
144
145 2. Start the sshd server:
146    ```console
147    user@computer$ sudo -s
148    root@computer# /etc/init.d/sshd start
149    root@computer# exit
150    ```
151
152 (<i>Warning: The rest of this section is work in progress.</i>)
153
154 3. Now, open Microsoft Visual Studio and click on `File` -> `New` ->
155    `Create New Project from Existing Code Files`. Use
156    `C:\Users\<user>\Documents\workspace\step-6` as "Project file location"
157    and "step-6" as project name. Click next. Select "Use external build
158    system" and click next again.
159
160
161 ## Installing X server
162
163 (<i>TODO: write section</i>)
164
165
166
167 # Using deal.II on native Windows
168
169 For an overview of different ways to use deal.II on Windows have a look at
170 the corresponding [FAQ entry](https://github.com/dealii/dealii/wiki/Frequently-Asked-Questions#can-i-use-dealii-on-a-windows-platform).
171
172 **Warning: please be aware that the following is experimental and you will
173 likely encounter bugs in compilers and deal.II itself. Only continue if you
174 are willing to experiment.**
175
176 ## Visual Studio
177
178 Since deal.II 8.4.0 we have experimental support for the newer Visual
179 Studio C++ compilers (2017 or newer), but this is still work in progress.
180 You can check the current development status
181 [here](https://github.com/dealii/dealii/issues/1921)
182
183 Installation instructions:
184
185 1. Download and install Visual Studio 2017:
186    https://www.visualstudio.com/vs/ and make sure you select the C++
187    compiler
188 2. Install cmake from https://cmake.org/download/ (pick the windows
189    installer)
190 3. Extract deal.II to a folder, for example c:\dealii (or clone the git
191    development version)
192 4. Configure using cmake by opening the 64bit command line shortcut and
193    run:
194
195    ```
196    set PreferredToolArchitecture=x64
197    cd c:\dealii
198    mkdir build
199    cd c:\dealii\build
200    cmake -G "Visual Studio 15 2017 Win64" ..
201    ```
202    <b>Note:</b> Setting the tool architecture to 64 bit works around problems of
203    the compiler or linker running out of memory and leads to much quicker
204    compile times.
205    <b>Note:</b> Use generator ``"Visual Studio 15 2017 Win64"`` for Visual Studio
206    2017.
207
208 6. Compile and install the library by opening ``deal.II.sln`` in
209    c:\dealii\build, pick the install target and compile. Note: you need to
210    either compile in the same terminal as above (using ``cmake --build .``)
211    or open ``devenv.exe`` from the same terminal, to use the 64 bit tool
212    architecture.
213
214 7. in cmd go to one of the examples in c:\dealii\examples\step-xy:
215    ```
216    cmake -D DEAL_II_DIR=c:\dealii\build -G "Visual Studio 15 2017 Win64" .
217    ```
218
219 8. Open the newly created solution (step-xy.sln) in that directory and
220    compile/run/debug.
221
222 ## Running build tests on Windows:
223
224 Install git and mingw (for perl etc). Then create a .bat file:
225 ```
226 git pull origin master
227 rmdir /Q /S buildtest17
228 mkdir buildtest17
229 cd buildtest17
230 ctest -C Debug -DMAKEOPTS="/m:1" -DCTEST_CMAKE_GENERATOR="Visual Studio 15 2017" -S ../tests/run_buildtest.cmake -V
231 cd ..
232 ```
233
234 ## Cygwin / MingGW
235
236 Cygwin and forks such as MinGW and MinGW-64 are unsupported due to multiple
237 unresolved miscompilation issues.
238
239 ## Other Windows compilers
240
241 We haven't had much success with any other compiler on Windows (Intel,
242 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.