Skunk

Skunk is a human-designed, AI-implemented experimental programming language targeting LLVM. It is a language-design project and compiler playground, not a production-ready platform.

Do not use Skunk to build critical, safety-sensitive, security-sensitive, or high-reliability software.

Status

• Native compilation through LLVM/Clang is the primary execution path.
• Native compilation is the only execution path, keeping runtime behavior aligned with generated binaries.
• The language reference lives in Skunk
• Syntax and implemented behavior are defined by src/syntax/grammar.pest and the test suite.

Install

Skunk needs clang at runtime to link native executables (macOS: xcode-select --install, Linux: install clang via your package manager).

Install the latest release (macOS and Linux):

curl -fsSL https://dmgcodevil.github.io/skunk/install.sh | sh

This downloads the prebuilt binary for your platform from GitHub Releases, verifies its checksum, and installs it to ~/.skunk/bin. Pin a version with SKUNK_VERSION=v0.1.0. Installs are versioned side by side: skunk --version shows the running version, skunk versions lists installed ones, and skunk use <version> switches. See RELEASE.md for building and installing a release locally.

Alternatively, download a tarball from the releases page manually, or build from source with Rust:

cargo install --git https://github.com/dmgcodevil/skunk

The release process is documented in RELEASE.md.

Build

Skunk currently requires Rust and clang.

cargo build

Compiler Architecture

The compiler is available as a Rust library (src/lib.rs) with a thin CLI in src/main.rs. The production compilation path is:

Pest parse tree
  -> syntax AST (direct parser actions, source-oriented nodes and spans)
  -> module loading and source normalization
  -> generic expansion and source-level validation
  -> lexical resolution (DefId, LocalId, FieldId, VariantId)
  -> semantic type interning (TypeId)
  -> typed HIR
  -> HIR invariant validation and specialization seal
  -> LLVM layouts, signatures, vtables, and function lowering
  -> native LLVM/Clang build

AST and HIR are separate representations: syntax nodes never contain semantic types, while HIR never contains unresolved identifiers or Pest values. Compiler clients can start with pipeline::check_source; the returned CheckedProgram owns HIR, semantic tables, specialization metadata, and its source map.

Generic expansion uses a private, phase-specific tree before semantic analysis. The LLVM backend accepts only CheckedProgram and derives its internal lowering state from typed HIR; neither representation is part of the public compiler API.

Use

Compile a program to a native executable:

cargo run -- compile path/to/main.skunk ./out
./out

A new macOS-first window/input runtime is also available for simple 2D programs. The repository includes a playable Pong example:

cargo run -- compile examples/pong.skunk ./pong
./pong

Compile and run a program natively using a temporary executable:

cargo run -- path/to/main.skunk
# Equivalent explicit form:
cargo run -- run path/to/main.skunk

To inspect the compiler pipeline, add the global --debug flag to run, compile, test, or build:

cargo run -- --debug compile path/to/main.skunk ./out

Debug logging is written to stderr and prints a labeled, pretty-formatted dump after every output-producing phase: loaded and normalized syntax ASTs, name resolution, generic specialization, the semantic model, typed HIR, MIR, and the final LLVM IR. Normal program output remains on stdout. The flag may also appear after the command, for example skunk run main.skunk --debug.

Projects and Tests

Scaffold a project with a skunk.toml manifest, build it, and run its native tests:

skunk new demo
cd demo
skunk build        # compiles src/main.skunk into target/demo
skunk test         # runs `test "name" { ... }` blocks natively
skunk test --filter shorthand

skunk.toml configures linking for extern "C" interop (libraries = ["sqlite3"], frameworks = ["Cocoa"]). The standard library ships embedded in the compiler; import std.math; resolves to the SDK (the std. prefix is reserved) and provides libm bindings plus integer helpers.

See the language reference for the C interop, standard library, and native test sections, and examples/c_interop.skunk, examples/math_test.skunk, and examples/calculator/ for runnable samples.

VS Code

A lightweight VS Code extension now lives in editors/vscode/skunk. It includes:

• syntax highlighting for .skunk
• basic autocompletion for keywords, snippets, and top-level symbols
• a simple formatter for indentation and brace layout

Quick local install on macOS or Linux:

sh editors/vscode/skunk/build-vsix.sh

Then install editors/vscode/skunk/dist/dmgcodevil.skunk-0.0.3.vsix from VS Code via Extensions > ... > Install from VSIX.... More details are in editors/vscode/skunk/README.md.

In This Repository

• docs/index.html: Skunk Language Reference
• docs/compiler-booklet.html: print-friendly compiler booklet with diagrams and a worked example
• docs/compiler-notebook.md: compiler notebook, Part 1
• docs/compiler-notebook-part2.md: compiler notebook, Part 2
• docs/compiler-notebook-part3.md: compiler notebook, Part 3, focused on extending the language/compiler
• docs/pointers-and-allocators.md: pointer and allocator design note
• docs/language-development.md: development contract
• examples/: runnable sample programs
• editors/vscode/skunk: VS Code syntax highlighting, completion, and formatter extension

License

Skunk is open-source and distributed under the MIT License. See LICENSE for details.