Docs: Update with more sections

4 files changed, 108 insertions, 0 deletions

diff --git a/docs/src/gettingstarted/README.md b/docs/src/gettingstarted/README.md
new file mode 100644
index 0000000..152d491
--- /dev/null
+++ b/docs/src/gettingstarted/README.md
@@ -0,0 +1,2 @@
+# Getting Started
+This chapter contains the steps to get started with the Go library. You will learn how to build the library, what the structure of the library is and how to test the code.
diff --git a/docs/src/gettingstarted/building.md b/docs/src/gettingstarted/building.md
new file mode 100644
index 0000000..8747cd7
--- /dev/null
+++ b/docs/src/gettingstarted/building.md
@@ -0,0 +1,65 @@
+# Building
+To build the Go library, you need the dependencies for your system installed. We will go over the needed dependencies for Linux and Windows. Afterwards, we explain the basic commands to build the library.
+## 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
+
+## Commands
+To build the shared library for the current platform issue the following command in the root directory:
+
+```bash
+make
+```
+
+Build shared library for specified OS & architecture (example):
+
+```bash
+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:
+
+```bash
+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/).
+
+### Cleaning
+Clean built libraries and wrapper builds:
+
+```bash
+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=...`.
diff --git a/docs/src/gettingstarted/debugging.md b/docs/src/gettingstarted/debugging.md
new file mode 100644
index 0000000..1e584c9
--- /dev/null
+++ b/docs/src/gettingstarted/debugging.md
@@ -0,0 +1 @@
+# Debugging
diff --git a/docs/src/gettingstarted/testing.md b/docs/src/gettingstarted/testing.md
new file mode 100644
index 0000000..f89757e
--- /dev/null
+++ b/docs/src/gettingstarted/testing.md
@@ -0,0 +1,40 @@
+# Testing
+To test the Go code, issue the following command in a shell
+
+## Testing the Go code
+```bash
+make test-go
+```
+
+Note that this runs the tests without any server interaction. To run the tests with an eduVPN server you need to specify environment variables:
+
+```bash
+SERVER_URI="eduvpn.example.com" PORTAL_USER="example" PORTAL_PASS="example" make test-go
+```
+
+If you have [Docker](https://www.docker.com/get-started/) installed and [Docker-compose](https://docs.docker.com/compose/install/) you can use a convenient helper script which starts up two containers
+- An eduvpnserver for testing
+- A Go container that builds and runs the test-suite
+
+```bash
+PORTAL_USER="example" PORTAL_PASS="example" ./ci/startcompose.sh
+```
+
+This script is also used in the continuous integration, so we recommend to run this before you submit any changes.
+## Testing the wrappers
+To test the wrappers, issue the following command in a shell (you will need compilers for all wrappers if you do this):
+
+```bash
+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 everything
+To test all the code at once, issue the following command:
+```bash
+make test
+```
+
+This accepts the same environment variables as we have explained before.