The Terra Programming Language

Home Page: https://terralang.org

Community: https://terralang.zulipchat.com

Replit: https://replit.com/@terralang/terra

Build Status:

Terra is a new low-level system programming language that is designed to interoperate seamlessly with the Lua programming language. It is also backwards compatible with (and embeddable in) existing C code. Like C, Terra is a monomorphic, statically-typed, compiled language with manual memory management. But unlike C, it is designed to make interaction with Lua easy. Terra code shares Lua's syntax and control-flow constructs. It is easy to call Lua functions from Terra (or Terra functions from Lua).

Furthermore, you can use Lua to meta-program Terra code. The Lua meta-program handles details like conditional compilation, namespaces, and templating in Terra code that are normally special constructs in low-level languages. This coupling additionally enables more powerful features like function specialization, lisp-style macros, and manually controlled JIT compilation. Since Terra's compiler is also available at runtime, it makes it easy for libraries or embedded languages to generate low-level code dynamically.

This guide serves as an introduction for programming in Terra. A general understanding of the Lua language is very helpful, but not strictly required.

Run Terra in Your Browser via Replit

The fastest way to try Terra is via Replit. You can run Terra in your browser without needing to install anything. Once you get a feel for the language, you can use the instructions below to install Terra on your computer.

Installing Terra

Terra currently runs on Linux (x86_64, AArch64, PPC64le), macOS (x86_64, AArch64), FreeBSD (x86_64), and Windows (x86_64). Binary releases for popular versions of these systems are available online, and we recommend you use them if possible because building Terra requires a working install of LLVM and Clang, which can be difficult to get working.

Note that as of macOS 10.15 Catalina, in order to include C headers in Terra you will need to define the following environment variable:

export SDKROOT="$(xcrun --sdk macosx --show-sdk-path)"

Running Terra

Similar to the design of Lua, Terra can be used as a standalone executable/read-eval-print-loop (REPL) and also as a library embedded in a C program. This design makes it easy to integrate with existing projects.

To run the REPL:

$ ./terra

Terra -- A low-level counterpart to Lua

Homepage: https://terralang.org/
Project: https://github.com/terralang/terra
Community: https://terralang.zulipchat.com/

>

Terra's REPL behaves similar to Lua's REPL. If you are familiar with other languages like Python, the one major difference is that expressions must be prefixed with return or = if you want to get their value:

> 3        --ERROR! it is expecting a statement
stdin:1: unexpected symbol near 3
> return 3 -- OK!
3
> = 3      -- syntax sugar in the REPL for 'return 3'
3

You can also run it on already written files:

$ ./terra tests/hello.t
hello, world

Terra can also be used as a library from C by linking against libterra_s.a (windows: terra.dll). The interface is very similar that of the Lua interpreter. A simple example initializes Terra and then runs code from the file specified in each argument:

//simple.cpp
#include <stdio.h>
#include "terra.h"

int main(int argc, char ** argv) {
    lua_State * L = luaL_newstate(); //create a plain lua state
    luaL_openlibs(L);                //initialize its libraries
    //initialize the terra state in lua
    terra_init(L);
    for(int i = 1; i < argc; i++)
        //run the terra code in each file
        if(terra_dofile(L,argv[i]))
            return 1; //error
    return 0;
}

This program can then be compiled by linking against the Terra library

# Linux
c++ simple.cpp -o simple -I<path-to-terra-folder>/terra/include \
-L<path-to-terra-folder>/lib -lterra_s -ldl -pthread

# OSX
c++ simple.cpp -o simple -I<path-to-terra-folder>/terra/include \
-L<path-to-terra-folder>/lib -lterra_s

In addition to these modes, Terra code can be compiled to .o files which can be linked into an executable, or even compiled to an executable directly.

A bunch of example scripts can be found in the tests/ directory. The run script in the directory will run all of these languages tests to ensure that Terra is built correctly.

Running Terra's Test Suite

Terra includes test suite to make sure all of its functionality is working. To run it:

cd tests
../terra run

Expect it to print a lot of junk out. At the end it will summarize the results:

471 tests passed. 0 tests failed.

