Yo logo

Yo Programming Language v0.2.32

A general-purpose, ahead-of-time compiled language with algebraic effects

GitHub Standard Library Language Design

Yo

English | 简体中文

Work in Progress :) Not Ready!

https://shd101wyy.github.io/Yo

LLM-friendly to write, human-friendly to read.

A multi-paradigm, general-purpose, compiled programming language. Yo aims to be Simple and Fast (around 0% - 15% slower than C).

The name Yo comes from the Chinese word 柚 (yòu), meaning pomelo, a large citrus fruit similar to grapefruit. It's my daughter's nickname.

📖 My Story with Programming Languages — the journey from Java at 16 to building Yo.

Features

For the design of the language, please refer to DESIGN.md.

Below is a non-exhaustive list of features that Yo supports:

Image

Installation

Installs a native prebuilt compiler.

# macOS / Linux
$ curl -sSL https://shd101wyy.github.io/Yo/install.sh | sh

# Windows (PowerShell)
> irm https://shd101wyy.github.io/Yo/install.ps1 | iex

This installs to <prefix>/lib/yo/<tag> and links <prefix>/bin/yo, with the prefix defaulting to $HOME/.local. Useful options:

Option Meaning
-v, --version=<tag> install a specific release (default: latest)
-p, --prefix=<dir> install prefix — /usr/local for system-wide (uses sudo)
--from-source build from the published single-file yo.c
-cc, --c-compiler=<cc> C compiler for the source build (implies --from-source)
-cflags, --c-flags=<f> extra C flags for the source build (implies --from-source)
-u, --uninstall uninstall instead of install
--dry-run show what would happen, change nothing 
# a specific release, system-wide
$ curl -sSL https://shd101wyy.github.io/Yo/install.sh | sh -s -- --version=v0.2.4 --prefix=/usr/local

# build from source with your own toolchain
$ curl -sSL https://shd101wyy.github.io/Yo/install.sh | sh -s -- -cc=gcc -cflags='-march=native'

Platforms without a prebuilt bundle — pass --from-source. The installer downloads the release's single-file yo.c and compiles it with your own C compiler, so it links against your own libc and loader. This is the answer on NixOS, where the prebuilt binary's hardcoded ELF interpreter (/lib64/ld-linux-x86-64.so.2) does not exist.

Note: --from-source needs a release that publishes the single-file yo.c. Releases up to and including v0.2.4 predate that artifact, so the option only works on releases made after it. The installer says so explicitly rather than failing obscurely.

The installer puts the yo command on your PATH. Run yo --help to see the available commands.

Yo transpiles to C, so a C compiler is required to produce machine code. The install script above sets one up for you — these guides are for configuring the toolchain by hand, or for diagnosing a failed install.

Targeting WebAssembly needs Emscripten as well — WASM setup.

Quick Start

$ yo init my-project        # Scaffold a new project
$ cd my-project
$ yo build run              # Build and run
Hello, world!

yo init generates a project with a build file, source, and tests — plus the bundled agent skill files and AGENTS.md/CLAUDE.md so AI coding agents pick up version-matched Yo knowledge (skip with yo init --no-skills):

my-project/
├── build.yo              # Build configuration
├── src/
│   ├── main.yo           # Entry point
│   └── lib.yo            # Library module
├── tests/
│   └── main.test.yo      # Unit tests
├── .agents/skills/       # Agent skill files (AGENTS.md lists them)
├── AGENTS.md             # Guidance for AI coding agents
└── CLAUDE.md             # Points at AGENTS.md

src/main.yo:

{ println } :: import("std/fmt");

main :: (fn() -> unit)({
  println("Hello, world!");
});

export(main);

Common build commands:

$ yo build                  # Build all artifacts
$ yo build run              # Build and run the executable
$ yo build test             # Run tests
$ yo build --list-steps     # List available build steps
$ yo build doc              # Generate HTML documentation
$ yo fmt                    # Format Yo source files
$ yo fmt --check            # Check formatting without writing changes

Prelude

Every Yo file automatically imports std/prelude.yo, which provides the core types, traits, and builtins available without any explicit import:

Standard Library

Still In Design

Yo ships with a comprehensive standard library covering strings, collections, file I/O, networking, encoding, regex, crypto, and more. For the full module reference, see the Standard Library Documentation.

You can generate documentation for your own project with yo doc:

$ yo doc ./src -o docs --title "My Project"

Or add a documentation step to your build.yo — see yo doc --help for details.

Code examples

Check the ./tests and ./std folders for more code examples.

Hello World

// main.yo
{ println } :: import("std/fmt");

main :: (fn() -> unit)({
  println("Hello, world!");
});

export(main);

// $ yo compile main.yo --optimize 2 -o main
// $ ./main

Example Projects

Project Description
raylib_yo Comprehensive raylib bindings — 35 struct types, 535 functions, 227 constants
tetris_yo | Online Demo Classic Tetris game built with raylib_yo, demonstrating Yo's build system and C interop
http_server_demo_yo Simple HTTP/1.1 server — async I/O, algebraic effects, TCP networking, request parsing & routing
markdown_it_yo Direct port of the popular JavaScript markdown parser markdown-it to Yo, showcasing string processing and performance
markdown_yo | Online Demo High-performance markdown-to-HTML converter — 5-7× faster than markdown-it (native), 2-6× faster (WASM at ≥1 MB). Try it in the browser
yo_http_benchmark HTTP throughput benchmark — Yo vs Bun vs Deno vs Node.js vs Go, using wrk load testing

Contributing

The compiler is written in Yo and builds itself. See CONTRIBUTING.md for the dev environment, the build loop, and how to run the test suites — LLM-assisted contributions included.

Editor Support

Version Management

Yo supports per-project version pinning via a .yo-version file (similar to .nvmrc or .python-version):

# Pin your project to a specific Yo version
yo version pin 0.1.12

# Show current and pinned version
yo version

# Install, list, and clean cached versions
yo version install 0.1.13
yo version list
yo version clean

When a .yo-version file exists, the yo CLI automatically dispatches to the pinned version — downloading and caching the matching native release bundle on first use.

See docs/en-US/VERSION_MANAGEMENT.md for full documentation.

AI Agent Skills

This repository ships a set of agent skill files that teach AI agents how to write Yo programs. The skills are portable — you can copy the .github/skills/ directory into any Yo project and agents will be able to use them there too.

Skill Description
yo-syntax Core language syntax: curly braces, cond/match, structs, enums, operators, modules
yo-core-patterns Everyday patterns: types, generics, traits, error handling, collections, iterators
yo-async-effects Async/await, algebraic effects, Exception, Io, spawning tasks
yo-project-workflow yo CLI commands, build.yo project files, dependency management

Using in your own project

yo init installs the skills automatically (along with an AGENTS.md that lists them). For a project created another way, use the yo CLI:

yo skills install

This copies all skill files into every agent config directory found in the current project (.github, .agents, .claude, .opencode, .openai, .cursor). If none exist, .agents/skills/ is created automatically.

You can also copy them manually:

cp -r .github/skills /path/to/your-yo-project/.github/
# or .agents, .claude, etc depending on your agent platform

Then in any AI agent session, invoke a skill by name (e.g. @yo-syntax) to give the agent contextual knowledge about the Yo language.

CLI output language

CLI help texts and user-facing messages are bilingual (English + 简体中文): yo --lang zh-CN --help or export YO_LANG=zh-CN switches the CLI to Simplified Chinese. English is the default.

License

UIUC/NCSA Open Source License

Yo Programming Language — GitHub · Std Library Docs