Compile-time filesystem reads

Status: available. comptime fs.* is implemented by the compiler's read-only evaluator. This page describes the current implementation, not a proposal.

Use std::fs inside comptime to read project files while compiling and bake their values into the generated program. Runtime code uses the same module without the comptime prefix.

use std::fs

let banner = comptime fs.read("banner.txt").trim()
print(banner)

With banner.txt containing Zolo docs, the program prints:

Zolo docs

Paths are resolved relative to the source file that contains the call. This is especially useful for modules: a read in src/ui/theme.zolo resolves from src/ui, not from the entry file or the compiler's working directory.

Available operations¶

Only the following read-only operations are recognized by the comptime evaluator:

Call	Compile-time result
`fs.read(path)`	UTF-8 `str`
`fs.read_bytes(path)`	`[int]`, one value per byte
`fs.exists(path)`	`bool`
`fs.list(path)`	sorted `[str]` of direct entry names
`fs.stat(path)`	map with deterministic `size` and `kind` fields
`fs.read_dir(path)`	sorted map of direct UTF-8 files, keyed by name
`fs.glob(pattern)`	sorted map of matched UTF-8 files

fs.glob supports *, **, and ?. Bracket classes such as [a-z] are not implemented. read_dir and glob skip non-UTF-8 files; use read_bytes when you need binary data.

Mutation APIs such as fs.write, fs.remove, and fs.create_dir are runtime operations and are rejected in a comptime expression.

Path and budget rules¶

Absolute paths are rejected.
A relative path is normalized lexically and must remain under the nearest project root (the directory containing zolo.toml). In a single-file program, the source file's directory is the boundary.
Without source-file context, such as some REPL or compiler-API uses, the current working directory is the base.
Each file read is capped at 16 MiB, and the ordinary comptime allocation budget still applies to the resulting values.
fs.exists is a probe: a missing or out-of-bound path produces false instead of exposing a path error.

The containment check is currently lexical. It does not canonicalize and re-check the destination of a symlink, so do not treat comptime evaluation of untrusted projects as an operating-system sandbox.

Diagnostics and caching¶

Filesystem failures are regular comptime errors attached to the call span. Messages identify the operation and resolved path; there are no public E_PathNotConst or E_NotUtf8 diagnostic codes. Do not build tooling around those old proposal names.

Comptime file reads are not currently recorded in the module dependency list. Watch mode and the opt-in run cache therefore do not promise invalidation when only an embedded file changes. Re-run the build (or use --no-cache) after editing embedded assets.

Comptime by example introduces the evaluator and @comptime functions.
Standard library covers runtime std::fs.
The executable embedding example reads a sibling file and transforms it before runtime.

Compile-time filesystem reads

Available operations¶

Path and budget rules¶

Diagnostics and caching¶

Related material¶