Skip to main content

Project Structure

Every Morph project follows a standard directory layout created by morph new.

Directory Layout​

my_project/
│
├── morph.toml              # Project configuration (build, web, routes, dependencies)
├── .morphsettings          # Source rules and lint configuration
├── .productsettings        # Product / installer metadata for release builds
├── .gitignore              # Git exclusion rules
│
├── assets/                 # Static assets (empty scaffold; use for your project)
│
├── src/                    # Source code
│   └── Main.mx             # Program entry point (`Init` method for applications)
│
├── modules/                # External package dependencies (vendored / locked)
│
├── build/                  # Build output (auto-generated; gitignored)
│
├── docs/                   # Project documentation
│   └── scripts/            # Per-script documentation
│       └── Main.md         # Docs for Main.mx (required when script docs are enforced)
│
├── tests/                  # Tests
│   ├── auto/               # Automated integration tests
│   └── unit/               # Unit tests
│
└── agents/                 # Agent / learning reference (regenerated on `morph new`)
    ├── language/           # Language guides and rule details
    ├── project/            # Project-specific docs
    └── learnmorph/         # End-user tutorials copied from the toolchain when present

Key Files​

morph.toml​

The primary project manifest. The generator emits a working baseline similar to:

[project]
name = "my_project"
version = "0.1.0"

[package]
kind = "application"
description = "Morph application project"
repository = "https://github.com/your-org/my_project"
license = "MIT"
source_dir = "src"

[build]
main = "src/Main.mx"
build_dir = "build"
optimize = "aggressive"
emit_ir = "optimized"
target_cpu = "native"
tensor_profile = "balanced"
tensor_autotune = true
tensor_kernel_cache = "build/.morph_cache/tensor/"

[web]
canvas_id = "morph-canvas"
wgsl_cache = true
dev_server_port = 8080
enable_shared_array = true
initial_memory_mb = 64
maximum_memory_mb = 512
wasm_simd = true

[morph]
host_route = "host.llvm"
nn_route = "nn.graph"

[dependencies]

Optional sections such as [vcon] are not part of the default scaffold; add them when you configure VCON packaging or sandbox settings.

.morphsettings​

Controls source rules enforced by the compiler. The generator enables a strict baseline (script docs, naming, visibility, etc.). See .morphsettings Reference for every key.

src/Main.mx​

The program entry point for an application package. It must define an Init method. Example (generator style):

Init is method()
{
    Print("Hello Morph!");
};

For morph new --lib, the scaffold uses a library-style entry (e.g. a public method returning a string) instead of Init.

docs/scripts/Main.md​

Documentation for Main.mx. Required when require_script_docs = true in .morphsettings.

Source Organization​

Each .mx file contains exactly one class. The class name must match the filename:

src/
├── Main.mx          → Main class; `Init` is the app entry point
├── Vector2.mx       → Vector2 class
├── Player.mx        → Player class
└── AI/
    ├── Brain.mx     → Brain class
    └── Morph.mx     → Morph class

Subdirectories are allowed for organizing larger projects.

Build Output​

After morph build or morph run, artifacts typically land under build/ (exact names depend on target and settings), for example:

build/
├── Main.exe          # Native executable (Windows)
├── Main.obj          # Object file
├── Main.ll           # LLVM IR when emit_ir is enabled
└── .morph_cache/     # Tensor / codegen caches (under build/)

.gitignore Defaults​

The scaffold’s .gitignore includes:

build/
Build/
modules/
agents/

The agents/ tree is populated from toolchain templates (and learn/tutorial copies) when the project is created.

Compiler repo vs your project (contributors)​

End-user project layout is what this page describes (morph new, src/*.mx, one root morph.toml for the CLI loader).

If you are working inside the Morph compiler repository, language behavior lives under morphs/<Package>/: each package has its own morph.toml, nested feature.toml / block.toml, and C++ under features/, blocks/, runtime/, plugin/. That graph is the Morph Framework—not the same file as your app’s root manifest. Start from morphs/README.md and Plugin-governed pipeline.

Next Steps​