Skip to main content

Morph Framework Overview

Morph Framework is the plugin and manifest system that owns Morph language features, runtime behavior, backend routes, execution formats, build providers, and tooling commands. The C++ sources in src/ provide the host (pipeline spine, IR containers, diagnostic engine, CLI/LSP shells); morphs/ provides the loadable policy that tells that host which sema rules, lowers, optimizers, LLVM/GPU/shader/NN/REPL routes, runtime symbols, and morph subcommands apply.

Read this first if you wonder “where does Morph’s real power live?” → Plugin-governed pipeline.

Core Idea​

Morph uses a package-first model:

  • Packages own feature behavior end-to-end (surface → sema → NIR/MIR → backend → runtime/tooling), not as scattered one-offs in core.
  • morph.toml / feature.toml / block.toml declare exports, imports, providers, routes, and runtime families so discovery is data-driven.
  • Generated glue + stable ABI (include/morphc/morph/MorphABI.h, package plugin/*, build emission) registers factories into the host at build time.
  • The host composes packages; it does not hardcode every domain.

This means a new language or runtime capability should usually be added by extending a package or creating a new package—and only widening src/ when the framework needs a new hook shape.

Why Morph Exists​

Without Morph, feature ownership drifts into compiler core files:

  • parser shortcuts appear in src/
  • runtime symbols get hardcoded in shared runtime folders
  • build and tooling logic become platform-specific branches

Morph prevents that by making packages the canonical ownership boundary.

The Plugin-First Rule​

Feature work happens in package space first.

If an existing package can express the feature, extend that package. If no package should own the feature, create a new package. If the current framework cannot express the feature, widen the framework or SDK.

Do not edit Core as a shortcut for feature ownership.

What Counts As A Morph Feature?​

Morph packages can own:

  • syntax and semantic rules
  • lowering behavior
  • runtime families
  • backend routes
  • tooling commands
  • execution formats
  • build providers

Examples from the current repo:

PackageOwns
Corebaseline package-owned language features
Typestype registration and type descriptors
Opsoperator and operation ownership
Testtest {} blocks and assertions
Vconexecution format and VM behavior
Buildgeneric build orchestration
WindowsWindows platform provider behavior

The Current Canonical Model​

The current Morph model is based on:

  • morph.toml as the canonical package manifest
  • feature-first package layout
  • package-owned runtime, backend, tooling, execution, and build behavior

Legacy terminology and legacy manifest layouts are not the teaching target here. Learn and use the current model.

What This Category Teaches​

This category is for plugin authors.

You will learn:

  • how Morph packages are structured
  • how to write a plugin from zero without pushing ownership into Core
  • how manifests drive discovery
  • how package dependencies and imports work
  • how framework SDK headers and generated glue fit into authoring
  • how package scripting and implementation files should be organized
  • how providers, artifacts, runtime families, and LLVM route signatures are declared
  • how to add a feature to an existing package
  • how to create a new package
  • how runtime, backend, tooling, build, and execution ownership stay package-owned

Next Steps​