Authoritative source: Installing tulam and editor support

Installing tulam and editor support

tulam is currently built from source. Development builds need Haskell and the pinned LLVM toolchain once, when assembling the compiler distribution. The resulting release carries its own ORC worker, Clang, LLD, compiler runtime, and native runtime artifact. End users do not install LLVM, Xcode, Command Line Tools, or a C++ toolchain separately.

This chapter uses the repository checkout directly. That keeps the commands reproducible while the compiler is under active development.

What you need

Install these tools before building tulam from source:

Stack resolves and installs the matching GHC compiler and Haskell dependencies. You do not need an existing Haskell development environment beyond Stack.

Check that the commands are visible:

git --version
stack --version
/path/to/llvm/bin/llvm-config --version
/path/to/lld/bin/ld.lld --version   # Linux
/path/to/lld/bin/ld64.lld --version # macOS

The exact installation command depends on your operating system. The LLVM version must match toolchain/llvm-version.txt; an arbitrary host clang++ is not used as a fallback.

Platform status: LLVM native is the current reference backend. Building the tulam compiler and using tulam’s planned .NET target are different things; installing a .NET SDK does not currently add a .NET backend. The same applies to Node.js and the planned JavaScript provider.

Get the source

Clone the repository and enter it:

git clone https://github.com/aantich/tulam.git
cd tulam

If you already have a checkout, use that directory instead. Commands in this guide assume that the current directory is the repository root unless a chapter explicitly creates a separate example project.

Build the compiler

Run:

stack build

The first build can take longer because Stack may download the selected GHC toolchain and package snapshot. Later builds are incremental.

Build the development native bundle with the pinned LLVM installation:

TULAM_LLVM_ROOT=/path/to/llvm \
TULAM_LLD_ROOT=/path/to/lld \
./tools/build-jit-worker.sh

This creates the ignored .tulam-toolchain/ development bundle. The compiler validates its LLVM version, JIT protocol, operating system, architecture, runtime artifact, linker, and link settings before execution.

Ask the built compiler for its command summary:

stack exec tulam -- --help

You should see commands including check, run, build, test, lock, and project operations. The two -- tokens serve different purposes: the first belongs to stack exec, and the second is the --help argument passed to tulam.

For a stronger repository-level verification, run the Haskell unit suite:

stack test

This tests the compiler itself. It is not required before every tulam program, but it is useful after a fresh checkout or toolchain change.

Running the compiler from another directory

During development, the simplest command is always:

stack exec tulam -- COMMAND

from the repository root. To work in another project directory without installing the executable globally, tell Stack which project to use:

stack --stack-yaml /path/to/tulam/stack.yaml exec tulam -- check

Replace /path/to/tulam with the absolute path of your checkout. The compiler will discover the nearest tulam.project.tl from your current directory.

stack install can place only the Haskell executable in Stack’s local binary directory. Native execution also needs the standard library and toolchain, so use release staging for a standalone installation tree:

TULAM_LLVM_ROOT=/path/to/llvm \
TULAM_LLD_ROOT=/path/to/lld \
TULAM_RELEASE_OUTPUT=/path/to/tulam-release \
./tools/stage-release.sh

/path/to/tulam-release/bin/tulam --help

Staging computes and relocates the private dynamic-library closure, writes a relative schema-3 manifest, and runs clean-environment ORC and AOT smoke tests. The guide continues to spell development commands as stack exec tulam -- ....

Syntax highlighting

The canonical TextMate grammar lives at:

editors/vscode-tulam/syntaxes/tulam.tmLanguage.json

The repository also contains a lightweight Visual Studio Code extension in:

editors/vscode-tulam

It contributes the .tl and .tulam file types, bracket and comment behavior, and syntax highlighting. Because the extension currently contains only editor metadata and grammar files, it does not require a JavaScript build step.

For development directly from the checkout, copy or link that directory into your Visual Studio Code extensions directory under a name such as:

tulam-lang.tulam-0.2.0

The usual user extension directories are:

Platform Directory
Linux and macOS ~/.vscode/extensions/
Windows %USERPROFILE%\.vscode\extensions\

Restart Visual Studio Code after adding it. Opening a .tl file should then select the tulam language mode. A symlink is convenient for compiler contributors because grammar updates in the checkout become visible after an editor restart.

Editors that accept TextMate grammars can use the JSON grammar directly. The tulam website also offers the synchronized grammar as a download. Installation details vary by editor; the source grammar above is authoritative.

Syntax highlighting is deliberately not a parser. A highlighted program can still be invalid, and a newly supported construct may compile before an old editor session reloads its grammar. tulam check is the authority.

Optional: confirm native compilation

Create a temporary file named install-check.tl in the repository root:

function main() : Int = 0;

Then compile and run it:

stack exec tulam -- check install-check.tl
stack exec tulam -- run install-check.tl

The first command exercises parsing, module loading, elaboration, and strict checking. The second additionally lowers the checked program through RuntimeCore and LLVM, invokes the validated compiler-shipped Clang/LLD pair, and runs the produced executable. An output line containing 0 is the expected result; the current native entry wrapper prints supported scalar return values.

You may delete install-check.tl afterward. Chapter 3 replaces it with a program that prints a visible greeting.

Troubleshooting the first build

stack is not found

Stack is either not installed or its executable directory is not on PATH. Open a new terminal after installation and repeat stack --version.

Stack cannot download a compiler or packages

The initial build requires network access to the configured package snapshot. Check proxy, certificate, and firewall settings, then rerun stack build.

The compiler-shipped toolchain is not found

For a source checkout, run tools/build-jit-worker.sh with TULAM_LLVM_ROOT and TULAM_LLD_ROOT as shown above. For an installed release, keep bin/tulam and lib/tulam/toolchain/ in the same installation prefix. Tulam deliberately does not fall back to a clang++ found on PATH.

Native linking reports unsupported LTO options

Rebuild the development bundle with exactly the LLVM and LLD version named in toolchain/llvm-version.txt. Release staging tests LTO before accepting a bundle.

The compiler cannot find its standard library or native runtime

When using stack exec, run it against the tulam repository’s stack.yaml as shown above. A release keeps lib/Base.tl and lib/tulam/toolchain/ below the same installation root as bin/tulam.

The shell starts when you expected a build

Running stack exec tulam with no tulam command opens the compiled shell. Declarations persist and expressions execute through an isolated LLVM ORC worker. Use :help for shell commands and :worker for worker status.

Recap

At this point you should be able to:

Next: Your first program.