Building HLVM from Source

Complete guide to building HLVM binaries.

Prerequisites

Required

macOS Native Builds

HLVM uses deno compile to build the native hlvm binary. On macOS, that goes through Apple's native toolchain, so make build, make repl, make test, and the platform build targets may require Command Line Tools and an accepted Xcode/Apple SDK license first.

Optional

  • Make (for build commands)

Quick Start REPL

Build the native binary and launch the REPL:

make repl

This compiles ./hlvm first, then launches its REPL.

Quick Build

Build for your current platform:

make build

This creates ./hlvm binary.

Verify:

./hlvm --version

This binary is now the SSOT build artifact for both:

  • standalone CLI/runtime use
  • the macOS GUI wrapper at ~/dev/HLVM, which copies this exact binary into HLVM/Resources/hlvm

Build Commands

Build for Current Platform

make build

Output: ./hlvm

Build and Test

make test

Builds binary and runs smoke tests.

Start REPL

make repl

Builds the native hlvm binary and launches its REPL.

Start Ink REPL

make ink

Builds the native hlvm binary and launches the Ink REPL.

Install System-Wide

make install

Installs to /usr/local/bin/hlvm.

Then use anywhere:

hlvm --version

Cross-Platform Builds

Build for macOS

Intel:

make build-mac-intel

Output: hlvm-mac-intel

Apple Silicon:

make build-mac-arm

Output: hlvm-mac-arm

Build for Linux

make build-linux

Output: hlvm-linux

Build for Windows

make build-windows

Output: hlvm-windows.exe

Output: hlvm-windows.exe

Build All Platforms

make all

Creates all binaries:

  • hlvm-mac-intel
  • hlvm-mac-arm
  • hlvm-linux
  • hlvm-windows.exe

Manual Build (Without Make)

If you don't have make:

Step 1: Build Stdlib

deno run -A scripts/build-stdlib.ts

Step 2: Embed Packages

./scripts/embed-packages.ts

Step 3: Compile Binary

deno compile --allow-all --no-check --config deno.json \
  --include src/hql/lib/stdlib/js/index.js \
  --output hlvm src/hlvm/cli/cli.ts

No AI engine embedding. Ollama is downloaded at bootstrap time, not at build time. The binary is ~120 MB, not ~587 MB.

Step 4: Test

./hlvm --version
./hlvm run -e '(print "Hello!")'

Build Options

Debug Build

Include source maps:

deno compile --allow-all --config deno.json \
  --include src/hql/lib/stdlib/js/index.js \
  --output hlvm src/hlvm/cli/cli.ts

Note: Larger binary, better error messages.

Optimized Build

Fastest compilation (production):

deno compile --allow-all --no-check --config deno.json \
  --include src/hql/lib/stdlib/js/index.js \
  --output hlvm src/hlvm/cli/cli.ts

Note: Default, skips type checking.

Build Targets

Available targets:

  • x86_64-apple-darwin - macOS Intel
  • aarch64-apple-darwin - macOS Apple Silicon
  • x86_64-unknown-linux-gnu - Linux x64
  • x86_64-pc-windows-msvc - Windows x64

Specify with --target:

deno compile --allow-all --target x86_64-apple-darwin --output hlvm src/hlvm/cli/cli.ts

Binary Size

Typical sizes:

  • All platforms: ~120 MB

The binary includes the Deno runtime, all dependencies, and the HQL stdlib. Ollama is NOT embedded — it is downloaded at bootstrap time. This keeps all platform binaries small and uniform.

GUI Binary Sync

~/dev/hql is the only SSOT build source for hlvm.

If you are also working with the macOS GUI wrapper in ~/dev/HLVM:

  • Xcode no longer compiles its own alternate hlvm
  • the GUI build phase calls scripts/sync-gui-binary.sh
  • that script builds ~/dev/hql/hlvm if needed, then copies it into HLVM/Resources/hlvm

Optional developer convenience hook:

git config core.hooksPath .githooks

That enables the tracked .githooks/post-commit wrapper, which syncs the bundled binary into a sibling ../HLVM checkout after commits.

The hook is convenience only. The Xcode build phase remains the correctness path, because it always copies the SSOT binary before the app is built.

Troubleshooting

Permission Denied

Make scripts executable:

chmod +x scripts/embed-packages.ts

Deno Not Found

Install Deno:

curl -fsSL https://deno.land/install.sh | sh

Add to PATH:

export PATH="$HOME/.deno/bin:$PATH"

Build Fails

Clean and retry:

make clean
make build

Missing Dependencies

Update Deno:

deno upgrade

Development Builds

Watch Mode

Rebuild on changes:

deno run --allow-all --watch src/hlvm/cli/cli.ts repl

Test Changes

Without building binary:

deno run --allow-all src/hlvm/cli/cli.ts run test.hql

CI/CD Builds

GitHub Actions

See .github/workflows/release.yml for automated builds.

Build Matrix

Builds for:

  • macOS (Intel + ARM)
  • Linux (x64)
  • Windows (x64)

Clean Up

Remove build artifacts:

make clean

Removes:

  • hlvm
  • hlvm-* (all platform binaries)
  • Temporary files

Next Steps