From debad07ebd99f7ab0777a8eea09c4501ae8e8d61 Mon Sep 17 00:00:00 2001
From: Lars Bilke <lars.bilke@ufz.de>
Date: Fri, 15 May 2020 11:21:24 +0200
Subject: [PATCH] [web] Added docs on WSL usage.
---
web/content/docs/devguide/advanced/wsl.pandoc | 44 +++++++++++++++++++
.../getting-started/prerequisites.pandoc | 7 +++
.../devguide/troubleshooting/build.pandoc | 5 +++
3 files changed, 56 insertions(+)
create mode 100644 web/content/docs/devguide/advanced/wsl.pandoc
diff --git a/web/content/docs/devguide/advanced/wsl.pandoc b/web/content/docs/devguide/advanced/wsl.pandoc
new file mode 100644
index 00000000000..36b5be87dd0
--- /dev/null
+++ b/web/content/docs/devguide/advanced/wsl.pandoc
@@ -0,0 +1,44 @@
++++
+date = "2020-05-15T10:46"
+title = "Windows Subsystem for Linux"
+author = "Lars Bilke"
+weight = 1042
+
+[menu]
+ [menu.devguide]
+ parent = "advanced"
++++
+
+The [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) is an alternative way to setup a complete development environment on Windows. It offers a Linux environment with a seamless bridge to the Windows world. We recommend this setup for Windows developers.
+
+## Setup
+
+- Install WSL by following [this guide](https://www.windowscentral.com/install-windows-subsystem-linux-windows-10). **Important:** Choose **Ubuntu 20.04 LTS** as the Linux distribution. Other distros may not have a sufficient compiler.
+- Follow the [developer guide for Linux]({{< ref "prerequisites.pandoc" >}}) from now on.
+
+## Using Visual Studio Code as IDE
+
+You can use the native Windows Visual Studio Code IDE (VS Code) for developing in the WSL. It offers code completion, CMake integration, an integrated debugger, git integration and more.
+
+### Setup
+
+- In the WSL shell run `sudo apt update && sudo apt install -y ninja-build gdb`.
+- On Windows [install Visual Studio Code](https://code.visualstudio.com/docs/setup/windows)
+- Open VS Code and install the [VS Code Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) extension
+- In the WSL shell go to your OGS source code and run `code .`. This will open the source code in VS Code.
+- Install the [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools), [CMake](https://marketplace.visualstudio.com/items?itemName=twxs.cmake) and [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) extensions
+
+### Build and debug OGS
+
+- Configure your project by following [this guide](https://vector-of-bool.github.io/docs/vscode-cmake-tools/getting_started.html#configuring-your-project). Select `GCC 9.3.0` as the [CMake kit](https://vector-of-bool.github.io/docs/vscode-cmake-tools/kits.html#kits).
+- Follow [this guide](https://vector-of-bool.github.io/docs/vscode-cmake-tools/debugging.html#selecting-a-launch-target) for debug a target. Select `ogs` as the debug target.
+
+## Additional notes
+
+The filesystem of the WSL is not inside your regular user directories. You can find it by running `explorer.exe .` inside the WSL shell. It should be something like `\\wsl$\Ubuntu-20.04\home\[username]\...`.
+
+You can also run OGS inside the WSL with benchmarks located in your regular Windows directories. You regular filesystem can be accessed inside WSL with the `/mnt/c/`-prefix. E.g. to run an OGS benchmark:
+
+```bash
+bin/ogs -o _out /mnt/c/Users/[username]/ogs-src/Tests/Data/Elliptic/square_1x1_SteadyStateDiffusion/square_1e0.prj
+```
diff --git a/web/content/docs/devguide/getting-started/prerequisites.pandoc b/web/content/docs/devguide/getting-started/prerequisites.pandoc
index e7ee87b1804..d5c68ea1a5a 100644
--- a/web/content/docs/devguide/getting-started/prerequisites.pandoc
+++ b/web/content/docs/devguide/getting-started/prerequisites.pandoc
@@ -22,6 +22,13 @@ The minimum prerequisites to build OGS are:
## Step: Install a compiler
::: {.win}
+
+::: {.note}
+### Alternative setup
+
+Please note that the following setup on Windows is the **native Windows development setup**. This native setup is **quite involved** and **heavy on system resources**. We can recommend an alternative setup in which the [Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) is used: Setup and development of OGS follows the Linux way but you can use your Windows IDE (especially Visual Studio Code) for development and debugging. If this sounds interesting please [follow the steps here]({{< ref "wsl.pandoc" >}})!
+:::
+
As we use lots of features of the C++17-standard we support **Visual Studio {{< dataFile "versions.minimum_version.msvc.year" >}}** and up. Therefore you will need at least **Windows 7** (64-bit recommended). It is perfectly fine to use the free Community Edition of Visual Studio.
- Download and install [Visual Studio Community](https://www.visualstudio.com)
diff --git a/web/content/docs/devguide/troubleshooting/build.pandoc b/web/content/docs/devguide/troubleshooting/build.pandoc
index cbd96298b28..1fa0ca0e783 100644
--- a/web/content/docs/devguide/troubleshooting/build.pandoc
+++ b/web/content/docs/devguide/troubleshooting/build.pandoc
@@ -12,6 +12,10 @@ weight = 1043
## Visual Studio out-of-heap or stackoverflow errors
+::: {.note}
+**Note:** To prevent this you can also use the [WSL setup]({{< ref "wsl.pandoc" >}}).
+:::
+
The compilation especially of the processes in Release-config can be very memory hungry. Using dynamic Eigen shape matrices can reduce memory usage:
```
@@ -29,3 +33,4 @@ If this still fails you can disable building of the failing processes, e.g.:
```
cmake . -DOGS_BUILD_PROCESS_HT=OFF
cmake --build . --config Release -j 1
+```
--
GitLab