Skip to main content

morph.toml

morph.toml is the canonical entry point for a Morph package (under morphs/<Name>/): [package], [include], [tokens], [runtime.*], provider imports/exports, and other manifest tables.

This file is the root of the plugin graph for that package: it is how the compiler discovers exports, runtime families, routes, and composition with other packages—see Plugin-governed pipeline.

For an application or library project created with morph new, the root file is also named morph.toml, but its schema matches the CLI project loader ([project], [build], [dependencies], [web], …). See the end-user reference: Toolchain: morph.toml.

What It Does​

The package manifest declares package identity and package-owned capabilities such as:

  • package metadata (library path, dependencies, ABI version)
  • imports and exports (provider edges to other packages)
  • [include] — which feature.toml / block.toml / other TOML fragments belong to this package
  • [tokens] — lexer token_requests that forms and ops reference by stable id
  • runtime — [runtime.family.*], [runtime.bundle.*] (shared C sources, per-platform slices)
  • [build] — nir_sources, sema_sources, codegen_sources, cli_sources, library_sources, …
  • [diagnostics] — error catalog prefix for package-owned messages
  • tooling descriptors where the package exposes nested CLI surfaces

One package, one canonical manifest root. Nested feature.toml / block.toml files are fragments; they only load if [include] names them—see Feature manifests and the Plugin-governed pipeline tour.

Section cheat sheet (package manifest)​

SectionRole
[package]Identity: domain, abi, library, enabled, dependencies, …
[tokens]Keyword/punctuator requests surfaced in grammar
[import.*] / [export.*]Cross-package provider wiring
[include]Globs listing features/*/feature.toml, blocks/*/block.toml, etc.
[runtime.family.*]Named runtime import families + symbol LLVM signatures
[runtime.bundle.*]Source lists for linking (native shared, web, per-OS slices)
[build]C++ translation units compiled into the morph library
[diagnostics]prefix for this package’s diagnostic namespace

Open morphs/Core/morph.toml, morphs/GPU/morph.toml, and morphs/Wasm/morph.toml side by side: they differ because domain ownership differs, not because the “rules” change.

Minimal Shape​

[package]
domain = "example"
owner = "Morph"
abi = 1

[include]
files = [
  "features/*/feature.toml",
  "blocks/*/block.toml",
]

This says:

  • the package exists
  • the package has an identity
  • feature and syntax-block fragments are loaded explicitly

Omit blocks/*/block.toml only when the package truly has no [forms.*] surfaces (many small packages still use [build]-listed sources without a separate blocks/ tree—verify in morph.toml).

Include Fragments​

morph.toml stays readable by including nested manifests instead of inlining everything:

[include]
files = [
  "features/*/feature.toml",
  "blocks/*/block.toml",
]

The split is physical (one TOML per feature group or syntax block folder). The truth source is still the single package root: if a path is not under [include], the compiler does not load it as part of this package’s graph.

Some packages add extra globs (for example nested runtime TOML) as the repo grows—always trust the package you are editing, not a stale doc example.

What Should Live Here​

Use morph.toml for package-wide declarations:

  • package identity
  • include rules
  • package-level imports and exports
  • package-owned runtime and build metadata
  • tooling or execution descriptors that are package-wide

Use feature fragments for feature-specific declarations.

What Should Not Happen​

Do not create a feature by editing unrelated core configuration code.

If the package needs a new descriptor type and morph.toml cannot express it yet, widen the framework manifest model first. Do not bypass the manifest with manual registration as a shortcut.

Example Direction​

For a build provider package:

  • morph.toml should declare package identity and provider-level metadata
  • features/build/... should declare feature-specific build pipeline behavior

For a test package:

  • morph.toml should declare package-level runtime or tooling metadata
  • features/... should declare test syntax, assertions, and runner behavior

Next Steps​