Skip to main content

Getting Started with Morph Development

Prerequisites​

ToolMinimum VersionPurpose
Windows10 / 11Primary CI and reference dev platform
MSYS2 + MinGW-w64CurrentGCC, Ninja, LLVM, CMake (Windows)
LLVM15+ (typical via MSYS2)Code generation backend
CMake3.20+Meta-build
Ninja1.11+Build executor
Python3.11+morphc driver (scripts/morphc_build)
Git2.30+Version control

Install MSYS2 toolchain (Windows)​

# In MSYS2 MINGW64 shell:
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-ninja \
          mingw-w64-x86_64-llvm mingw-w64-x86_64-libffi \
          mingw-w64-x86_64-cmake

Clone and build (this repository)​

Use morphc as the unified entry point — it auto-detects MSYS2/LLVM/Ninja and keeps workspace state under %LOCALAPPDATA%\Morph\workspaces\morph\ (see Playbook and scripts/README.md).

git clone https://github.com/jeandarcc/morph.git Neuron
cd Neuron

# Optional overrides (normally not needed):
# $env:MORPH_TOOLCHAIN_BIN = "C:\msys64\mingw64\bin"
morphc.bat build
# or: python -m scripts.morphc_build build

Full build + test suite:

morphc.bat build --test

Targeted tests:

morphc.bat test "flow"
morphc.bat test --list

Environment diagnosis:

morphc.bat doctor

Compiler artifacts land under %LOCALAPPDATA%\Morph\workspaces\morph\build-mingw\bin\ (e.g. morph.exe, morph_unit_tests.exe).

Do not use raw cmake -S/-B or ad-hoc Ninja for routine work. Legacy scripts\build.bat / build_tests.ps1 exist for older automation but morphc is the supported path.

VS Code​

  1. Open the repo folder in VS Code.
  2. Install recommended extensions when prompted (clangd, cmake-tools, editorconfig).
  3. Use tasks if defined, or build from the terminal with morphc.bat build.
  4. compile_commands.json is emitted under the workspace build directory for clangd.

Repository layout​

src/          Compiler (lexer, parser, sema, NIR, MIR, codegen, CLI, LSP, vcon)
runtime/      Native runtime (platform, tensors, graphics, etc.)
include/      Public headers (morphc ABI)
tests/        C++ unit tests (single binary target)
morphs/       Morph packages (features, manifests, package-owned suites)
scripts/      morphc_build Python package + legacy scripts
config/       Branding, diagnostics, tooling config
extensions/   vscode-morph, intellij-morph
docs/         Guides, ADRs, Learn Morph, specs
benchmarks/   Performance assets

First change checklist​

  1. Locate the relevant area in src/ or morphs/ (see architecture overview).
  2. Implement the change; match existing style and tests.
  3. Add or update tests under tests/ and/or morphs/*/tests/ as appropriate.
  4. morphc.bat build (or morphc.bat build --test).
  5. Open a PR using .github/PULL_REQUEST_TEMPLATE.md.

Further reading​