container: provide usage example

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

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

4 files changed, 47 insertions, 3 deletions

diff --git a/container/check/absolute.go b/container/check/absolute.go
index 83ae8cc4..fcb260c5 100644
--- a/container/check/absolute.go
+++ b/container/check/absolute.go
@@ -56,7 +56,7 @@ func NewAbs(pathname string) (*Absolute, error) {
 // MustAbs calls [NewAbs] and panics on error.
 func MustAbs(pathname string) *Absolute {
 	if a, err := NewAbs(pathname); err != nil {
-		panic(err.Error())
+		panic(err)
 	} else {
 		return a
 	}
diff --git a/container/check/absolute_test.go b/container/check/absolute_test.go
index 91cd3c92..107407f3 100644
--- a/container/check/absolute_test.go
+++ b/container/check/absolute_test.go
@@ -84,9 +84,9 @@ func TestNewAbs(t *testing.T) {
 		t.Parallel()
 
 		defer func() {
-			wantPanic := `path "etc" is not absolute`
+			wantPanic := &AbsoluteError{Pathname: "etc"}
 
-			if r := recover(); r != wantPanic {
+			if r := recover(); !reflect.DeepEqual(r, wantPanic) {
 				t.Errorf("MustAbs: panic = %v; want %v", r, wantPanic)
 			}
 		}()
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()
 
diff --git a/package.nix b/package.nix
index b8518a94..21aee353 100644
--- a/package.nix
+++ b/package.nix
@@ -24,6 +24,7 @@
 
   # for check
   util-linux,
+  nettools,
 
   glibc, # for ldd
   withStatic ? stdenv.hostPlatform.isStatic,
@@ -98,6 +99,9 @@ buildGoModule rec {
   nativeBuildInputs = [
     pkg-config
     makeBinaryWrapper
+
+    # for container example
+    nettools
   ];
 
   postInstall =