v++ Documentation Master Content

Complete source content for the official Docs hub

Current release: v1.0.4 (compiler + extension) · License: MIT · Stage: v1.0 stable

1. What is v++?

V++ is a compiled programming language designed around readable source code, static typing, local type inference, and native compilation. Its project tagline is Write it simply. Compile it natively. Grow into control when you need it. The compiler has one front end and two execution paths. The interpreter is useful for development and teaching. The native path lowers checked programs into V++ IR, then LLVM, and finally a native executable linked with the V++ runtime. The goal is not to become Python or Rust. V++ is its own language whose identity comes from readable syntax, explicit types where useful, local inference, native compilation, and an integrated toolchain.

2. Core design goals

Readable by default: Simple programs should not require excessive ceremony.

Statically typed: The compiler checks types before native execution while inference reduces unnecessary repetition.

Native compilation: Supported programs can be compiled through LLVM and clang into native executables.

Two execution paths: Interpreter and native execution share the same checked language model and are tested for parity.

Tooling included: V++, the language server, VS Code extension, formatter, tests, package manager, standard library, documentation, and release tooling are all part of the project.

3. Quick start

Windows release users can install the V++ installer, install the V++ Language VS Code extension, and run a program from a terminal.

vpp run examples\hello.vpp
vpp build examples\hello.vpp -o hello.exe
.\hello.exe

Contributors can build from source with:

git clone https://github.com/shauryaR790/V-.git
cd V-
cargo build --release --features codegen,lsp
cargo test --all-targets

Keep installation instructions version aware. Distribution artifacts and supported platforms can change between releases.

4. Language reference

Primitive values

let count = 42
let ratio = 3.14
let ready = true
let name = "Shaurya"

The current specification defines int as a 64 bit signed integer, float as a 64 bit IEEE value, bool as true or false, and string as a UTF 8 heap string in the native runtime.

Arrays and user types

let numbers: array[int] = [1, 2, 3]
struct User {
name: string
age: int
}
enum Status {
Active
Inactive
}

Option and Result are built in sum types for representing optional values and successful or failed operations.

let value: Option[int] = Some(42)
let answer: Result[int, string] = Ok(42)

Variables and mutability

let x = 10
let mut total = 0
total = total + x

Bindings are immutable by default. Reassignment requires let mut.

Functions

fn add(a: int, b: int) -> int {
return a + b
}
fn main() -> int {
return add(20, 22)
}

When present, fn main() -> int is the program entry point for both interpreter and native execution.

5. Control flow

if score > 50 {
print("pass")
} else {
print("try again")
}
while count < 5 {
count = count + 1
}
for i in 0..5 {
print(i)
}
for item in numbers {
print(item)
}

V++ supports if and else, while, half open range loops, array iteration, break, continue, and match.

Pattern matching

match status {
Active => {
print("active")
}
Inactive => {
print("inactive")
}

}

The v0.4 language core added compile time exhaustiveness checking for enums, Option, and Result. An underscore pattern can be used where appropriate.

6. Generics

fn id[T](x: T) -> T {
return x
}
fn main() -> int {
let value = id[int](42)
return value
}

Generics currently use monomorphization. Generic calls require explicit type arguments at call sites in the current specification.

7. Traits and impl

trait Display {
fn to_text(self) -> string
}
impl Display for User {
fn to_text(self) -> string {
return self.name
}
}
print(user.to_text())

Traits provide interfaces with static dispatch. The current specification does not claim trait objects or dynamic dispatch.

8. Modules and packages

import std.io
import std.fs
import "legacy/path.vpp"

Canonical imports use paths such as std.io. Public declarations use pub. Namespaced calls such as math.add(1, 2) are supported. Circular and duplicate imports are errors. Projects use vpp.toml and vpp.lock. The package manager supports path, git, and registry semver dependencies in the current implementation.

vpp new myapp
vpp add helper --path ../helper
vpp add lib --git https://github.com/example/lib --tag v1.0.0
vpp update
vpp remove helper

The current repository contains a registry index for semver resolution. Hosted package publishing is a future roadmap item.

9. Standard library

Current standard library modules are std.io, std.math, std.string, std.collections, std.fs, std.json, and std.process. Native runtime support includes file reading, file writing, file existence checks, JSON parsing and stringifying, and process execution. The language reference and standard library guides should be kept synchronized with the actual builtin registry.

10. Builtins

