Oscan

A small, statically typed language for writing clear standalone programs.

Oscan favors explicit, predictable code: types are written out, effects are visible in function signatures, and errors are values rather than exceptions. It is designed to be approachable for people and reliable for AI coding tools.

Why Oscan?

• Small and explicit: no implicit type coercions, hidden exceptions, or surprise control flow.
• Safe by design: bounds checks, overflow checks, no null pointers, and no manual memory management. See the safety guide.
• Batteries included: 328 built-in functions for strings, files, math, collections, networking, graphics, TLS, and more.
• Standalone programs: produce native executables, including freestanding programs that do not depend on libc on supported targets.
• Clear effects: fn declares pure functions and fn! declares functions that may perform I/O or other side effects.
• Errors as values: Result<T, E>, exhaustive match, and try make failures explicit.

Install

Download the latest release from GitHub Releases. Choose the LLVM slim package for the smallest recommended install, or choose full to use LLVM, Cranelift, and C from one compiler with --backend.

Platform	Recommended download	Notes
Windows x86_64	oscan-vX.Y.Z-windows-x86_64-llvm.msi or .zip	Every profile has both formats; -full.msi/.zip includes all backends
Linux x86_64	oscan-vX.Y.Z-linux-x86_64-llvm.tar.xz	-full.tar.xz includes all backends; LLVM requires glibc 2.34+
macOS x86_64	oscan-vX.Y.Z-macos-x86_64-c.tar.gz	Requires Xcode Command Line Tools

Windows and Linux provide full, llvm, cranelift, and c profiles. Full contains one backend-neutral compiler; the others are smaller slim packages. Windows publishes both .msi and .zip for all four profiles. Profile MSIs upgrade independently and may be installed together. If the legacy flat LLVM MSI is installed, run the current LLVM MSI once to migrate it before installing another MSI profile. Each release includes SHA256SUMS; keep the downloaded file's original name and verify it before installing. The installation guide has step-by-step verification, upgrade, and uninstall instructions.

Windows

Install the latest recommended package:

iwr -useb https://raw.githubusercontent.com/lucabol/Oscan/master/scripts/install-latest.ps1 | iex

Install full, or select a slim package explicitly:

iwr -useb https://raw.githubusercontent.com/lucabol/Oscan/master/scripts/install-latest.ps1 -OutFile install-latest.ps1
.\install-latest.ps1 -Profile full
oscan-default set full
.\install-latest.ps1 -Backend llvm
.\install-latest.ps1 -Backend cranelift
.\install-latest.ps1 -Backend c

Archive profiles coexist as oscan-full, oscan-llvm, oscan-cranelift, and oscan-c. Plain oscan uses a per-user sticky selection shared by archive and MSI installs. Installing or upgrading a profile never changes an existing selection. If none exists, the first oscan invocation chooses the highest-priority installed profile and persists that exact choice.

oscan-default set full       # explicit and sticky
oscan-default show
oscan --version
oscan-default auto           # optional full > llvm > cranelift > c fallback

Removing the explicitly selected profile does not silently switch compilers: oscan fails with instructions until that profile is reinstalled or oscan-default set <profile>/oscan-default auto is run. MSI selection is always performed after installation as the target user; -SetDefault remains archive-only because MSI installation is elevated.

Linux

Download an archive and SHA256SUMS, verify it, extract it, and run the included installer. This example installs full and selects it as the default:

tar xf oscan-vX.Y.Z-linux-x86_64-full.tar.xz
./oscan-vX.Y.Z-linux-x86_64-full/install.sh
oscan-default set full
oscan --version
oscan app.osc --backend cranelift

On Debian or Ubuntu, the LLVM and full packages also need:

sudo apt-get install libedit2 libffi8 libxml2 libz3-4 libzstd1 zlib1g

macOS

Install Apple's command-line tools, then download and extract the macOS package:

xcode-select --install
tar xf oscan-vX.Y.Z-macos-x86_64-c.tar.gz

Run the included install.sh to create oscan-c without disturbing another profile, then run oscan-c --version. Select it with oscan-default set c; --set-default remains a compatible installer shortcut.

Build from source

Building the compiler requires Rust:

