Skip to content

splanck/viper

BranchesTags

Repository files navigation

Viper

Viper

License: GPL v3 Platform

Viper is a from-scratch, IL-first compiler toolchain and virtual machine for building platform-native applications and games. Source languages lower to a typed intermediate language, Viper IL, which can run on the VM, feed the optimizer, or compile to native code through the built-in backends.

Zia is the flagship language: a modern, statically typed language with classes, generics, enums, lambdas, modules, pattern matching, and direct access to the Viper runtime. A BASIC frontend is included for education, compatibility experiments, and quick prototypes.

Status: Pre-alpha, active development. The current source tree is 0.2.99.20260702; the IL reference is 0.3.0. APIs, diagnostics, IL rules, and tooling are still evolving.

Download

Latest tagged release: v0.2.7-dev (2026-06-30)

In development: 0.2.99.20260702 on master. See the draft v0.2.99 release notes.

git clone https://github.com/splanck/viper.git
cd viper

Quickstart

Build, test, and install the toolchain with the platform scripts:

# macOS
./scripts/build_viper_mac.sh

# Linux
./scripts/build_viper_linux.sh

# Windows
.\scripts\build_viper_win.cmd

Verify the build:

viper --version

Create and run a project:

viper init my-app              # Zia project (default)
viper init my-app --lang basic # BASIC project
viper run my-app

Try the REPL:

viper repl
zia> 2 + 3 * 4
14
zia> Say("Hello from Viper")
Hello from Viper

See the Getting Started Guide for platform-specific setup, build directory layout, and troubleshooting.

Components

Component Description
Zia Statically typed application language with classes, generics, modules, lambdas, enums, and pattern matching
BASIC Educational and prototyping frontend that lowers to the same IL
Viper IL Typed, block-structured SSA-style IR with a normative 0.3.0 reference
Optimizer Registered O1/O2 pipelines covering SSA promotion, SCCP, GVN, LICM, loop cleanup, inlining, devirtualization, runtime fast paths, and cleanup passes
VM IL execution engine for fast bring-up, tests, debugging, and step-budgeted runs
Native backends AArch64 and x86-64 code generators with backend optimization, register allocation, assembly emission, and executable output
Assembler / Linker In-tree ELF, Mach-O, and PE object/link support with DWARF and platform packaging integration
Runtime Shared standard library for collections, graphics, 3D, GUI, games, networking, crypto, text, threads, localization, and more
Language servers Zia and BASIC servers with LSP and MCP modes for editors and AI coding tools
Tools Unified viper driver plus zia, vbasic, ilrun, il-verify, il-dis, REPL, package, installer, and benchmark commands

Why Viper?

  • IL thin waist: Zia, BASIC, and future frontends share one typed IR, verifier, optimizer, VM, and native backend path.
  • Self-contained native toolchain: Viper includes its own runtime, assembler, linker, object writers, package generation, and install packaging paths.
  • Machine-readable tooling: viper check, viper eval, viper explain, --dump-runtime-api, and --dump-opcodes expose JSON-friendly surfaces for editors, scripts, and AI agents.
  • Cross-platform by design: macOS, Linux, and Windows are first-class targets; platform checks are centralized in adapter layers.
  • Runtime-first apps and games: The standard library includes 2D/3D graphics, GUI widgets, game systems, audio, networking, localization, threading, and structured data APIs.

Examples

The examples tree includes applications, games, 3D scenes, API audits, language samples, IL programs, and C++ embedding demos.

Demo Description
ViperSQL PostgreSQL-compatible SQL database server and client
Paint Drawing app with tools, layers, file dialogs, zoom, and undo/redo
WebServer Multi-threaded HTTP server demo
Chess GUI chess with alpha-beta AI and drag-and-drop play
Crackman Maze chase game with pathfinding and mode-driven AI
XENOSCAPE Metroidvania-style sidescroller with abilities, enemies, levels, and saves
3D Bowling Physics-driven 3D bowling with camera modes
Ridgebound Open-world Game3D sample with terrain, water, skybox, PBR materials, beacon objectives, and post-FX 
viper run examples/games/chess/
viper build examples/apps/paint/ -o paint
./scripts/build_demos.sh

Architecture

+-------------------------+
|    Source Languages     |
|      Zia / BASIC        |
+-----------+-------------+
            |
            v
+-------------------------+
|  Parser / Sema / Lower  |
+-----------+-------------+
            |
            v
+-------------------------+
|       Viper IL          |
|  Verifier / Optimizer   |
+------+------------+-----+
       |            |
       v            v
+-------------+  +-----------------+
|     VM      |  | Native Backends |
|  Interpreter|  | AArch64/x86-64  |
+------+------+  +-------+---------+
       |                 |
       +--------+--------+
                v
+-------------------------+
|      Viper Runtime      |
| Collections / Graphics  |
| GUI / Game / Network    |
| Text / Threads / ...    |
+-------------------------+

See the Architecture Overview and Code Map for subsystem details.

IL at a Glance

Frontends lower to typed Viper IL that is compact, explicit, and inspectable.

Zia source:

module Hello;