print(value)
len(value)
assert(condition)
assert_eq(a, b)
read_file(path)
write_file(path, data)
file_exists(path)
json_parse(text)
json_stringify(value)
process_run(command)

11. CLI

The toolchain includes commands for running, building, checking, compiling, formatting, testing, initialization, package management, language server operation, and toolchain health.

vpp run file.vpp
vpp build file.vpp -o output.exe
vpp check file.vpp
vpp compile file.vpp
vpp fmt
vpp test
vpp init
vpp doctor
vpp lsp
vpp new project
vpp add package
vpp remove package
vpp update

The detailed CLI reference should be versioned because flags and subcommands may evolve.

12. Compiler architecture

.vpp source
|
Lexer
|
Parser -> AST
|
Module loader
|
Type checker -> TypedProgram
| |

v v

Interpreter v++ IR

|

LLVM

|

C runtime

|

Native executable

The lexer and recursive descent parser create the AST. The type checker produces the typed program. The interpreter evaluates it directly. The native backend lowers it to V++ IR, emits LLVM, invokes clang, and links the runtime. The project architecture document describes the LLVM backend as feature gated through codegen. The runtime provides the C ABI used by native code generation.

13. Runtime and memory model

Native strings and arrays use runtime managed representations. The runtime exposes a C ABI, and the native backend emits calls to that ABI. The memory model documentation describes the heap headers and ARC behavior. The public Docs site should separate language level behavior from compiler implementation details. Beginners need to know what a value does. Compiler contributors need to know how the value is represented.

14. Diagnostics

V++ uses numbered compiler errors and source spans. The compiler uses miette based diagnostics and the language server can surface diagnostics in the editor. The repository documents E0107 for non exhaustive match checking and E0400 through E0404 for module and import related errors. The long term Docs site should provide a searchable error reference so users can search an error code and immediately see its cause, example, and fix.

15. Testing and interpreter/native parity

A major engineering property of V++ is parity between its interpreter and native backend. Supported programs should produce equivalent behavior, with the repository using parity tests and a stress script.

vpp run stress.vpp
vpp build stress.vpp -o stress.exe
.\stress.exe

Compiler changes should normally add or update tests. Native features should include parity coverage whenever practical.

16. Complete version history

v0.1.0 Initial release

Established the interpreter complete language, partial LLVM backend, CLI, extension, standard library, and CI.

v0.2.0 Native foundation

Introduced V++ IR between the typed AST and LLVM, a shared builtin registry, architecture and memory model documentation, native strings and arrays, scoped locals, native structs, enums, Option, Result, match, break and continue, and differential parity tests. Important native ABI, scope, and floating point comparison issues were fixed.

v0.3.0 Usable language and ecosystem

Added the module system, package manager, registry semver resolution, standard library modules, native filesystem, JSON and process helpers, doctor, improved LSP diagnostics, release automation, and expanded syntax highlighting.

v0.3.1 Phase A polish

Fixed user defined enum resolution, bare enum variants in typed contexts, the native entry point symbol, and path lookup. Added stress.vpp and stress.ps1 and refreshed the specification and README.

v0.4.0 Language Core Phase B

Added let mut, monomorphized generics, traits and impl with static dispatch, and compile time match exhaustiveness checking. Examples, tests, and the language specification were updated.

v0.4.4 Distribution milestone

Added GitHub release bundles, Marketplace publication of the V++ Language extension, release and Marketplace documentation, and fixes to the LSP and Windows setup flow.

v0.5.0 Documentation and project experience

Added the official website, twenty guided projects, GitHub Pages deployment, a documentation hub with more than thirty guides, contributing, security and code of conduct paperwork, a v0.5.0 extension update, and installer PATH handling for vpp and bundled clang.

v1.0.0 Stable language

Debugger (F5), Test Explorer, frozen SPEC v1.0, Parity Promise, compat CI on all examples.

v1.0.3 Release polish

Formatter fix, GitHub Releases publish reliably on Windows, extension 1.2.0 for Marketplace.

v1.0.4 CMake integration

CMake modules (FindVpp, vpp_add_executable) ship in the Windows installer and portable zip.

17. Current v1.0.4 status

The repository ships compiler and VS Code extension v1.0.4. v1.0.4 adds CMake integration: FindVpp.cmake and Vpp.cmake are bundled under the install folder, plus debug, Test Explorer, watch, and a formatter fix. SPEC v1.0 is frozen with a Parity Promise: the same .vpp file runs in the interpreter, debugger, and native build. Linux and macOS native bundles are optional CI targets; build from source on Unix today.

