Expand description
The file operations of task programs, behind the fs functions and the dotenv
reads of env.load_file and env.read.
Every operation resolves its path against the task directory, where an
absolute path stands for itself and paths outside the tree are allowed, and it
records each access it makes in the task’s Accesses:
- a read of a file’s content is a
read, and a path found missing is aprobe; - an existence check is a
probe; - reading a directory’s entries is a
list, and a missing directory is aprobe; - a write is a
writeof the file and of every parent directory it created.
Writes happen only when the content differs, so an unchanged file keeps its
timestamps; a write is recorded either way. A write that changes the file is
also a change, which FileChanges keeps with when it happened, so a pass in
which a task program changed a file does work and the task is the file’s last
writer. Text is UTF-8: bytes that are not valid UTF-8 are replaced with U+FFFD, as
with command output. JSON is written in a stable form: object keys sorted by their
UTF-8 bytes, indent spaces per level, and a trailing newline.
For the observation report of kizz run --output, the operations can also note
how each access ended (Files::noting): into AccessOutcomes, ok for an
access whose operation succeeded, and otherwise the number of the system’s
error, which AccessOutcomes::observations names through the tracer’s
error-name query, such as ENOENT for a missing file’s probe. Without it, as in
every build, nothing more than the accesses is kept.
No operation can panic (“Kizz never panics”): a glob pattern is split at its
first glob component with slice::get, never split_at, and the indentation of
JSON is built in space reserved with String::try_reserve_exact, never with
str::repeat, which panics when the length overflows, so an indent too large
for memory is an error of the write.
Structs§
- Access
Outcomes - How the file accesses of a task program ended, for the observation report of
kizz run --output: each path with its access kinds, and each kind with how the operations that made it ended, before the errors are named. - Changed
File - A file that a task program changed, and when.
- File
Changes - The files that a task program changed through
fs.writeandfs.write_json, in the order it first changed each one, without repeats. - Files
- The file operations of one task: paths resolve against the task directory, and every access is recorded, with every file a write changed.
Enums§
- File
Error - A file operation that failed.
Functions§
- stable_
json valueas stable JSON: object keys sorted by their UTF-8 bytes, each element and member on its own line indented byindentspaces per level,": "between a key and its value, empty arrays and objects as[]and{}, and a trailing newline.