docs: document the rust and regen subcommands

README gains `rust` and `regen` entries in the command reference, a
"Rust output (experimental)" section showing the generated crate's shape
and load API, and a "Regenerating a tree with gloam regen" section under
the provenance material.  docs/manifest.md points at `gloam regen` as
the automated form of the --lock replay it describes.  CONTRIBUTING's
pipeline sketch and module map pick up generator/rust/ and regen.rs, and
CLAUDE.md's design philosophy no longer claims there is no active non-C
backend.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tycho

.claude/CLAUDE.md

@@ -27,10 +27,11 @@ used throughout for insertion-order preservation. Never introduce
 non-determinism (HashMap iteration order, random seeds, etc.) and minimize
 unnecessary output churn.
 
-**C is the target.** C output is universally compatible — it works in C++
-projects too. The `generator/c/` directory structure allows for future
-backends, but there is no active non-C backend. Focus effort on the
-C generator.
+**C is the primary target.** C output is universally compatible — it works
+in C++ projects too. An experimental Rust backend (`generator/rust/`)
+covers GL/GLES only; it shares the resolver, so the two backends detect
+extensions identically. The C generator remains the main focus, and new
+resolver/selection features must land in C first.
 
 **Merged output is the primary use case.** `--merge` with GL+GLES2 is how
 the loader is actually used in production (Darwinia runs on desktop GL or

CONTRIBUTING.md

@@ -14,7 +14,7 @@ CLI args
   -> fetch/bundled XML specs
   -> parse into RawSpec (IR)
   -> resolve into FeatureSet (indexed, sorted, grouped)
-  -> generate C code via minijinja templates
+  -> generate C code via minijinja templates (or Rust via string emission)
 ```
 
 ### Module map
@@ -28,6 +28,7 @@ CLI args
 | `fetch.rs` | Load specs from bundled copies or remote Khronos URLs (`--fetch`) |
 | `build_info.rs` | Git version metadata embedded at compile time (generated by `build.rs`) |
 | `preamble.rs` | Copyright/license/provenance comment block for generated files |
+| `regen.rs` | `gloam regen`: replays each tree's recorded command line to regenerate it in place |
 | **`parse/`** | **XML -> `RawSpec` IR** |
 | `parse/mod.rs` | Orchestrator; raw C text extraction, enum value computation |
 | `parse/types.rs` | `<types>` -> `RawType[]` with topological sort (Kahn's algorithm) |
@@ -48,6 +49,7 @@ CLI args
 | **`generator/`** | **`FeatureSet` -> output files** |
 | `generator/c/mod.rs` | C generator: template rendering, function-name blob layout, aux header copying |
 | `generator/c/templates/` | Minijinja templates (`header.h.j2`, `source.c.j2`, `hash_search.j2`, `library.j2`, `loader.j2`, etc.) |
+| `generator/rust/mod.rs` | Rust generator (experimental; GL/GLES): emits a self-contained `#![no_std]` crate by string emission |
 
 ### Key data types
 

README.md

@@ -6,9 +6,10 @@
 [crates.io]: https://crates.io/crates/gloam
 
 A loader generator for Vulkan, OpenGL, OpenGL ES, EGL, GLX, and WGL.
-Reads Khronos XML spec files and generates C dispatch code. The gloam
-binary is fully self-contained — XML specs and auxiliary headers are
-embedded at compile time.
+Reads Khronos XML spec files and generates C dispatch code, with an
+experimental Rust backend for GL/GLES. The gloam binary is fully
+self-contained — XML specs and auxiliary headers are embedded at compile
+time.
 
 ## Why gloam?
 
@@ -168,6 +169,17 @@ Commands:
                   (vk_platform.h, vk_video/*) are not bundled in the
                   output directory.
 
+  rust  Generate a Rust loader (experimental; GL and GLES only). Emits a
+        self-contained #![no_std] crate — Cargo.toml plus src/lib.rs —
+        instead of C sources. See "Rust output" below.
+        --alias   Enable bijective function-pointer alias resolution at
+                  load time (same semantics as the C generator).
+        --mx-global
+                  Also emit a process-global context with free-function
+                  dispatch (gl::DrawArrays(...) after `use gloam_gl as
+                  gl`), the analogue of the C loader's global-context
+                  macros.
+
   lock  Write a provenance-only snapshot manifest (no loader output)
         pinning every supported upstream source — at the current bundle,
         or at upstream HEAD with --fetch. Reuse it later with --lock.
@@ -177,6 +189,19 @@ Commands:
                   all match it keeps its previously recorded
                   commit/describe; delete the file to force a full
                   re-snapshot.
+
+  regen Regenerate existing gloam output trees in place by replaying the
+        command line recorded in each tree's .gloam/manifest.json. Takes
+        any number of paths — a tree root, a directory to search
+        recursively (also finds `gloam lock` snapshots), or a manifest
+        file itself [default: .]. The output path is derived from each
+        manifest's own location, so regeneration works from any working
+        directory. By default every tree is pinned to its recorded
+        provenance, so output changes only if gloam itself changed. See
+        "Regenerating a tree with gloam regen" below.
+        --fresh   Re-resolve sources instead (bundled, or upstream HEAD
+                  if the recorded command used --fetch), advancing the
+                  tree — the update workflow.
 ```
 
 ### Extension selection flags
@@ -254,6 +279,31 @@ changed. Unlike an explicit `--lock`, the baseline is best-effort rather than a
 contract: sources missing from the old manifest resolve fresh (advancing their
 whole repo) instead of being refused.
 
+### Regenerating a tree with `gloam regen`
+
+Because every output tree records its own command line, a checked-in tree is
+self-describing — you don't need to remember (or script) the invocation that
+produced it:
+
+```sh
+gloam regen path/to/gloam           # reproduce the tree with this gloam
+gloam regen --fresh path/to/gloam   # advance it to this gloam's bundle
+```
+
+`gloam regen` replays the recorded command with the current gloam. The output
+path is derived from the manifest's own location (the recorded `--out-path`
+was relative to the original invocation's working directory, so it is treated
+as a historical record and re-recorded verbatim), which means regeneration
+works from any directory. A directory argument is searched recursively, so one
+command can regenerate several vendored trees at once; bare `gloam lock`
+snapshots found along the way are re-snapshotted in place.
+
+By default each tree is pinned to its recorded provenance — with an unchanged
+gloam the result is byte-identical, and after upgrading gloam the diff shows
+exactly what the new version changed. `--fresh` re-resolves sources instead
+(the embedded bundle, or upstream HEAD if the recorded command used
+`--fetch`), which is how you pull in new spec content.
+
 ## Generated output
 
 ### Context struct and dispatch
@@ -457,6 +507,40 @@ if(UNIX)
 endif()
 ```
 
+## Rust output (experimental)
+
+The `rust` subcommand generates the loader as a self-contained Rust crate
+instead of C sources. It currently covers GL and GLES only:
+
+```sh
+gloam --api gl:core=3.3,gles2=3.0 --merge --out-path gloam rust --alias --mx-global
+```
+
+This emits `Cargo.toml` and `src/lib.rs` (crate name `gloam_<stem>`, e.g.
+`gloam_gl`) — add it to your workspace or reference it by path. The crate is
+`#![no_std]` with a single dependency (`xxhash-rust`, for the same XXH3
+extension detection the C loader uses; the two backends detect identically).
+
+Loading takes a `GetProcAddress`-style closure and returns a context struct
+with an `#[inline]` dispatch method per command plus feature/extension
+presence queries:
+
+```rust
+use gloam_gl::*;
+
+let gl = unsafe { Gl::load_gl(|name| display.get_proc_address(name))? };
+unsafe { gl.Clear(GL_COLOR_BUFFER_BIT) };
+if gl.VERSION_3_3() { /* GL 3.3 core available */ }
+if gl.KHR_debug()   { /* KHR_debug available */ }
+```
+
+With `--mx-global`, the crate also emits a process-global context with
+free-function dispatch — the analogue of the C loader's global-context
+macros. After one `load_gl_global(...)`, every command is a free function
+(`gl::DrawArrays(...)`) with no context threading. See
+[examples/rust/gl-triangle](examples/rust/gl-triangle) for a complete
+winit + glutin application using this mode.
+
 ## Bundled specs
 
 gloam embeds compile-time snapshots of upstream Khronos XML specs and

docs/manifest.md

@@ -207,6 +207,13 @@ regenerate with the same or different flags:
 gloam --lock path/to/.gloam/manifest.json --api gl:core=4.6 c --loader
 ```
 
+To reproduce a tree with its *original* flags, `gloam regen <tree>` automates
+this replay: it re-runs the manifest's recorded `command_line` pinned to the
+manifest's own `provenance` (or re-resolved with `--fresh`), deriving the
+output path from the manifest's location so it works from any directory. The
+rest of this section describes the underlying `--lock` mechanism, which regen
+uses and which you drive directly when changing flags.
+
 When reading a `--lock` manifest, gloam uses **only its `provenance` section**.
 The `gloam` and `output` sections of the input are ignored and regenerated
 fresh for the new run.