CONTRIBUTING

Build Tekst.
Understand every layer.

Tekst is a language, compiler, runtime, documentation set, and developer toolchain. This guide gives contributors a practical path from first checkout to a focused, testable change.

01 · AREAS

Choose the layer you want to improve.

A good contribution does not have to start inside the compiler. Documentation, examples, diagnostics, tests, tooling, and runtime work all improve the language.

Compiler

Lexing, parsing, AST handling, lowering, LLVM IR, code generation, diagnostics, and command-line behaviour.

Runtime

Built-ins, memory operations, collections, objects, native runtime behaviour, and compiler/runtime boundaries.

Documentation

Language explanations, reference pages, examples, tutorials, release notes, and keeping documentation aligned with the compiler.

Tooling

CLI improvements, build workflows, package handling, examples, tests, and developer experience.

02 · SETUP

Get a reproducible development environment.

The current compiler is built around C++17, CMake, and LLVM/Clang. Keep the build directory separate from the source tree and use a release configuration when checking compiler output.

configure and build

cmake -S . -B build
cmake --build build --config Release

inspect the compiler

tekst --version
tekst examples/hello.tk
tekst examples/hello.tk --emit-ir

CMake places the compiler executables in build/release/; Windows builds include tekst.exe and tk.exe.

03 · ARCHITECTURE

Know where a change belongs.

Tekst follows a compact compiler pipeline. A focused change is easier to review when it has one clear responsibility and a small reproduction program.

Lexer

Converts source text into tokens and preserves the lexical structure needed by the parser.

Parser

Consumes tokens and builds the abstract syntax tree for the indentation-based language.

AST

Provides the structured representation consumed by later compiler stages.

LLVM backend

Lowers language operations into LLVM IR and connects the program to native runtime functionality.

compiler pipeline

.tk / .tekst
    ↓
Lexer
    ↓
Parser
    ↓
AST
    ↓
LLVM IR
    ↓
LLVM / Clang
    ↓
native executable

small reproduction

x = 41
p = &x
*p = 42
print(*p)

04 · WORKFLOW

Make changes small, observable, and testable.

Start from a concrete behaviour. Reproduce it, make the smallest useful change, build the compiler, run a focused example, and inspect the resulting diff before opening a contribution.

recommended loop

1. Reproduce the behaviour
2. Identify the responsible layer
3. Make the smallest useful change
4. Build the compiler
5. Run a focused program
6. Inspect LLVM IR when useful
7. Check nearby documentation
8. Review the diff

language example

use mathpkg
print(mathpkg.square(8))

from mathpkg use square
print(square(9))

05 · PRINCIPLES

Keep the language coherent.

Readable first

Prefer clear semantics and small implementations that another contributor can understand without archaeology.

Keep syntax intentional

Tekst has a deliberately small surface. New syntax should solve a concrete problem rather than add complexity for its own sake.

Document behaviour

A feature is easier to trust when its syntax, semantics, examples, and limitations are written down beside the implementation.

Ready to work on Tekst?

Start with the compiler documentation, inspect the release history for the current toolchain, then choose one focused improvement.

Compiler docs →Documentation →Release history →

Build Tekst.Understand every layer.