CLI usage examples

This page is a grab bag of practical workflows for the silk toolchain. It focuses on how people actually use the CLI: quick feedback (check), tests that integrate with CI (test), and explicit build outputs (build).

For the conceptual model, read: CLI and toolchain.

For flag-by-flag reference, use the manpages (sidebar → man).

Minimal loop: check → test → build#

Create hello.slk:

import { println } from "std/io";

fn main () -> int {
  println("hello {s}", "world");
  return 0;
}

Then:

silk check hello.slk
silk test hello.slk
silk build hello.slk -o build/hello

This loop is intentionally boring: each command has one job, and it scales from a single file to large packages.

Formatting#

Format files or directories:

silk fmt src
silk fmt --check .

Reference: silk-format (1)

Explicit module sets (multiple files)#

Passing multiple files defines the module set explicitly:

silk check src/main.slk src/util.slk
silk test  src/main.slk src/util.slk
silk build src/main.slk src/util.slk -o build/app

If you’re just starting a project, this is a great way to keep things simple before introducing manifests and named build targets.

Package builds (`silk.toml`)#

For larger projects, you typically describe the module set in silk.toml and ask the CLI to load it:

silk check --package .
silk test --package .
silk build --package .
silk package inspect --package .
silk package lint --package .

Why this model is valuable:

“what gets compiled” is explicit and reproducible
tooling can reason about packages without executing code
named targets let you build multiple artifacts from one codebase

References:

Build kinds: executable, object, static, shared#

silk build makes the output kind explicit:

# Executable (default)
silk build src/main.slk -o build/app

# Object file
silk build src/lib.slk --kind object -o build/lib.o

# Static library
silk build src/lib.slk --kind static -o build/libfoo.a

# Shared library
silk build src/lib.slk --kind shared -o build/libfoo.so

Emitting C headers for exports#

When building libraries for C consumers, emit a header for exported symbols:

silk build src/lib.slk --kind static -o build/libmylib.a --c-header build/mylib.h

This is a practical bridge between “Silk as a language” and “Silk as a component inside another system”.

Target selection#

Cross compilation and alternate backends are selected explicitly:

silk build src/main.slk --target linux-x86_64 -o build/app
silk build src/main.slk --arch wasm32 --kind executable -o build/app.wasm
silk targets
silk build --list-gpu-targets

Explicit targets keep builds readable: you can tell from the command line what you’re producing.

Mixed CPU/GPU executable#

On Linux x86_64, select the host and device targets independently:

silk build src/gpu_app.slk -o build/gpu-app \
  --target linux-x86_64 \
  --gpu-target amdgcn-amd-amdhsa-gfx1151

The same portable device source can select nvptx64-nvidia-cuda-sm80 for the NVIDIA/CUDA provider. See Pure-Silk CPU/GPU program for a complete buffer, launch, download, and verification example.

Standard library selection (`--std-root`, `--nostd`, `--std-lib`)#

When a module imports std::..., the CLI resolves the standard library from its configured stdlib root.

Common customizations:

# Point at an alternate stdlib root (for custom std distributions or runtimes)
silk check --std-root ./path/to/std src/main.slk
silk build --std-root ./path/to/std src/main.slk -o build/app

# Disable std auto-loading (useful for sandboxed embedding flows)
silk check --nostd src/main.slk

On hosted targets where stdlib archives are used, --std-lib selects the archive to link.

Reference: Custom stdlib root

Docs and manpages from source#

Silk can extract documentation from doc comments:

silk doc src/main.slk -o build/api.md

And render a man-style view of a symbol/module/concept:

silk man std::io

Embedding workflows (C)#

Two common embedding shapes:

Build a library for a C program to link against (object/static/shared + optional C header).
Embed the compiler itself (libsilk) inside another program.

When you’re in the “call a C compiler” world, silk cc is a convenience wrapper:

silk cc -std=c99 -Wall -Wextra my_program.c -o build/my_program

Reference: libsilk (7).

Platform SDK workflows#

Inspect platform device and signing tools before delegating lifecycle actions:

silk devices doctor --json
silk devices list --json
silk codesign doctor --json

On a host with the matching SDK, install and run an app bundle or verify its signature:

silk devices install --kind ios-simulator --app build/MyApp.app
silk devices run --kind ios-simulator --app build/MyApp.app
silk codesign verify --platform ios --input build/MyApp.app

References: silk-devices(1), silk-codesign(1), and Build LumenTrail for iOS.