bind Viper.Terminal;
bind Fmt = Viper.Text.Fmt;

func start() {
    var x = 2 + 3;
    var y = x * 2;
    Say("HELLO");
    Say(Fmt.Int(y));
}

Representative IL:

il 0.3.0
extern @Viper.Text.Fmt.Int(i64) -> str
extern @Viper.Terminal.Say(str) -> void
global const str @.L0 = "HELLO"
func @main() -> void {
entry_0:
  %t0 = iadd.ovf 2, 3
  %t1 = imul.ovf %t0, 2
  %t2 = const_str @.L0
  call @Viper.Terminal.Say(%t2)
  %t3 = call @Viper.Text.Fmt.Int(%t1)
  call @Viper.Terminal.Say(%t3)
  ret
}

Use --dump-il, --dump-il-opt, and viper il-opt to inspect the pipeline. The IL Quickstart is the practical introduction; IL Guide is the normative reference.

Runtime Library

All frontends share the Viper Runtime Library. The runtime surface is generated from the live registry and spans:

  • Collections, core types, functional helpers, math, text, structured data, I/O, time, and utilities
  • 2D graphics, 3D graphics, Game3D, GUI widgets, input, audio, and game systems
  • Networking, crypto, diagnostics, memory controls, threading, system APIs, and localization

Authoritative runtime inventory:

viper --dump-runtime-api

Authoritative IL opcode inventory:

viper --dump-opcodes

Tools

Command Purpose
`viper run <file dir>`
`viper build <file dir> -o `
`viper check <file dir> --diagnostic-format=json`
viper eval 'expr' --json --type --il Evaluate a Zia or BASIC snippet through the REPL pipeline
viper explain <CODE> --json Explain a diagnostic code from the central catalog
viper repl [zia & basic] Interactive REPL
viper -run <file.il> Execute an IL module directly, with optional tracing and step limits
viper package <dir> Package an application for macOS, Linux, Windows, or tarball output
viper install-package Package the Viper binary tools and ViperIDE into a platform installer
zia / vbasic Standalone source compiler entry points
zia-server / vbasic-server Language servers with LSP and MCP modes
ilrun, il-verify, il-dis Direct IL execution, verification, and disassembly
viper il-opt Run and inspect optimizer pipelines
viper bench IL benchmark runner

Common examples:

viper run program.zia
viper -run program.il --max-steps 100000
viper build project/ -o app
viper check project/ --diagnostic-format=json
viper eval '2 + 3 * 4' --json --type
viper explain V-ZIA-UNDEFINED --json
viper --dump-runtime-api
viper --dump-opcodes

See the Tools Reference, Debugging Guide, and MCP tool reference for full details.

Building

Requirements

  • CMake 3.20+
  • C++20 compiler: Apple Clang, Clang, GCC 11+, or MSVC

Build Scripts

# macOS
./scripts/build_viper_mac.sh

# Linux
./scripts/build_viper_linux.sh

# Windows
.\scripts\build_viper_win.cmd

The scripts configure, build, test, and install Viper. The Unix wrappers delegate to scripts/build_viper_unix.sh.

Useful iteration knobs:

Variable Effect
VIPER_SKIP_CLEAN=1 Incremental rebuild
VIPER_SKIP_TESTS=1 Build only
VIPER_TEST_LABEL=<label> Run one CTest label
VIPER_CMAKE_GENERATOR=Ninja Select Ninja

Targeted checks after a build:

ctest --test-dir build -L codegen --output-on-failure
ctest --test-dir build -R test_zia_lexer --output-on-failure
./scripts/example_smoke.sh --fast

Platform guides:

Documentation

Getting Started: Setup Guide, REPL Guide, Zia Tutorial, Viper Bible

Language References: Zia, BASIC, IL Guide, IL Quickstart

Runtime & APIs: Runtime Library, 3D Graphics, Game Engine, GUI

Internals: Architecture, VM, Code Map, Backend, IL Passes

Contributors: Contributor Guide, Frontend How-To, Testing, Dependencies

Contributing

Viper is in active development and the architecture is still stabilizing. Small fixes, documentation improvements, bug reports, and focused tests are welcome.

Before proposing changes:

  • Read the relevant spec or reference first; IL Guide is normative for IL.
  • Keep the product dependency-free.
  • Preserve macOS, Windows, and Linux behavior.
  • Use the platform build scripts and keep tests green.
  • Follow Conventional Commits for commit messages.

See Contributor Guide and Testing for the full workflow.

License

Viper is licensed under the GNU General Public License v3.0 (GPL-3.0-only).

See LICENSE for the full text.

About

Viper is a self-contained development platform for building native games and applications on Linux, macOS, and Windows. It brings back the coherence and immediacy of classic developer tools, while providing a modern language, compiler, runtime, IDE, 2D/3D engine, GUI toolkit, networking and packaging.

Topics

debugger interpreter compiler game-engine runtime virtual-machine linker x86-64 ide assembler codegen arm64 3d-engine intermediate-language basic-programming zia

Resources

Readme

License

View license
Activity

Stars

4 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

12 tags

Contributors

Languages