diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/index.md | 95 |
1 files changed, 74 insertions, 21 deletions
diff --git a/docs/index.md b/docs/index.md index 0989f45..b802c10 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,37 +1,90 @@ -## Welcome to GitHub Pages +## Welcome to the eduVPN-common documentation -You can use the [editor on GitHub](https://github.com/jwijenbergh/eduvpn-common/edit/main/docs/index.md) to maintain and preview the content for your website in Markdown files. +This is the documentation for eduVPN-common, a shared GO library to be used as a common codebase between eduVPN clients. This library is a WIP and is not production ready. -Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files. +### Dependencies +#### Linux +To build the GO shared library using Linux you need the following dependencies: -### Markdown +- [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 -Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for +#### Windows +On Windows, you can install gcc and make (or even Go) via MinGW or Cygwin or use WSL. For MinGW: -```markdown -Syntax highlighted code block +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 -# Header 1 -## Header 2 -### Header 3 +### Building +Build shared library for current platform: -- Bulleted -- List +```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 +``` -1. Numbered -2. List +### Testing -**Bold** and _Italic_ and `Code` text +To tesst wrappers, issue the following command in a shell (you will need compilers for all wrappers if you do this): -[Link](url) and  +```shell +make test-wrappers ``` -For more details see [Basic writing and formatting syntax](https://docs.github.com/en/github/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax). +Specify `-j` to execute tests in parallel. You can specify specific wrappers to test by appending +e.g. `WRAPPERS="csharp php"`. + +Test both: -### Jekyll Themes +```shell +make test +``` -Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/jwijenbergh/eduvpn-common/settings/pages). The name of this theme is saved in the Jekyll `_config.yml` configuration file. +Clean built libraries and wrapper builds: -### Support or Contact +```shell +make -j clean +``` -Having trouble with Pages? Check out our [documentation](https://docs.github.com/categories/github-pages-basics/) or [contact support](https://support.github.com/contact) and we’ll help you sort it out. +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=...`. |