Skunk, Explained As A Pipeline

How To Read This

The most important idea in this whole booklet is that Skunk is a pipeline. Each stage receives a program in one form and hands a more useful form to the next stage. If you always know which stage you are in, the compiler stops feeling like a pile of unrelated files.

The second important idea is that not every program exercises every pass equally. A tiny non-generic program will mostly glide through monomorphization. A generic one will make that pass much more interesting. That is normal.

The Whole Pipeline

The high-level path through the compiler is short enough to memorize. That is helpful, because it lets you classify almost every file by its role in the bigger machine.

Parsing And AST

Skunk parsing is split into two layers. src/grammar.pest describes which source forms are valid. src/ast.rs turns those grammar matches into the compiler's internal tree of Node values.

This matters because the rest of the compiler does not want to reason about raw strings. It wants to reason about named constructs like StructDeclaration, FunctionDeclaration, StructInitialization, and Access.

source text
  "Point { x: 20, y: 22 }"

grammar match
  recognized as a struct initialization

AST
  Node::StructInitialization {
      _type: Point,
      fields: [("x", 20), ("y", 22)]
  }

Modules And Normalization

src/source.rs is where the compiler stops thinking in terms of "one file the user opened" and starts thinking in terms of "one program the compiler can analyze."

The source loader resolves imports, validates module declarations, detects cycles, and uses the module normalizer to rename private symbols when needed. That makes later global passes much simpler.

Monomorphization

Generics are comfortable for programmers and inconvenient for backends. Skunk's answer is a preparation pass in src/monomorphize.rs that turns generic templates into concrete specialized program pieces when needed.

The pass is easiest to understand if you think in terms of recipes and finished dishes. A generic function is a recipe. A monomorphized concrete function is one finished dish for one concrete set of type arguments.

Type Checking

The type checker is where the compiler shifts from "this parses" to "this is a legal Skunk program."

The public entry point is check. The most important recursive engine under it is resolve_type. It walks expressions, determines the type they produce, and validates whether the operations used are allowed.

One especially valuable helper in this file is resolve_access, because many language rules come together in access chains like self.x, ptr.*, slice[0], or window.draw_rect(...).

LLVM, Layouts, And Runtime

The backend in src/compiler.rs is where language concepts become storage and instructions. Its own internal vocabulary is LlvmType.

This file also contains the layout structures that describe how values live in memory: StructLayout, EnumLayout, TraitLayout, and TraitMethodLayout.

compile_to_llvm_ir emits textual LLVM IR. Then compile_to_executable writes the IR to disk and invokes clang along with the runtime support files.

Worked Example: One Tiny Program Through The Compiler

The best way to make the pipeline feel real is to trace one small program through it. Here is the example used in Part 2 of the notebook:

struct Point {
    x: int;
    y: int;
}

attach Point {
    function sum(self): int {
        return self.x + self.y;
    }
}

function main(): int {
    p: Point = Point { x: 20, y: 22 };
    return p.sum();
}

Step 1: Parse It

The parser recognizes a struct declaration, an attach declaration, and a main function. The method body becomes a nested expression tree rather than a flat string.

Step 2: Load It

Because this example has no imports, load_program has little visible work to do. But it still wraps the result as one coherent program node.

Step 3: Prepare It

Because this example is non-generic, monomorphization mostly passes it through. That is a useful lesson in itself: not every pass dramatically changes every program.

Step 4: Type-Check It

The checker proves that Point exists, the fields are legal, the struct literal initializes valid fields with assignable types, and p.sum() returns an int.

Step 5: Build Layouts

StructLayout("Point")
  field 0 -> x : i32
  field 1 -> y : i32

Step 6: Emit LLVM IR

The backend lowers the struct literal, method body, and return path into LLVM IR. You do not need to master LLVM syntax to understand the shape: build a value, access its fields, add them, and return the result.

Step 7: Link The Binary

Finally the compiler writes a .ll file and asks clang to produce a native executable, linking runtime support as needed.

Extending Skunk

If Parts 1 and 2 teach you how to read the compiler, Part 3 teaches you how to change it. The key idea is to stop thinking of a feature as one edit and start thinking of it as a path through the pipeline.

Recommended Reading Order

Read the compiler in this order if you want the architecture before the details:

1. src/main.rs
2. src/source.rs
3. src/ast.rs
4. src/type_checker.rs
5. src/compiler.rs

Then go deeper with:

1. src/grammar.pest
2. src/monomorphize.rs
3. src/interpreter.rs
4. runtime/skunk_runtime.c
5. runtime/skunk_window_runtime.m