Installation
You need only Node.js and clang; there are no npm packages to install.
Supported platforms
Section titled “Supported platforms”| Platform | Native | GPU (Metal) | wasm32 |
|---|---|---|---|
| macOS (Apple Silicon) | yes | yes | yes, with Homebrew’s LLVM |
| Linux (x86_64 / arm64) | yes | — | yes (needs lld) |
| Windows | not tested; use Linux under WSL2 | — | — |
1. Node.js (22.18 or later)
Section titled “1. Node.js (22.18 or later)”The compiler is TypeScript that Node.js runs directly (type stripping, enabled by default since 22.18).
# macOSbrew install node
# Linux (example with nvm; distribution packages are often too old)curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bashnvm install 22node --version # v22.18.0 or later2. clang (LLVM 18 or later)
Section titled “2. clang (LLVM 18 or later)”# macOS: the clang from Xcode or the Command Line Tools (also provides the Metal framework)xcode-select --install
# Linux (Debian / Ubuntu): lld provides wasm-ld for wasm32 linkingsudo apt install clang lldclang --version # 18 or laterFor GPU execution on a Mac you need Apple Silicon with Xcode or the Command Line Tools (Metal).
3. Get the compiler
Section titled “3. Get the compiler”git clone https://github.com/UnifiedMozaic/UnifiedMozaic.gitcd UnifiedMozaic4. The um command (optional)
Section titled “4. The um command (optional)”Run npm link inside the repository to put um on your PATH. It is a link, so there is nothing to reinstall after git pull.
npm linkum --help- If you get
um: command not found, check that thebindirectory undernpm prefix -gis on yourPATH. - To remove it:
npm unlink -g unifiedmozaic. - Without
npm link, replaceumwithnode src/cli.ts. - Installing from the npm registry (
npm install -g) is not supported yet.
5. Tests
Section titled “5. Tests”node tests/run.ts # same as npm testThis takes a few minutes. It runs every example on wasm32 and native and compares the output, checks programs that must fail to compile (tests/errors/) or must stop at run time (tests/panics/), and runs thread tests under ThreadSanitizer and memory tests under AddressSanitizer or valgrind when available.
Anything your machine lacks is skipped with a note:
- no wasm32-capable clang (for example Xcode’s clang on a Mac) → wasm32 tests are skipped
- none of AddressSanitizer, valgrind or
leaks(Mac) → memory-checked runs are skipped; on Linux,sudo apt install valgrindadds them - no Metal →
tests/metal/is only compiled for arm64
Troubleshooting
Section titled “Troubleshooting”| Symptom | Fix |
|---|---|
ERR_UNKNOWN_FILE_EXTENSION ".ts", or a SyntaxError at a type annotation |
Node.js is too old; use 22.18 or later |
clang が見つかりません / the LLVM toolchain (clang) failed |
Install clang, or set UM_CLANG to its path |
この clang は wasm32 を出力できない (this clang cannot target wasm32) |
macOS: set UM_CLANG to Homebrew’s LLVM as above. Linux: install lld |
gpu.dispatch is a compile error |
The GPU path exists only for native Mac builds with UM_METAL=1; otherwise use dispatch or cpu.dispatch |
panic: the GPU is not available at run time |
gpu.dispatch stops when there is no GPU; dispatch (automatic) falls back to the CPU |