app,internal/debug: define GIODEBUG env var

This commit defines an environment-variable-based debug mechanism allowing
users to toggle various debug features of their applications at runtime. The
only currently supported features are debug logging in the text stack and
suppressing the usage message that would otherwise be printed if you supplied
a malformed GIODEBUG value. The syntax is a comma-delimited list of features
right now. To see the usage, set the variable to the empty string (or any other
unsupported value):

$ GIODEBUG="" go run .

To suppress the usage message, use GIODEBUG=silent. This may be helpful for scripts
trying to activate debug features and inspect their output across versions of Gio
with different debug options available.

Signed-off-by: Chris Waldon <christopher.waldon.dev@gmail.com>

app/window.go

@@ -16,6 +16,7 @@ import (
 	"gioui.org/f32"
 	"gioui.org/font/gofont"
 	"gioui.org/gpu"
+	"gioui.org/internal/debug"
 	"gioui.org/internal/ops"
 	"gioui.org/io/event"
 	"gioui.org/io/key"
@@ -136,6 +137,7 @@ type queue struct {
 // Calling NewWindow more than once is not supported on
 // iOS, Android, WebAssembly.
 func NewWindow(options ...Option) *Window {
+	debug.Parse()
 	// Measure decoration height.
 	deco := new(widget.Decorations)
 	theme := material.NewTheme(gofont.Regular())

internal/debug/debug.go

@@ -0,0 +1,57 @@
+// Package debug provides general debug feature management for Gio, including
+// the ability to toggle debug features using the GIODEBUG environment variable.
+package debug
+
+import (
+	"fmt"
+	"os"
+	"strings"
+	"sync"
+	"sync/atomic"
+)
+
+const (
+	debugVariable = "GIODEBUG"
+	textSubsystem = "text"
+	silentFeature = "silent"
+)
+
+// Text controls whether the text subsystem has debug logging enabled.
+var Text atomic.Bool
+
+var parseOnce sync.Once
+
+// Parse processes the current value of GIODEBUG. If it is unset, it does nothing.
+// Otherwise it process its value, printing usage info the stderr if the value is
+// not understood. Parse will be automatically invoked when the first application
+// window is created, allowing applications to manipulate GIODEBUG programmatically
+// before it is parsed.
+func Parse() {
+	parseOnce.Do(func() {
+		val, ok := os.LookupEnv(debugVariable)
+		if !ok {
+			return
+		}
+		print := false
+		silent := false
+		for _, part := range strings.Split(val, ",") {
+			switch part {
+			case textSubsystem:
+				Text.Store(true)
+			case silentFeature:
+				silent = true
+			default:
+				print = true
+			}
+		}
+		if print && !silent {
+			fmt.Fprintf(os.Stderr,
+				`Usage of %s:
+	A comma-delimited list of debug subsystems to enable. Currently recognized systems:
+
+	- %s: text debug info including system font resolution
+	- %s: silence this usage message even if GIODEBUG contains invalid content
+`, debugVariable, textSubsystem, silentFeature)
+		}
+	})
+}