Builtins

Every function a spec.star, dev.star or secrets.star can call, with its arguments and defaults.

A spec is Starlark: Python syntax with def, if, for, comprehensions and lambda, and no access to files, the network or the clock. On top of the language, FormalSpec adds the builtins on this page.

Every builtin checks its arguments when it runs, so a misspelled or unknown field fails on the line that wrote it. An argument passed as None counts as unset. Positional arguments are listed in the signature; everything else is a keyword.

Besides these, spec.star and dev.star have Starlark's struct, json.encode, json.decode and print.

Files and their globals

load("//modules/cli.star", "cli") resolves from the directory that holds spec.star. Relative loads (load("cli.star")) are an error. Hosts and modules covers gh: loads.

host

host(name, platform, system = None, users = [], modules = [], ssh = name,
     protect = [], persist = [], release_age = None, builders = [], sync = [])

A function in modules receives a struct with:

modules takes pkg, file, service, timer, user, secret, defaults, setting, repo and sync. A sync in modules joins the host's sync list. image(...) and the distro builtins go in system, never in modules.

System layer

image

image(base, packages = None, copr = [], repos = [], stages = [], steps = [],
      kernel_args = [], distro = None)

A bootc image, built by CI and switched to with bootc switch. See The system layer.

An image host runs systemd.

fedora, arch, debian, ubuntu, void, aerynos, tumbleweed

fedora(packages = [], init = "systemd")
tumbleweed(packages = [], kernel_args = [])

A classic distro. All seven take keywords only.

repo

repo(name, url, key = None, fingerprint = None)

A third-party zypper repository. Tumbleweed only.

pkg

pkg(name, source = aqua(name), version = None, mode = "pinned", channel = "stable", ...)

A package. See Packages.

pypi

pypi(name, ...)

A PyPI distribution, for dev.star. Same arguments as pkg except source.

Sources

Each returns a value for pkg(source = ...).

names defaults to the package's own name. zypper("nordvpn", repo = "nordvpn") ties the package to a repo(...), so it waits with that repository when the repository is unreachable.

file

file(path, src = None, content = None, target = None, mode = "managed",
     format = None, owns = {}, on_conflict = "ours", on_drift = "overwrite", perms = None)

A file. A path under ~/ is in the user scope; an absolute path is in the system scope. See Files.

Each mode takes its content one way:

The format comes from the path's extension (.json, .toml, .yaml, .yml, .ini, .plist, .lua) unless format sets it. A dict or list content needs a format. lua writes return { ... }.

list_union, list_replace, list_keyed

list_union(items)
list_replace(items)
list_keyed(field, items)

Strategies for a list under file(owns = ...):

secret

secret(path, src, perms = "0400", owner = None, identities = [])

An age-encrypted file from the repository, decrypted at apply. See Secrets.

Default identities: in the system scope /etc/ssh/ssh_host_ed25519_key, /etc/ssh/ssh_host_rsa_key, then ~/.config/fspec/age.key; in the user scope ~/.ssh/id_ed25519, ~/.ssh/id_rsa, then ~/.config/fspec/age.key.

service

service(name, exec = None, user = False, restart = "no", after = [], env = {},
        description = None, systemd = {}, launchd = {}, display_manager = False)

A service, rendered for the host's init system. See Services and timers.

A service without exec takes only name, user (systemd) and display_manager.

timer

timer(name, exec, schedule, user = False, env = {})

A scheduled job: a systemd timer, a cron entry or a launchd calendar interval.

user

user(name, uid = None, shell = None, groups = [])

On Linux a missing account is created with useradd, and an existing one gets the declared UID and shell with usermod. On macOS the account must exist; fspec sets its login shell and checks the UID.

defaults

defaults(domain, key, value, system = False)

A macOS defaults key. value is a bool, int, float, string, list or dict. system = True writes the machine-wide domain in /Library/Preferences as root.

defaults("com.apple.dock", "autohide", True)
defaults("NSGlobalDomain", "KeyRepeat", 2)

setting

setting(tool, key, value)

A macOS setting behind a command instead of a defaults domain.

setting("pmset", "sleep", 0)
setting("firewall", "globalstate", True)

builder

builder(name, routes = [name])

A machine that builds git(...) packages for a host, reached over ssh. routes are ssh destinations for the same machine, tried in order.

sync, json_keys, keyring

sync(name, peers, paths = [], include = [], exclude = [], keys = None, keyring = [],
     mode = "live", conflict = "newest", after = [], on_receive = None, unless_running = [])
json_keys(path, keys)
keyring(schema = None, attrs = {}, label = None)

App data shared between your hosts over ssh. See Sync between hosts.

An item needs at least one of paths, keys or keyring. keyring needs a schema or attrs; an attribute value ending in * matches a prefix.

Helpers

dev.star

dev

dev(packages = [], libs = [], bins = [], env = {}, services = [], shell_hook = None,
    container = None, fallback_container = None, platforms = [...])

dev.star has a global platform with name, os, arch, is_linux and is_darwin.

lib, bin

lib(name, apt = None, dnf = None, zypper = None, pacman = None, xbps = None, moss = None, brew = None)
bin(name, ...)

lib("gtk4") is the pkg-config module gtk4, or with a .so name a shared object. bin("cmake") is an executable. fspec update asks each package manager which package provides it. Name the package by hand where that lookup cannot: lib("x", apt = "libx-dev").

service (in dev.star)

service(name, exec = None, version = None, image = None, ports = [], env = {})

Without exec, the image <name>:<version> (or image), pinned by digest, run with each port published on 127.0.0.1. With exec, a command from the project's environment.

secrets.star

kyan = "age1..."
laptop = "ssh-ed25519 AAAA..."

secrets = {
    "secrets/openai.age": [kyan, laptop],
    "secrets/wifi.age": [kyan],
}

Maps each .age file, relative to the spec directory, to the public keys it is encrypted to: age recipients (age1...) or ssh public keys (ssh-ed25519 ..., ssh-rsa ...). fspec secret edit and fspec secret rekey read it.