Open-source project
terralang/terra avatar
terralang/terra

Terra: a C-like systems language that Lua writes, specializes and JIT-compiles

Terra is a low-level system programming language that is embedded in and meta-programmed by the Lua programming language.

2,929 stars212 forksC++NOASSERTION

At a glance

What is it?
Terra is a statically typed, manually managed low-level language that shares Lua's syntax and is meta-programmed by Lua code. Binary releases make it easy to try, but building it yourself ties you to a specific LLVM and Clang toolchain.
Who is it for?
Terra suits developers who already work in Lua or C and want to generate specialized native code at runtime, build embedded languages, or replace preprocessor tricks with real Lua meta-programs. It is a poor fit for anyone who wants garbage collection or a toolchain-free build.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 88 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • terralang/terra2,929 ★ · +17
Star history
Repository2026-09-242026-11-15
terralang/terra2.9k2.9k

17 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Lua is the compile-time language for Terra code

Terra is monomorphic, statically typed, compiled and uses manual memory management, like C. It is also backwards compatible with existing C code and can be embedded in it. The difference from C is where the meta-level lives. Terra code shares Lua's syntax and control flow, and Lua acts as its meta-programming layer. Conditional compilation, namespaces and templating, which C handles with a preprocessor and other special constructs, are ordinary Lua code here.

The same coupling gives function specialization, lisp-style macros and manually controlled JIT compilation. Because the compiler is available at runtime, a library or embedded language can generate low-level code on the fly instead of shipping every variant precompiled. Lua functions are callable from Terra and Terra functions from Lua, so the boundary between the scripting side and the native side is a function call rather than a separate build step.

The cost is that you need to think in two languages at once. Knowing Lua is very helpful though not strictly required, and anyone who has never written Lua will meet its conventions in the REPL first.

The REPL wants statements, not bare expressions

Terra's REPL follows Lua's rules, which trips up anyone coming from Python. Typing a bare value is a syntax error; you prefix it with return or the = shorthand:

code
> 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

Starting ./terra with no arguments opens this prompt; passing a file runs it, so ./terra tests/hello.t prints hello, world. The tests/ directory doubles as a collection of example scripts, which is the closest thing to a sample library in the repository. For a first look with nothing installed, the project keeps a Replit at https://replit.com/@terralang/terra, which runs Terra in the browser.

Embedding in C goes through libterra_s.a and a Lua state

Terra can also be linked into a C program, with an interface close to the Lua interpreter's. You create a plain lua_State with luaL_newstate, open its libraries with luaL_openlibs, call terra_init on it, then run files with terra_dofile, which returns nonzero on error. On Linux and macOS the static library is libterra_s.a; on Windows it is terra.dll. The Linux link line needs extra flags that macOS does not:

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

The macOS version drops -ldl and -pthread. Beyond the REPL and the embedded library, Terra code can be compiled to .o files that link into an executable, or compiled to an executable directly, so a project does not have to carry the Lua runtime into production if it only needs the generated native code.

Building from source means owning an LLVM and Clang install

Prebuilt releases cover Linux (x86_64, AArch64, PPC64le), macOS (x86_64, AArch64), FreeBSD (x86_64) and Windows (x86_64), and the project advises using them because getting LLVM and Clang working is the hard part of a source build. A source build also needs a C++17 compiler, CMake 3.26.4 or greater, GNU Make on Linux, macOS and FreeBSD for LuaJIT, and Visual Studio 2022 on Windows, where other versions are untested. LuaJIT itself is downloaded and installed automatically by default. On Ubuntu the listed packages are:

code
sudo apt-get install build-essential cmake git llvm-21-dev libclang-21-dev clang-21 libpolly-21-dev libncurses-dev libzstd-dev zlib1g-dev

On macOS with Homebrew and on FreeBSD the lists are shorter:

code
brew install cmake llvm@21
code
pkg install -y cmake gmake llvm21

All three pull LLVM 21 while LLVM 22 is the recommended version, so a reader following the commands literally does not land on the recommended toolchain.

Older LLVM versions are on a deprecation path

The LLVM support table marks versions 11 and 12 as deprecated, with a linked issue. If your distribution only ships an old LLVM, a build may work today and stop being supported later, so plan to move to a newer LLVM rather than pinning to an old one.

GPU support splits by vendor. CUDA is an optional build dependency for NVIDIA. AMD and Intel GPUs are supported, but Terra does not link their GPU toolkits directly, so those toolkits are not build requirements. The support table tracks NVIDIA/CUDA, AMD/HIP and Intel/SPIRV columns per LLVM version, which means GPU targets depend on which LLVM you built against, not only on the hardware you own.

macOS needs SDKROOT before C headers will include

Since macOS 10.15 Catalina, including C headers from Terra requires an environment variable. Without it, the C interop that makes Terra attractive fails on a Mac:

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

Put it in your shell profile or build script rather than typing it per session. After any install, the test suite confirms the build. It prints a lot of output and ends with a summary such as 471 tests passed. 0 tests failed:

code
cd tests
../terra run

Release gaps, packaging files and an undetected license

Release 1.2.0 shipped on 2024-06-25, then nothing until 1.2.1 on 2026-08-01 and 1.2.2 on 2026-08-14. The last push was 2026-08-19 and the repository is not archived. The two-year gap means binary releases can lag the source, so check the release date against the LLVM version you need before downloading.

The repository root carries several packaging paths besides CMakeLists.txt: default.nix and a nix/ directory, a docker/ directory, an msvc/ directory, and terra-scm-1.rockspec for LuaRocks. CI runs through GitHub Actions and AppVeyor. GitHub reports the license as NOASSERTION, so read LICENSE.txt before shipping Terra in a product. STABILITY.md and CHANGES.md sit at the root as well, and are the files to read before upgrading.

Editorial conclusion

Terra suits developers who already work in Lua or C and want to generate specialized native code at runtime, build embedded languages, or replace preprocessor tricks with real Lua meta-programs. It is a poor fit for anyone who wants garbage collection or a toolchain-free build. Before adopting it, use a binary release, confirm your platform and LLVM version are supported rather than deprecated, and check LICENSE.txt yourself, since GitHub does not detect a standard license for the repository.

Frequently asked questions

What platforms does Terra run on?

Terra runs on Linux (x86_64, AArch64, PPC64le), macOS (x86_64, AArch64), FreeBSD (x86_64) and Windows (x86_64). Binary releases are on the GitHub releases page.

Does Terra need LLVM to build?

Yes. Building Terra from source requires LLVM and Clang, with LLVM 22 recommended, plus CMake 3.26.4 or greater and a C++17 compiler. LuaJIT is downloaded automatically by default.

Can Terra be embedded in a C program?

Yes. You link against libterra_s.a (terra.dll on Windows), call terra_init on a lua_State, and run Terra files with terra_dofile.

Official sources

  1. Issues
  2. README
  3. Releases
  4. terralang/terra on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/terralang-terra.svg)](https://hysenlabs.com/projects/terralang-terra)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/terralang-terra.svg)](https://hysenlabs.com/projects/terralang-terra)

Was this useful?