Skip to content
Z

Getting started

Z is currently developed from its source repository. There is not yet a versioned compiler distribution or package manager.

Requirements

Section titled “Requirements”
  • Bun 1.3.14, or the version named by the repository
  • Clang available on PATH
  • On macOS, Xcode Command Line Tools for Objective-C, AppKit, and Swift probes

Clone the repository, then confirm the toolchain:

Terminal window
git clone https://github.com/popaprozac/z.git
cd z
bun --version
clang --version
bun run test

Your first program

Section titled “Your first program”

Create hello.zs:

import console from "std/console";


function main(): i32 {
  const answer = 20 + 22;
  console.log(`answer=${answer}`);
  return 0;
}

Run it through the Stage-0 CLI:

Terminal window
bun run z run hello.zs

main is required for an executable entry point and returns the native process exit code. Export-only .zs files are valid modules and do not require main.

Z uses .zs for source and .zd for foreign declaration contracts. It does not claim .z, which Unix tooling commonly recognizes as a compressed archive.

Useful commands

Section titled “Useful commands”
Command Purpose
bun run z check file.zs Parse, type-check, and validate ownership
bun run z emit file.zs Print the generated C-family translation unit
bun run z metadata path Print versioned checked metadata for tools and generators
bun run z run file.zs Compile and execute a native binary
bun run z run file.zs --release Build and run with optimization
bun run z test path Run reachable inline Z tests
bun run bootstrap Build the local native z compiler

Once the bootstrapped z binary is on PATH, project commands become simply z check ., z run ., and z build ..

Framework tools may add generated Z modules for one invocation without editing z.json or authored source. They pass a versioned build product explicitly:

Terminal window
z build . --generated .zapp/generated/services.zbuild.json

The overlay uses exact module specifiers, cannot shadow project or standard imports, and generated source is checked as ordinary Z. Stage 0 and the fixed-point native driver also execute source-hashed, exact-target checked call adaptation. A generated adapter can import an exported type declared beside main: its compiler-created function link does not invent a source import cycle. Ordinary imports in either authored or generated files still reject cycles, and generated code keeps the normal type and visibility checks.

Native dependencies belong in z.json. Portable libraries use target.link.libraries; Apple executables can use target.link.frameworks for checked names such as AppKit and WebKit without adding a Swift subtarget or raw linker flags. Reusable source packages carry their required header paths, libraries, and frameworks transitively under library.native, so applications do not duplicate package implementation details.

Editor support

Section titled “Editor support”

The repository includes a VS Code/Cursor extension with syntax highlighting, hover, completion, diagnostics, and a schema for z.json. Z is pre-alpha, so the extension is installed from the repository rather than a public marketplace. Semantic errors remain localized: syntax-derived highlighting and local hover survive elsewhere in the file, while unchanged documents retain their most recent rich semantic information if an imported dependency temporarily breaks.

For current bootstrap details, testing tiers, and editor installation, use the repository documentation.