silk(7) — Silk Toolchain Overview

NOTE: This is the Markdown source for the eventual man 7 page for Silk. The roff-formatted manpage should be generated from this content.

Name#

silk — overview of the Silk language toolchain, documentation, and conventions.

Description#

Silk is a high performance general purpose programming language with formal verification built in. Silk targets computer systems, mobile / tablet devices, WASM / WASI runtimes, and the web.

Silk is a native compiler toolchain with:

• a CLI entrypoint (silk(1)),
• an embedding API (libsilk(7) and the silk_* functions documented in section 3),
• and a standard library under the std:: namespace.

Online documentation:

• https://oro.computer/silk (entry point)
• https://oro.computer/silk/docs/ (documentation)
• https://oro.computer/silk/spec/2026/ (spec snapshot)

The toolchain is intended to be discoverable from the terminal instead of requiring repository spelunking:

• silk man opens the nearest package overview when one is in scope; otherwise it shows the shipped entry surface,
• silk man --list lists the shipped commands/concepts plus common stdlib entrypoints,
• silk man --search <pattern> searches commands, concepts, stdlib modules, public stdlib symbols, and package-local pages/symbols when a package root is in scope,
• silk doc --man <query> -o <path> writes the generated roff page to a file,
• silk cache summarizes the managed cache root and helps prune or compact it without deleting unknown files under that root; managed cache mutations are lock-coordinated with normal builds,
• inspection/reporting commands such as check, targets, graph, size, error, package, cache, env, and format support --json where a stable machine-readable result is useful,
• silk proto compiles proto3 schema files to Silk modules without invoking protoc, uses std::protobuf for wire-format helpers, and can emit complete versioned descriptor JSON for tooling,
• and REPL users can use .man <query> for current-session, imported, and std::... symbol/module docs.

Discovery Workflow#

Read the manpage sections as:

• section 1 — commands and subcommands,
• section 3 — public API / stdlib modules and symbols,
• section 7 — concepts, overviews, and workflows.

Recommended terminal workflow:

1. start with silk man 7 silk,
2. list or search when you do not know the exact page spelling yet,
3. open the exact page or symbol directly,
4. move to silk doc --man when you need a saved/generated roff file,
5. use .man inside the REPL for narrower session-level browsing.

Current Code Generation Coverage#

The compiler currently supports full parsing and type checking, but code generation is not yet implemented for the full language surface. When a program type-checks but uses a construct outside the currently implemented codegen coverage, builds fail with E4001 diagnostics that point at the rejected construct and name its kind.

The currently implemented coverage is documented in:

• silk(1) (see the build command and its notes),
• cli silk,
• and runnable fixtures under tests/silk/.

Source Layout#

• Silk source files use the .slk extension.
• Package builds are driven by a manifest file named silk.toml (see package manifests).
• The default stdlib implementation is a directory tree rooted at std/ and is imported via import std::...;.

Standard Library#

The std:: package namespace is the primary stdlib surface. The compiler can auto-load std::... modules from a configured stdlib root, and hosted builds may link a prebuilt stdlib archive.

See:

• overview for module inventory and conventions,
• conventions for ownership and error-handling patterns,
• cli silk for stdlib root selection and archive linking behavior.

Formal Silk#

Formal Silk verification is an optional part of the toolchain. The verifier uses Z3 and can be configured via CLI flags or environment variables.

See:

• formal verification
• diagnostics (verifier diagnostics)

Examples#

# Start from the toolchain overview.
silk man 7 silk

# List the shipped discovery surface.
silk man --list

# Search when you only know part of the name.
silk man --search fs
silk man --search String

# Open a command page, a stdlib module page, and a stdlib symbol page.
silk man build
silk man cache
silk man std::fs
silk man std::strings::String

# Use package-aware overview/docs aliases when silk.toml is in scope.
silk man readme
silk man docs

# Inspect and preview managed cache cleanup.
silk cache
silk cache prune --dry-run
silk cache list --json

# Write a generated manpage to a file.
silk doc --man std::fs -o std_fs.3

See Also#

• silk(1)
• silk-build(1), silk-package(1), silk-cache(1), silk-check(1), silk-targets(1), silk-graph(1), silk-size(1), silk-test(1), silk-doc(1), silk-man(1), silk-guide(1), silk-error(1), silk-proto(1), silk-cc(1)
• silk_compiler(3), silk_error(3), silk_bytes(3), silk_abi_get_version(3), silk_amdgpu_aql_dispatch_packet_build(3)
• libsilk(7)
• https://oro.computer/silk