The Module Catalog

The official Shinro catalog is a module registry: a git repository shaped as a flat tree, with one descriptor per module version at <name>/<version>.toml. Because a catalog holds descriptors and nothing else, it stays small (a few kilobytes per module), so a project can clone the whole catalog and immediately see everything that can be built from it. Catalog access is currently limited.

What a catalog entry contains

A catalog entry is a descriptor and nothing else. It declares what the module is ([module]), how its content is acquired ([acquire]), what it depends on ([modules.<alias>]), and what it exposes ([provides]). An entry never contains the module’s source code or binaries: acquisition happens at build time, from wherever the descriptor points.

Because every entry is descriptor-only, the smallest entry is just a few lines. This is the minimal shape:

[module]
name    = "cake"
version = "0.1.0"
type    = "tool"
store   = "local"

[acquire]
strategy = "data"
path     = "."

That is what keeps a catalog small enough to clone in full and read end to end.

Using catalog modules in a project

Register the catalog once with the Shinro CLI (invoked as cake):

cake add official https://github.com/Shinro-xyz/gh-catalog

After that, reference any catalog module from app.toml by its alias, in the form official.<name>/<version>:

[modules.sdl3]
module = "official.sdl3/3.2.4"

cake add clones the catalog in clone mode by default, which is what you want: clone mode keeps a writable local copy, and cake promote needs one when you contribute a module back. fetch mode is read-only, which is fine when you only consume catalog modules. For how registries, clone and fetch mode, and promotion work in general, see Creating a Module.

What is in the catalog

The catalog already covers several families of modules:

• Zig toolchain modules: zig-mode, zig-layout, and zig-build.
• C++ builders: cpp-cl, cpp-clang, cpp-gcc, and cpp-clang-cxxmodules.
• Shared build tools: diag-tool and cxx-module-build.
• Libraries such as sdl3.

All of these are ordinary descriptors: once the catalog is registered, they resolve like any other module.

Contributing a module

Contributing a module to the official catalog follows the same path as any other module, ending in a pull request:

1. Develop the module in your project’s draft_modules/ folder. See Creating a Module for how to write and wire a descriptor.
2. Validate the wiring with cake check, then build the module to confirm it works.
3. Run cake promote <name> official to copy the descriptor into your local clone of the catalog. This requires that the catalog was added in clone mode (the cake add default), since cake promote needs a writable clone.
4. Commit and push the catalog clone yourself, then open a pull request against the catalog repository. cake promote deliberately performs no git operations of its own.
5. The catalog owner reviews the pull request and merges it.

See Creating a Module for the draft_modules and cake promote details.

Entry standards

Entries are reviewed against a few standards before they are merged:

• The descriptor contains no module source code; content is acquired at build time.
• No long inline scripts. Where real logic is needed, build a small tool instead.
• No hardcoded machine paths.
• store values are limited to "system" or "local".
• name and version match the descriptor’s file path (<name>/<version>.toml).

These mirror the general guidance in Rules worth keeping.