Skip to main content

Build Pipeline

Morph separates how you compile from how you ship. Day-to-day project commands compile through the LLVM pipeline; VCON and Web are additional targets with their own entrypoints.

Under the hood, most “language behavior” (syntax forms, semantic features, NIR lowering, backend routes, runtime bundles, tooling commands) is package-owned under morphs/<Package>/ and registered through package manifests (morph.toml, feature.toml, block.toml) plus the stable ABI. If you are extending compiler behavior, read Plugin-governed pipeline.

Native LLVM path (morph build, morph run, morph release)​

This is the default path for a normal project directory with morph.toml. Both morph build and morph run drive the same LLVM-oriented compile stack end-to-end. morph build finishes by placing a dev binary under build/dev/. morph run compiles, then executes the resulting native executable.

Source (.mx)
   │
   ├── Lexer → Tokens
   ├── Parser → AST
   ├── Semantic analysis → typed IR surface
   ├── NIR → Morph IR
   ├── LLVM codegen → LLVM IR
   ├── LLVM optimizer (per `build.optimize` / project settings)
   └── Native linker → executable (.exe / host suffix)

Commands:

  • morph build — dev build (tests + compile with dev output layout).
  • morph run — compile to native executable, then run it (no VCON VM implied).
  • morph release — stricter path: tests, compile, stage under build/release/<name-version>/, copy artifacts and package metadata.

Web target (morph build --target=web, morph run --target=web)​

Web builds reuse the same frontend and lowering stack where applicable, then emit artifacts under build/web (see CLI help / UsageText.h). morph run --target=web serves that tree with the embedded dev server (COOP/COEP headers). Configure WASM/memory knobs in [web] in morph.toml (see morph_toml).

VCON container path (morph vcon …)​

Portable bytecode + VM packaging is handled under the morph vcon nested command, not by plain morph run. Expect something like:

Source (.mx)
   │
   ├── Frontend (lexer → … → NIR)  [same stages through NIR]
   ├── Bytecode lowering / container tooling
   └── .vcon container → Nucleus / VM execution

Use morph vcon subcommands for build, run in the sandbox, inspect, watch/hot-reload, etc. Hot reload and sandbox policies come from [vcon] (and related tables) in morph.toml, not from morph run.

Comparison (at a glance)​

ConcernNative build / runWeb --target=webVCON morph vcon
Typical commandmorph build, morph runmorph build --target=webmorph vcon …
Primary outputNative executablebuild/web bundle.vcon container
Hot reloadNo (rebuild/restart)Dev server reloadSupported via VCON workflow
SandboxOS processBrowser / WASMVCON policies

Debug / inspection commands​

These are for debugging the compiler, not for shipping binaries:

morph lex <file>         # Tokens
morph parse <file>       # Parse / AST-oriented debug output
morph nir <file>         # NIR dump
morph lex-dump <file>    # Canonical lexer dump (tests)
morph parse-dump <file>  # Canonical parser dump (tests)
morph nir-dump <file>   # Canonical NIR dump (tests)
morph mir-dump <file>   # Canonical MIR dump (tests)
morph compile <file>    # Full compile pipeline to a native executable

To retain LLVM IR on disk for a project, use build.emit_ir / build_dir in morph.toml (none | optimized | both per ProjectConfig). morph compile is “build the exe”, not “print LLVM IR only”.

Next Steps​