Getting Started

Install the compiler, run your first .sio program, and learn the basics.

Getting Started

This guide is the practical entry point for the current public Sounio workflow. It assumes you are starting from the checked-in compiler artifact, validating with souc check, and treating repository gates and fixtures as the source of truth for what is actually supported right now.

Current contract

  • The safest documented entry point is the canonical launcher at $(pwd)/bin/souc.
  • The first thing to trust is check, not run, because execution paths vary by host artifact and backend support.
  • The checked launcher reports souc 1.0.0-beta.5 today (README badge may read 1.0.0-beta.6 during release reconciliation). The default public workflow is self-hosted native ELF/Mach-O — not a Rust/Cargo build and not Cranelift JIT as the onboarding story.
  • Gate-backed status is currently strong for the stdlib reliability lane (251/251 in the committed artifact), the fmri and darwin_pbpk science lanes, and seven required hyper-execution lanes.
  • Optional omega profiles (Cranelift JIT, GPU) exist separately from the default bin/souc contract. Confirm capability with souc info before documenting it as available.

Bootstrap the verified toolchain

git clone https://github.com/sounio-lang/sounio.git
cd sounio

export SOUC_BIN="$(pwd)/bin/souc"
export SOUNIO_STDLIB_PATH="$(pwd)/stdlib"

"$SOUC_BIN" --version
"$SOUC_BIN" info
"$SOUC_BIN" sysroot stdlib-paths

Validation sequence used by these docs

  • "$SOUC_BIN" check examples/hello.sio confirms the basic CLI and stdlib path are wired correctly.
  • "$SOUC_BIN" check tests/run-pass/covid_2020_kernel.sio validates a current epistemic science fixture.
  • "$SOUC_BIN" check tests/run-pass/vancomycin_propagation.sio validates the current confidence-propagation path.
  • "$SOUC_BIN" check tests/compile-fail/vancomycin_low_conf.sio should fail with the documented confidence mismatch, proving the refusal path is active.

Where to look next in the repo

  • examples/ contains the smallest onboarding programs, but not every file there should be treated as equally production-ready.
  • tests/run-pass/ and tests/compile-fail/ are the best evidence for language behavior that is supposed to work today.
  • artifacts/stdlib/*.json record the gate-backed status for stdlib reliability, science lanes, and hyper execution.
  • docs/guide/MINIMUM_VIABLE_SOUNIO.md explains the conservative contract this site is following.

Minimal first program

fn main() with IO {
    println("Hello, Sounio!")
}

Caveats before you go deeper

  • Do not treat a top-level Cargo build as the primary public onboarding path; it is no longer the clearest story for this repo state.
  • Do not infer support from directory presence alone. The repo contains active implementations, stubs, disabled files, and long-horizon experiments side by side.
  • If you need more than the checked self-hosted launcher exposes, confirm that capability with souc info or by rebuilding a different artifact profile before documenting it as available.