doc(bridge) Explain how this package works

README.md

@@ -28,15 +28,17 @@ $ export CGO_ENABLED=1; export CC=gcc;
 $ go get github.com/wasmerio/go-ext-wasm/wasmer
 ```
 
-To install the `go-wasmer` CLI, follow the classical:
+It will work on many macOS and Linux distributions. It will not work
+on Windows yet, we are working on it.
+
+If the pre-compiled shared libraries are not compatible with your system, try installing manually with the following command:
 
 ```sh
-$ go install github.com/wasmerio/go-ext-wasm/go-wasmer
+$ just build-runtime
+$ just build
+$ go install github.com/wasmerio/go-ext-wasm/wasmer
 ```
 
-`go install` will work on many macOS and Linux distributions. It will
-not work on Windows yet, we are working on it.
-
 # Documentation
 
 [The documentation can be read online on godoc.org][documentation]. It

justfile

@@ -1,8 +1,12 @@
-# Build the `wasmer` library.
-build go-build-args='-v':
+# Build the runtime shared library for this specific system.
+build-runtime:
 	#!/usr/bin/env bash
 	set -euo pipefail
-	cd wasmer
+
+	# Build the shared library.
+	cargo build --release
+
+	# Find the shared library extension.
 	case "{{os()}}" in
 		"macos")
 			dylib_extension="dylib"
@@ -13,10 +17,21 @@ build go-build-args='-v':
 		*)
 			dylib_extension="so"
 	esac
-	if ! test -f libwasmer_runtime_c_api.${dylib_extension}; then
-		cargo build --release
-		ln -s ../target/release/deps/libwasmer_runtime_c_api-*.${dylib_extension} libwasmer_runtime_c_api.${dylib_extension}
-	fi
+
+	# Link `wasmer/libwasmer_runtime_c_api.*`.
+	rm -f wasmer/libwasmer_runtime_c_api.${dylib_extension}
+	ln -s \
+		'../'$( find target/release -name "libwasmer_runtime_c_api*.${dylib_extension}" -exec stat -n -f '%m ' {} ';' -print | sort -r | head -n 1 | cut -d ' ' -f 2 ) \
+		wasmer/libwasmer_runtime_c_api.${dylib_extension}
+
+	# Link `src/wasmer.h`.
+	rm -f wasmer/wasmer.h
+	ln -s \
+		'../'$( find target/release/build -name 'wasmer.h' -exec stat -n -f '%m ' {} ';' -print | sort -r | head -n 1 | cut -d ' ' -f 2 ) \
+		wasmer/wasmer.h
+
+# Build the `wasmer` library.
+build go-build-args='-v':
 	go build {{go-build-args}} .
 
 # Build the `go-wasmer` bin.

src/lib.rs

@@ -1 +1 @@
-// Empty project, so that we can install Wasmer through Cargo more easily.
+// Empty module, so that we can install Wasmer through Cargo more easily.

wasmer/bridge.go

@@ -6,6 +6,83 @@ package wasmer
 import "C"
 import "unsafe"
 
+// This file is the foundation of this package.
+//
+// [Wasmer] is the WebAssembly runtime used by this package to run
+// WebAssembly modules. It is written in [Rust]. The runtime exposes a C
+// API through [the `wasmer-runtime-c-api` crate][wasmer-runtime-c-api],
+// which is also written in Rust but compiles to C compatible shared
+// libraries. C and C++ headers are also automatically built at
+// compile-time. [Wasmer releases][wasmer-releases] come with
+// pre-compiled `.dylib` and `.so` shared libraries. It is also possible
+// to re-compile specific shared libraries with this project. In this
+// package, they are located in the root as
+// `libwasmer_runtime_c_api\..*`.
+//
+// Go provides [cgo] that enables the creation of Go packages that
+// call C code. This package uses cgo to communicate with Wasmer through
+// C.
+//
+// This `bridge.go` file contains a thin layer on top of the cgo
+// generated code to get a more user-friendly API. It is the only place
+// where data transit from Go to the Wasmer runtime. Any new features
+// provided by Wasmer that needs to be exposed in this package must be
+// “described” here.
+//
+// Schematically, the workflow looks like this:
+//
+//     +------------------------------+
+//     |                              |
+//     |  +------------------------+  |
+//     |  |                        |  |
+//     |  |          Go            |  |
+//     |  |                        |  |
+//     |  +----+--------------+----+  |
+//     |       |              ^       |
+//     |       v              |       |
+//     |  +----+--------------+----+  |
+//     |  |                        |  |
+//     |  |       bridge.go        |  |   go-ext-wasm/wasmer
+//     |  |                        |  |
+//     |  +----+--------------+----+  |
+//     |       |              ^       |
+//     |       v              |       |
+//     |  +----+--------------+----+  |
+//     |  |                        |  |
+//     |  |          cgo           |  |
+//     |  |                        |  |
+//     |  +----+--------------+----+  |
+//     |       |              ^       |
+//     +-------|--------------|-------+
+//     |       v              |       |
+//     |  +----+--------------+----+  |
+//     |  |                        |  |
+//     |  |  wasmer-runtime-c-api  |  |
+//     |  |                        |  |
+//     |  +----+--------------+----+  |
+//     |       |              ^       |   Wasmer runtime
+//     |       v              |       |   (shared library)
+//     |  +----+--------------+----+  |
+//     |  |                        |  |
+//     |  |     Wasmer runtime     |  |
+//     |  |                        |  |
+//     |  +------------------------+  |
+//     |                              |
+//     +------------------------------+
+//
+// The cgo part is auto-generated by Go. It should be considered
+// as an opaque black-box.
+//
+// Thanks to `bridge.go`, the rest of this package can talk to the
+// Wasmer runtime as if it is almost regular Go code.
+//
+//
+// [Wasmer]: https://github.com/wasmerio/wasmer
+// [Rust]: https://www.rust-lang.org/
+// [wasmer-runtime-c-api]: https://github.com/wasmerio/wasmer/tree/master/lib/runtime-c-api
+// [wasmer-releases]: https://github.com/wasmerio/wasmer/releases
+// [cgo]: https://golang.org/cmd/cgo/
+
 type cBool C.bool
 type cChar C.char
 type cInt C.int