Building Terra

If the binary releases are not appropriate, then you can also build Terra from source. Terra has the following dependencies:

A working C/C++ compiler (GCC, Clang, MSVC, etc.) that supports at least C++ 17
Windows only: Visual Studio 2022 (other versions may work but are untested)
CMake (version 3.5 or greater)
Linux, macOS, FreeBSD only: GNU Make (required for building LuaJIT)
LLVM and Clang (see suppport table below)
LuaJIT (note this is downloaded and installed automatically by default)
Optional: CUDA
Note: In addition to CUDA, Terra also supports AMD and Intel GPUs. However, Terra does not link their GPU toolkits directly so this is not a build requirement.

On recent versions of Ubuntu, you can get these dependencies with:

sudo apt-get install build-essential cmake git llvm-18-dev libclang-18-dev clang-18 libmlir-18-dev libedit-dev libncurses5-dev zlib1g-dev libpfm4-dev

On macOS with Homebrew, the following should be sufficient:

brew install cmake llvm@18

On FreeBSD, use:

pkg install -y cmake gmake llvm18

Supported LLVM Versions

The current recommended version of LLVM is 20 for most platforms, except Linux (ARM) where LLVM 11 is required. The following versions are also supported:

| Version | Linux | macOS | FreeBSD | Windows | NVIDIA/CUDA | AMD/HIP * | Intel/SPIRV ** | Notes | | ------- | ------------- | ------------- | ------------- | ------------- | ------------- | -------------- | ---------------- | ----- | | 11 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | | | | | 12 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | | | | | 13 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :yellow_heart: | | | | 14 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :yellow_heart: | | | | 15 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :yellow_heart: | :yellow_heart: | | | 16 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :yellow_heart: | :yellow_heart: | | | 17 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :yellow_heart: | :green_heart: | | | 18 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | | | 19 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | | | 20 | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | :green_heart: | | | 21 | :green_heart: | :green_heart: | :green_heart: | | :green_heart: | :green_heart: | :green_heart: | |

* AMD GPU support is currently experimental. LLVM 20 is strongly recommended.

** Intel GPU (SPIR-V) support is currently experimental.

The following versions were previously supported by Terra:

| Version | Last Supported Release | | ------- | ----- | | 3.5 | 1.0.0-beta3 | | 3.6 | 1.0.0-beta3 | | 3.7 | 1.0.0-beta3 | | 3.8 | 1.0.6 | | 3.9 | 1.0.6 | | 5 | 1.0.6 | | 6 | 1.1.1 | | 7 | 1.1.1 | | 8 | 1.1.1 | | 9 | 1.1.1 | | 10 | 1.1.1 |

Instructions for Building LLVM from Source

If you need to build LLVM from source, the following recipe has been known to work with Terra. The same basic procedure should work for all LLVM versions >= 11.

wget https://github.com/llvm/llvm-project/releases/download/llvmorg-13.0.0/llvm-13.0.0.src.tar.xz
wget https://github.com/llvm/llvm-project/releases/download/llvmorg-13.0.0/clang-13.0.0.src.tar.xz
tar xf llvm-13.0.0.src.tar.xz
tar xf clang-13.0.0.src.tar.xz
mv clang-13.0.0.src llvm-13.0.0.src/tools/clang
mkdir build install
cd build
cmake ../llvm-13.0.0.src -DCMAKE_INSTALL_PREFIX=$PWD/../install -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_TERMINFO=OFF -DLLVM_ENABLE_LIBEDIT=OFF -DLLVM_ENABLE_ZLIB=OFF -DLLVM_ENABLE_LIBXML2=OFF -DLLVM_ENABLE_ASSERTIONS=OFF
make install -j4 # tune this for how many cores you have

There are also pre-built binaries available that follow this basic recipe, and should be usable with Terra.

Building Terra with CMake (Linux, macOS, FreeBSD)

The basic procedure for building with CMake is the following:

git clone https://github.com/terralang/terra.git
cd terra/build
cmake -DCMAKE_INSTALL_PREFIX=$PWD/.

Terra

Install / Use

README