git clone https://github.com/lucabol/Oscan.git
cd Oscan
cargo build --release

The binary is target/release/oscan (oscan.exe on Windows). Prebuilt releases are easier for most users because they include the backend support files they need.

Your first program

Create hello.osc:

fn! main() {
    println("Hello, Oscan!");
}

Compile and run it:

oscan hello.osc --run

Or build an executable to run later:

oscan hello.osc
./hello

On Windows, run .\hello.exe.

The language at a glance

This example shows explicit types, pure and impure functions, recursion, ranges, and string interpolation:

fn fib(n: i32) -> i32 {
    if n <= 1 {
        n
    } else {
        fib(n - 1) + fib(n - 2)
    }
}

fn! main() {
    let name: str = "Oscan";

    for i in 0..10 {
        println("{name} fib({i}) = {fib(i)}");
    };
}

Feature	Oscan syntax
Explicit types	let count: i32 = 10;
Mutable values	let mut count: i32 = 10;
Pure function	fn add(a: i32, b: i32) -> i32 { a + b }
Side-effecting function	fn! save() { ... }
Error propagation	let value: i32 = try operation();
Exhaustive matching	match result { Result::Ok(v) => ..., Result::Err(e) => ... }
Dynamic array	let values: [i32] = [1, 2, 3];
Import	use "math.osc" as math;

Continue with the introductory tutorial, which builds a small wc-style command-line program step by step.

Everyday commands

Command	Result
oscan app.osc --run	Compile and run
oscan app.osc	Build a native executable
oscan app.osc -o program	Choose the executable name
oscan app.osc -o program.c	Emit C source
oscan app.osc -o program.ll	Emit LLVM IR
oscan app.osc --backend llvm	Select LLVM explicitly
oscan app.osc --backend cranelift	Select Cranelift explicitly
oscan app.osc --opt-level speed	Favor generated-code speed over the default size profile
oscan app.osc --backend c	Select the C backend explicitly
oscan app.osc --debuginfo line-tables	Keep Oscan source locations for debugging
oscan --help	Show every option

Full contains every backend; slim packages contain one and identify the full or matching slim package when another is requested. --opt-level size|speed applies to LLVM and Cranelift generated code; the default is size.

Debug information is opt-in: --debuginfo none is the default, while --debuginfo line-tables enables source breakpoints, stepping, stack symbolization, and imported-file locations without changing the selected optimization level. Oscan does not generate backend-independent local-variable or type descriptions at this level, although a C toolchain may include additional records. See compiler technical details for backend and debugger-format notes.

Examples

Run any example with oscan <path> --run.

• Command-line tools: Hello World, word count, grep, sorting, and word frequencies.
• Files and data: file I/O, Base64 encoding, and SHA-256 checksums.
• Networking: HTTP client and web server.
• Graphics and games: graphics demo, Conway's Game of Life, and spirograph.

Browse the full examples directory.

Built-in functions

328 built-in functions across 21 categories: I/O, String, Conversion, Character, Math, Bitwise, File I/O, Filesystem, Path, Socket, HashMap, Array, Date/Time, System, Environment, Terminal, Process, Graphics, TrueType, Image, TLS.

See the full built-in function reference for signatures and descriptions.

Technical details

• Backends: LLVM is recommended, Cranelift is an independent native alternative, and C is the portability and source-emission backend.
• Runtime: programs can use Oscan's freestanding runtime or opt into hosted libc mode with --libc.
• Memory: arena allocation provides deterministic cleanup without manual free calls or a garbage collector.
• Targets: release and cross-compilation support varies by platform and backend.
• Distribution: full contains all backends; coexistence-safe slim profiles contain one backend and its required support files.

See Compiler Technical Details for backend selection, package layouts, runtime and linker behavior, supported targets, toolchain discovery, source builds, and validation.

Documentation

• Introductory tutorial
• Language guide
• Built-in function reference
• Safety guide
• Language specification
• Compiler technical details

When using an AI coding agent, include the Oscan language reference in its context. GitHub Copilot loads it automatically for .osc files.

Contributing

Contributions that fit Oscan's small, explicit language design are welcome. See the test suite guide and release guide for development workflows.

License

MIT