container: provide usage example

This requires cgo so unfortunately will not run in the playground.

Signed-off-by: Ophestra <cat@gensokyo.uk>

1 files changed, 40 insertions, 0 deletions

diff --git a/container/container_test.go b/container/container_test.go
index 49797607..ecd3a1d7 100644
--- a/container/container_test.go
+++ b/container/container_test.go
@@ -21,6 +21,7 @@ import (
 	"hakurei.app/command"
 	"hakurei.app/container"
 	"hakurei.app/container/check"
+	"hakurei.app/container/fhs"
 	"hakurei.app/container/seccomp"
 	"hakurei.app/container/std"
 	"hakurei.app/container/vfs"
@@ -29,6 +30,45 @@ import (
 	"hakurei.app/message"
 )
 
+// Note: this package requires cgo, which is unavailable in the Go playground.
+func Example() {
+	// Must be called early if the current process starts containers.
+	container.TryArgv0(nil)
+
+	// Configure the container.
+	z := container.New(context.Background(), nil)
+	z.Hostname = "hakurei-example"
+	z.Proc(fhs.AbsProc).Dev(fhs.AbsDev, true)
+	z.Stdin, z.Stdout, z.Stderr = os.Stdin, os.Stdout, os.Stderr
+
+	// Bind / for demonstration.
+	z.Bind(fhs.AbsRoot, fhs.AbsRoot, 0)
+	if name, err := exec.LookPath("hostname"); err != nil {
+		panic(err)
+	} else {
+		z.Path = check.MustAbs(name)
+	}
+
+	// This completes the first stage of container setup and starts the container init process.
+	// The new process blocks until the Serve method is called.
+	if err := z.Start(); err != nil {
+		panic(err)
+	}
+
+	// This serves the setup payload to the container init process,
+	// starting the second stage of container setup.
+	if err := z.Serve(); err != nil {
+		panic(err)
+	}
+
+	// Must be called if the Start method succeeds.
+	if err := z.Wait(); err != nil {
+		panic(err)
+	}
+
+	// Output: hakurei-example
+}
+
 func TestStartError(t *testing.T) {
 	t.Parallel()