Sigil

A modern programming language.

---

Warning

Sigil is a work in progress and is not yet stable. It is under active development, and breaking changes are expected.

Language Documentation

The user-facing reference is organized by feature complexity in docs/lang/. Runnable examples live in docs/examples/; future, partial, reserved, and rejected features live in docs/proposals/, indexed in the proposal index.

Requirements

To build and run Sigil, you need the following dependencies installed on your system:

• Python 3.13+: Can be installed using pyenv or asdf.
• uv: A fast Python package installer from Astral.
• LLVM: The compiler infrastructure.
• C compiler: cc on Linux/BSD, clang on macOS, or cl.exe on Windows.

Architecture

The Sigil compiler is built with a modular architecture, following a classic multi-stage compilation pipeline. The entire frontend is written in Python.

+------------------------------------------+
|      Frontend (Python)                   |
+------------------------------------------+
|                                          |
|      Source Code (.sl)                   |
|           |                              |
|           v                              |
|         Lexer --(Tokens)-->              |
|           |                              |
|           v                              |
|         Parser --(AST)-->                |
|           |                              |
|           v                              |
|   Semantic Analyzer --(Validated AST)--> |
|           |                              |
|           v                              |
|     Code Generator                       |
|           | (LLVM IR)                    |
|           v                              |
+------------------------------------------+
              |
              v
+------------------------------------------+
|    Backend (LLVM Toolchain)              |
+------------------------------------------+
|                                          |
|       LLVM IR (.ll)                      |
|           |                              |
|     +-----+------+                       |
|     |            |                       |
|     v            v                       |
| opt (Optional)   llc                     |
|     |            ^                       |
| (Optimized IR)   |                       |
|     |            |                       |
|     +------>-----+                       |
|                  | (Object File .o)      |
|                  v                       |
|                 gcc                      |
|                  | (Executable)          |
|                  v                       |
|             Executable                   |
|                                          |
+------------------------------------------+

1. Lexical Analysis (Lexer): The source code is first processed by the lexer, which scans the text and converts it into a stream of tokens. This stage handles indentation, comments, and the basic elements of the language like keywords, identifiers, and operators.

2. Syntactic Analysis (Parser): The parser takes the stream of tokens and constructs an Abstract Syntax Tree (AST). This tree represents the hierarchical structure of the code and validates it against the language's grammar.

3. Semantic Analysis (Analyzer): The semantic analyzer traverses the AST to check for semantic correctness. It builds a symbol table to track variables, functions, and types, ensuring that the code is logically sound (e.g., type checking, scope resolution).

4. Code Generation (CodeGenerator): After analysis, the code generator walks the AST and translates it into LLVM Intermediate Representation (IR).

5. Backend Compilation: The generated LLVM IR is then passed to the LLVM toolchain:

   • opt: An optional step to optimize the LLVM IR.
   • llc: Compiles the IR into a native object file (.o).
   • C compiler: Links the object file to produce a final executable.

How to Run

Use the bin/sigilc wrapper, or uv run python -m src.main directly. Examples live in docs/examples/; build artifacts land in build/. Paths in the CLI are resolved relative to the repo root, so the same command works from any subdir.

Compile:

bin/sigilc docs/examples/01-basics/02-variables.sl

Compile and run:

bin/sigilc docs/examples/01-basics/02-variables.sl --run

Compile with optimizations:

To enable LLVM optimizations at the -O3 level, use the --optimize flag. This flag is experimental and currently only effective once code generation produces real LLVM IR; other optimization levels are not available. --optm is kept as a temporary alias.

bin/sigilc docs/examples/01-basics/02-variables.sl --optimize --run

Stop after semantic analysis (no codegen, no build artifacts):

bin/sigilc <file.sl> --check

JSON diagnostics on stdout (used by the VS Code extension on every keystroke):

bin/sigilc <file.sl> --check --format=json