{"id":37819303,"url":"https://github.com/splanck/viper","last_synced_at":"2026-01-16T15:40:41.731Z","repository":{"id":312199911,"uuid":"1046659507","full_name":"splanck/viper","owner":"splanck","description":"IL-first cross platform compiler toolchain, runtime, and virtual machine.","archived":false,"fork":false,"pushed_at":"2026-01-13T05:05:27.000Z","size":23112,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-13T08:33:59.400Z","etag":null,"topics":["arm64","basic-programming","compiler","interpreter","runtime","viperlang","virtual-machine"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/splanck.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-29T02:58:41.000Z","updated_at":"2026-01-13T05:05:30.000Z","dependencies_parsed_at":"2025-08-29T07:31:42.310Z","dependency_job_id":"83526306-a3c7-4346-8e26-f6adbdb0fe5e","html_url":"https://github.com/splanck/viper","commit_stats":null,"previous_names":["splanck/viper"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/splanck/viper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splanck%2Fviper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splanck%2Fviper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splanck%2Fviper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splanck%2Fviper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/splanck","download_url":"https://codeload.github.com/splanck/viper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splanck%2Fviper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm64","basic-programming","compiler","interpreter","runtime","viperlang","virtual-machine"],"created_at":"2026-01-16T15:40:41.663Z","updated_at":"2026-01-16T15:40:41.723Z","avatar_url":"https://github.com/splanck.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Viper\n\n**Viper** is an IL-first compiler toolchain and virtual machine for exploring intermediate language design, multi-frontend architectures, and interpreter implementation techniques.\n\nHigh-level frontends—like the included BASIC and Zia compilers—lower programs into a strongly typed, SSA-inspired intermediate language (**Viper IL**). The IL can be executed by the VM or compiled to native code.\n\n\u003e **Status:** Early development. APIs, IL, and tooling change frequently. Not production-ready.\n\n---\n\n## Download\n\n**Latest Release:** [v0.2.0-dev](https://github.com/splanck/viper/releases/tag/v0.2.0-dev) (1/15/2026)\n\n- [Source (tar.gz)](https://github.com/splanck/viper/archive/refs/tags/v0.2.0-dev.tar.gz)\n- [Source (zip)](https://github.com/splanck/viper/archive/refs/tags/v0.2.0-dev.zip)\n- [Release Notes](docs/release_notes/Viper_Release_Notes_0_2_0.md)\n\nOr clone the repository:\n\n```bash\ngit clone https://github.com/splanck/viper.git\ncd viper\n```\n\n---\n\n## Quickstart\n\nBuild and test:\n\n```bash\ncmake -S . -B build\ncmake --build build -j\nctest --test-dir build --output-on-failure\n```\n\nRun a BASIC program:\n\n```bash\n./build/src/tools/vbasic/vbasic examples/basic/ex1_hello_cond.bas\n```\n\nRun a Zia program:\n\n```bash\n./build/src/tools/zia/zia demos/zia/frogger/main.zia\n```\n\nRun an IL program directly:\n\n```bash\n./build/src/tools/ilrun/ilrun examples/il/ex1_hello_cond.il\n```\n\n---\n\n## What is Viper?\n\nViper is a compiler infrastructure with several components:\n\n| Component | Description |\n|-----------|-------------|\n| **IL** | Typed, SSA-based intermediate representation |\n| **Frontends** | Language compilers: BASIC and Zia |\n| **VM** | Bytecode interpreter with pluggable dispatch strategies |\n| **Backends** | Native code generators (AArch64, x86-64) |\n| **Runtime** | Portable C libraries for core types, collections, I/O, text, math, graphics, audio, GUI, input, networking, system, diagnostics, utilities, crypto, time, threading |\n| **Tools** | Compiler drivers, verifier, disassembler |\n\n### Why Viper?\n\n- **IL-centric**: A readable, typed IR makes semantics explicit and frontends interchangeable\n- **Human-scale**: The IL is designed to be read and edited—learn by inspecting output\n- **Composable**: Parser, IL builder, verifier, and VM work as standalone scriptable tools\n- **Educational**: Clear examples, golden tests, and a manageable codebase for experimentation\n\n---\n\n## Project Status\n\nViper is in **early development**. All components are functional but incomplete:\n\n| Component | Notes |\n|-----------|-------|\n| BASIC Frontend | Core language implemented; OOP features work but are evolving |\n| Zia Frontend | Core language with entities, generics, imports; actively developed |\n| Viper IL | Stable core; instruction set still expanding |\n| Virtual Machine | Functional with multiple dispatch strategies |\n| AArch64 Backend | Validated on Apple Silicon; actively developed |\n| x86-64 Backend | Validated on Windows; System V and Windows x64 ABI support |\n| Runtime Libraries | Comprehensive: core types, collections, I/O, text, math, graphics, audio, GUI, input, networking, system, diagnostics, utilities, crypto, time, threads |\n| IL Optimizer | Basic passes implemented; more planned |\n| Debugger/IDE | Early work; not yet usable |\n\nExpect breaking changes. The IL specification, APIs, and tool interfaces are not stable.\n\n---\n\n## Demos\n\nSeveral demos showcase the platform's capabilities. See the **[demos/](demos/README.md)** directory for the full list.\n\n### BASIC Demos\n\n| Demo | Description |\n|------|-------------|\n| `demos/basic/frogger` | Frogger clone (console). Also runs natively on Apple Silicon. |\n| `demos/basic/chess` | Console chess with AI opponent |\n| `demos/basic/pacman` | Pac-Man clone with ghost AI |\n| `demos/basic/centipede` | Classic arcade game with OOP |\n| `demos/basic/monopoly` | Board game with 4-player AI |\n| `demos/basic/vtris` | Tetris clone with high scores |\n| `demos/basic/particles` | Graphics particle system using Canvas API |\n\n### Zia Demos\n\n| Demo | Description |\n|------|-------------|\n| `demos/zia/frogger` | Frogger with entity types and generics |\n| `demos/zia/centipede` | Centipede arcade game clone |\n| `demos/zia/ladders` | Platform/ladder climbing game |\n| `demos/zia/paint` | Paint application with drawing tools |\n| `demos/zia/graphics_show` | Graphics API showcase |\n\nRun demos:\n\n```bash\n# BASIC\n./build/src/tools/vbasic/vbasic demos/basic/frogger/frogger.bas\n\n# Zia\n./build/src/tools/zia/zia demos/zia/frogger/main.zia\n```\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────┐\n│           Source Language               │\n│         (BASIC, Zia)              │\n└─────────────────┬───────────────────────┘\n                  │\n                  ▼\n┌─────────────────────────────────────────┐\n│     Frontend (Parser + Semantics +      │\n│              Lowering)                  │\n└─────────────────┬───────────────────────┘\n                  │\n                  ▼\n┌─────────────────────────────────────────┐\n│         Viper IL (Typed SSA)            │\n│        + Verifier + Optimizer           │\n└─────────┬───────────────┬───────────────┘\n          │               │\n          ▼               ▼\n┌──────────────┐   ┌──────────────────────┐\n│   Virtual    │   │   Native Backend     │\n│   Machine    │   │  (AArch64, x86-64)   │\n└──────────────┘   └──────────────────────┘\n        │                   │\n        └─────────┬─────────┘\n                  ▼\n┌─────────────────────────────────────────┐\n│           Viper Runtime                 │\n│ (Collections, I/O, Text, Math, Graphics,│\n│  Audio, GUI, Input, Network, Threads)   │\n└─────────────────────────────────────────┘\n```\n\n---\n\n## IL at a Glance\n\nFrontends lower to a typed IL that is compact, explicit, and inspectable.\n\n**BASIC Source:**\n\n```basic\n10 LET X = 2 + 3\n20 LET Y = X * 2\n30 PRINT \"HELLO\"\n40 PRINT Y\n50 END\n```\n\n**Viper IL Output:**\n\n```il\nil 0.2\nextern @Viper.Console.PrintStr(str) -\u003e void\nextern @Viper.Console.PrintI64(i64) -\u003e void\nglobal const str @.NL = \"\\n\"\nglobal const str @.HELLO = \"HELLO\"\n\nfunc @main() -\u003e i64 {\nentry:\n  %x = add 2, 3\n  %y = mul %x, 2\n  call @Viper.Console.PrintStr(const_str @.HELLO)\n  call @Viper.Console.PrintStr(const_str @.NL)\n  call @Viper.Console.PrintI64(%y)\n  call @Viper.Console.PrintStr(const_str @.NL)\n  ret 0\n}\n```\n\n---\n\n## Runtime Library\n\nAll frontends share the **Viper Runtime**, providing a growing set of modules:\n\n| Module | Classes | Description |\n|--------|---------|-------------|\n| **Collections** | `Bag`, `Bytes`, `Heap`, `List`, `Map`, `Queue`, `Ring`, `Seq`, `Stack`, `TreeMap` | Data structures for any use case |\n| **Core** | `Box`, `Object`, `String` | Base types and string operations |\n| **Crypto** | `Hash`, `KeyDerive`, `Rand` | CRC32, MD5, SHA1, SHA256, PBKDF2, secure RNG |\n| **Diagnostics** | `Assert`, `Trap` | Debugging and assertions |\n| **Graphics** | `Camera`, `Canvas`, `Color`, `Pixels`, `Sprite`, `Tilemap` | 2D graphics, sprites, tilemaps, cameras |\n| **GUI** | `App`, `Button`, `Checkbox`, `Label`, `Slider`, `TextInput`, etc. | Cross-platform GUI widgets and layouts |\n| **I/O** | `Archive`, `BinFile`, `Compress`, `Dir`, `File`, `LineReader`, `LineWriter`, `MemStream`, `Path`, `Watcher` | File system access and streaming |\n| **Input** | `Keyboard`, `Mouse`, `Pad` | Input devices for games and interactive apps |\n| **Math** | `Bits`, `Math`, `Random`, `Vec2`, `Vec3` | Mathematical functions and vectors |\n| **Network** | `Dns`, `Http`, `HttpReq`, `HttpRes`, `Tcp`, `TcpServer`, `Udp`, `Url` | Networking and sockets |\n| **Sound** | `Audio`, `Music`, `Sound`, `Voice` | Audio playback and sound effects |\n| **System** | `Environment`, `Exec`, `Machine`, `Terminal` | System interaction and console I/O |\n| **Text** | `Codec`, `Csv`, `Guid`, `Pattern`, `StringBuilder`, `Template` | String building and text encoding |\n| **Threads** | `Barrier`, `Gate`, `Monitor`, `RwLock`, `SafeI64`, `Thread` | Concurrent programming primitives |\n| **Time** | `Clock`, `Countdown`, `DateTime`, `Stopwatch` | Time utilities and measurement |\n| **Utilities** | `Convert`, `Fmt`, `Log`, `Parse` | Conversion, formatting, parsing, logging |\n\nSee the **[Runtime Library Reference](docs/viperlib/README.md)** for complete API documentation.\n\n---\n\n## Tools\n\n**Primary tools:**\n\n| Tool | Purpose |\n|------|---------|\n| `vbasic` | Run or compile BASIC programs |\n| `zia` | Run or compile Zia programs |\n| `ilrun` | Execute IL programs |\n| `il-verify` | Validate IL with detailed diagnostics |\n| `il-dis` | Disassemble IL for inspection |\n\n**Examples:**\n\n```bash\n# Run BASIC\n./build/src/tools/vbasic/vbasic program.bas\n\n# Run Zia\n./build/src/tools/zia/zia program.zia\n\n# Emit IL from any frontend\n./build/src/tools/vbasic/vbasic program.bas --emit-il\n./build/src/tools/zia/zia program.zia --emit-il\n\n# Run IL\n./build/src/tools/ilrun/ilrun program.il\n\n# Verify IL\n./build/src/tools/il-verify/il-verify program.il\n```\n\n**Advanced tool:**\n\n`ilc` is a unified compiler driver for advanced workflows:\n\n```bash\n# Compile BASIC to native executable (experimental)\n./build/src/tools/ilc/ilc front basic -emit-il program.bas \u003e program.il\n./build/src/tools/ilc/ilc codegen arm64 program.il -o program\n\n# Compile Zia to native executable\n./build/src/tools/ilc/ilc front zia -emit-il program.zia \u003e program.il\n./build/src/tools/ilc/ilc codegen arm64 program.il -o program\n```\n\n---\n\n## VM Dispatch Strategies\n\nThe VM supports three dispatch strategies:\n\n| Strategy | Description | Portability |\n|----------|-------------|-------------|\n| `switch` | Switch-based dispatch | All compilers |\n| `table` | Function-pointer dispatch | All compilers |\n| `threaded` | Direct-threaded (labels-as-values) | GCC/Clang only |\n\nSet at runtime:\n\n```bash\nVIPER_DISPATCH=threaded ./build/src/tools/ilrun/ilrun program.il\n```\n\nBuild with threaded dispatch enabled by default:\n\n```bash\ncmake -S . -B build -DVIPER_VM_THREADED=ON\n```\n\n---\n\n## Building\n\n### Requirements\n\n- CMake 3.20+\n- C++20 compiler (Clang recommended, GCC 11+, or MSVC)\n\n### Build Steps\n\n```bash\ncmake -S . -B build\ncmake --build build -j\nctest --test-dir build --output-on-failure\n```\n\n### Install (Optional)\n\n```bash\nsudo cmake --install build --prefix /usr/local\n```\n\nInstalls: `vbasic`, `vpascal`, `zia`, `ilrun`, `ilc`, `il-verify`, `il-dis`\n\n### Platform Notes\n\n- **macOS**: Use Apple Clang. ARM64 tests skip x86-64-specific checks automatically.\n- **Linux**: Clang recommended. Force with `CC=clang CXX=clang++ cmake -S . -B build`\n- **Windows**: Clang-CL preferred. Some POSIX tests are skipped.\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Getting Started](docs/getting-started.md) | Build and run your first program |\n| [BASIC Tutorial](docs/basic-language.md) | Learn Viper BASIC by example |\n| [BASIC Reference](docs/basic-reference.md) | Complete BASIC language specification |\n| [Zia Getting Started](docs/zia-getting-started.md) | Learn Zia by example |\n| [Zia Reference](docs/zia-reference.md) | Complete Zia language specification |\n| [Runtime Library](docs/viperlib/README.md) | Viper.* classes, methods, and properties |\n| [IL Guide](docs/il-guide.md) | IL specification and examples |\n| [IL Quickstart](docs/il-quickstart.md) | Fast introduction to Viper IL |\n| [VM Architecture](docs/vm.md) | VM design and internals |\n| [Frontend How-To](docs/frontend-howto.md) | Build your own language frontend |\n\nDeveloper documentation is in `docs/devdocs/`.\n\n---\n\n## Contributing\n\nViper is in early development and the architecture is stabilizing. We welcome:\n\n- Bug reports and issues\n- Small fixes and documentation improvements\n- Feedback and suggestions\n\nWe are not currently seeking large feature PRs while the design solidifies. Feel free to fork for broader experimentation.\n\n---\n\n## Related Project: ViperDOS\n\nThis repository also contains [ViperDOS](viperdos/README.md), a capability-based\nmicrokernel operating system for AArch64. ViperDOS is a separate project and\ndoes not depend on the Viper compiler.\n\nSee [viperdos/README.md](viperdos/README.md) for documentation.\n\n---\n\n## License\n\nViper is licensed under the **GNU General Public License v3.0** (GPL-3.0-only).\n\nSee [LICENSE](LICENSE) for the full text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsplanck%2Fviper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsplanck%2Fviper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsplanck%2Fviper/lists"}