Docs: Move to mdbook

3 files changed, 109 insertions, 0 deletions

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
new file mode 100644
index 0000000..211d9eb
--- /dev/null
+++ b/docs/src/SUMMARY.md
@@ -0,0 +1,4 @@
+# Summary
+
+- [About](./about.md)
+- [Installation](./installation.md)
diff --git a/docs/src/about.md b/docs/src/about.md
new file mode 100644
index 0000000..ac61279
--- /dev/null
+++ b/docs/src/about.md
@@ -0,0 +1,16 @@
+# About
+This chapter contains background information for the library.
+
+## eduVPN introduction
+eduVPN-common is a library for [eduVPN](https://www.eduvpn.org/), which is a VPN by [Surf](https://www.surf.nl) for research institutions such as Universities. Each institution that  uses eduVPN has its own server. To discover these servers and establish a VPN connection with them, eduVPN clients are used. eduVPN has clients for each common platform:
+- [Android](https://github.com/eduvpn/android)
+- [Linux](https://github.com/eduvpn/python-eduvpn-client)
+- [MacOS/iOS](https://github.com/eduvpn/apple)
+- [Windows](https://github.com/Amebis/eduVPN)
+
+## The problem
+However, as these clients are rather similar in functionality, apart from platform specific differences, right now there is duplicate code between them. For example, the process to discover institution's servers, the authorization process (OAuth) and Wireguard key generation.
+This goal of this library is to provide the common functionality between these clients into one codebase. The library is written in the [Go](https://go.dev/) language and has wrapper code for each of the languages that are used by the current clients.
+
+## Authors
+This library is written by [Steven Wallis de Vries](https://github.com/stevenwdv) and [Jeroen Wijenbergh](https://github.com/jwijenbergh), two Radboud University students that worked at Surf for their research internship.
diff --git a/docs/src/installation.md b/docs/src/installation.md
new file mode 100644
index 0000000..3a823cd
--- /dev/null
+++ b/docs/src/installation.md
@@ -0,0 +1,89 @@
+# Installation and building
+This chapter contains the instructions to build and install the Go library.
+## Dependencies
+This section contains the dependencies needed to build the library on Linux and Windows
+### Linux
+To build the GO shared library using Linux you need the following dependencies:
+
+- [Go](https://go.dev/doc/install) 1.15 or later
+- [Gcc](https://gcc.gnu.org/)
+- [GNU Make](https://www.gnu.org/software/make/)
+- Dependencies for each wrapper you are interested in
+
+### Windows
+On Windows, you can install gcc and make (or even Go) via MinGW or Cygwin or use WSL. For MinGW:
+
+1. [Install MinGW](https://www.msys2.org/#installation) (you don't need to install any extra packages yet) and open some
+   MSYS2 terminal (e.g. from the start menu or one of the installed binaries)
+2. Install the [`make`](https://packages.msys2.org/package/make?repo=msys) package (`pacman -S make`) (or
+   e.g. [`mingw-w64-x86_64-make`](https://packages.msys2.org/package/mingw-w64-x86_64-make?repo=mingw64) and
+   use `mingw32-make` in the command line)
+3. To compile for x86_64:
+    1. Install the [`mingw-w64-x86_64-gcc`](https://packages.msys2.org/package/mingw-w64-x86_64-gcc?repo=mingw64)
+       package
+    2. Open the MinGW 64-bit console, via the start menu, or in your current
+       terminal: `path/to/msys64/msys2_shell.cmd -mingw64 -defterm -no-start -use-full-path`
+    3. Run the make commands in the project directory
+4. To compile for x86 (32-bit):
+    1. Install the [`mingw-w64-i686-gcc`](https://packages.msys2.org/package/mingw-w64-i686-gcc?repo=mingw32) package
+    2. Open the MinGW 32-bit console, via the start menu, or in your current
+       terminal: `path/to/msys64/msys2_shell.cmd -mingw32 -defterm -no-start -use-full-path`
+    3. Run the make commands in the project directory
+
+## Building
+To build the shared library for the current platform issue the following command in the root directory:
+
+```shell
+make
+```
+
+Build shared library for specified OS & architecture (example):
+
+```shell
+make GOOS=windows GOARCH=386
+```
+
+To list all platforms supported by cgo, run `go tool dist list`.
+
+Results will be output in `exports/lib/`.
+
+Usually you will need to specify the compiler when cross compiling, for example:
+
+```shell
+make GOOS=windows GOARCH=amd64 CC=x86_64-w64-mingw32-gcc
+```
+
+For example, you can cross compile for Windows from Linux using [MinGW-w64](https://www.mingw-w64.org/downloads/).
+
+Test Go code:
+
+```shell
+make test-go
+```
+
+## Testing
+
+To test the wrappers, issue the following command in a shell (you will need compilers for all wrappers if you do this):
+
+```shell
+make test-wrappers
+```
+
+Specify `-j` to execute tests in parallel. You can specify specific wrappers to test by appending
+e.g. `WRAPPERS="csharp php"`.
+
+Test both:
+
+```shell
+make test
+```
+
+Clean built libraries and wrapper builds:
+
+```shell
+make -j clean
+```
+
+Usually you won't need to do this, as changes in the library should automatically be incorporated in wrappers.
+Specify `CLEAN_ALL=1` to also remove downloaded dependencies for some wrappers. You can clean individual wrappers by
+executing clean in their directories, or specify `WRAPPERS=...`.