18. Future roadmap

Future versions are plans, not promises. The Docs page should visually distinguish roadmap items from shipped features.

v0.6 Interactive development

Potential focus: finish the REPL, improve the standard library, and make interactive experimentation easier.

v0.7 Platform and distribution

Potential focus: improve Linux and macOS release support and complete signed Windows distribution.

v0.8 Debugging

Potential focus: debugger integration, breakpoints, stepping, and richer editor debugging.

v0.9 Stabilization

Potential focus: broad bug fixing, compatibility work, package ecosystem maturity, and preparation for a stable language contract. v1.0 - Stable language The current roadmap identifies a frozen language specification, debugger extension, VS Code Test Explorer, hosted package registry, and curriculum or interactive tutorial work.

The definition of v1.0 should be stability rather than ecosystem size. A v1.0 user should have a documented language, reliable installation, predictable compiler behavior, useful tooling, tested native execution, and a clear compatibility policy.

19. Compatibility policy

Before v1.0, language breaking changes may occur as the project evolves. Once the specification is frozen, breaking language changes should require a major version. Each release should document language changes, compiler changes, tooling changes, runtime changes, known compatibility effects, and any course examples that need updating.

20. Recommended Docs navigation

Getting Started: installation, Hello World, first project, VS Code setup, CLI basics.

Language: syntax, types, variables, functions, control flow, arrays, structs, enums, Option, Result, match, generics,

traits, modules, mutability.

Standard Library: io, math, string, collections, fs, json, process, plus future modules as they ship.

Toolchain: CLI, formatter, tests, parity, LSP, VS Code extension, package manager, registry.

Compiler: architecture, IR, LLVM backend, runtime, memory model, diagnostics, compiler development.

Projects: the twenty guided builds.

Reference: formal specification, builtins, error codes, CLI, compatibility.

Project: history, roadmap, contributing, security, privacy, releases, FAQ.

21. Twenty official learning projects

Each project page should contain an outcome, prerequisites, the problem, theory, incremental code blocks, explanation after each block, expected output, run instructions, common mistakes, a complete final program, and optional challenges. The examples should always be tested against the current compiler.

22. Contributing

V++ is open source under the MIT license. Contributors should be able to clone the repository, build it, run tests, understand the compiler architecture, make a focused change, and verify behavior.

git clone https://github.com/shauryaR790/V-.git
cd V-
cargo build --release --features codegen,lsp
cargo test --all-targets

Language changes should update the specification, changelog, examples, relevant documentation, and parity coverage where native execution is affected.

23. Release documentation

Releases use versioned numbers such as v0.5.0. Release automation builds distribution artifacts from version tags. The exact platform matrix and signing state can change, so the live release documentation should remain authoritative. The website history should distinguish language milestones from patch and distribution milestones so users can understand what changed.

24. FAQ

25. Documentation maintenance rules

Never present a roadmap item as shipped. Keep examples executable against the current release whenever possible. When implementation and documentation disagree, verify behavior with the compiler and tests before changing the public documentation. Every breaking language change should update the specification, changelog, examples, and affected learning projects. Use version labels on language reference pages so users know which syntax they are reading.

26. Suggested Docs landing page copy

Learn V++ A readable compiled language with static typing, local inference, native compilation, and a growing toolchain. Start here Install V++ Create your first .vpp file

Run it with vpp run

Build it with vpp build Continue with the twenty guided projects Explore the language Learn variables, functions, control flow, arrays, structs, enums, Option, Result, match, generics, traits, modules, and mutability. Understand the compiler Follow source code from lexing and parsing through type checking, interpretation or V++ IR, LLVM, the runtime, and a native executable. Build with V++ Use the CLI, standard library, package manager, LSP, VS Code extension, formatter, tests, and native compiler. See where it is going Read the history and roadmap to distinguish stable features from planned work.

27. Accuracy note

This master content was assembled from the public V++ repository as available on August 20, 2026, especially its README, CHANGELOG, SPEC, compiler architecture document, and roadmap. The repository currently reports v0.5.0 while its formal specification file is still titled v0.4. The website should either update the specification title or clearly label it as the v0.4 language reference. This avoids presenting an older reference as the complete v0.5 specification. Future releases in this document are intentionally marked as plans. They should be converted to shipped status only after the implementation and release notes confirm them.