Software Development Kit
Use a Once language library when an application needs to store and retrieve cache data directly. Use the command line instead when the goal is to execute scripts, build targets, run tests, or manage runtime sessions.
The language libraries intentionally expose the same small cache surface:
- Open the default local cache, an isolated local root, or the effective provider configured for a workspace.
- Store and retrieve content-addressed byte payloads.
- Store and materialize files without loading their complete contents into the host language.
- Build versioned action keys from labeled values and content digests.
- Associate an action digest with a completed action result.
- Remove an action result without deleting its referenced payloads.
- Inspect local cache statistics.
They do not execute commands or load the repository graph.
Choose A Language#
| Language | Package | Call style | Guide |
|---|---|---|---|
| Rust | once crate | Asynchronous | Rust |
| Swift | Once.xcframework and the matching Swift wrapper | Asynchronous | Swift |
| Ruby | buildonce gem | Synchronous | Ruby |
| JavaScript | buildonce package for Node.js | Promise-based | JavaScript |
| C | libonce and once.h | Synchronous | C |
Choose the binding used by the process that owns the integration. All bindings use compatible digests and action-result concepts, so separate tools can share a configured cache without translating records.
Choose A Cache#
The default constructor preserves the lightweight local behavior of earlier releases. Use an explicit local root for test isolation or caller-owned cache lifetimes. Use a workspace constructor when the integration must share the same effective provider as the command line. Workspace selection considers the process override, workspace infrastructure, compatible Tuist project configuration, and the user default in that order.
Statistics describe the local tier. Remote uploads are best effort: a configured remote provider writes through the local tier and keeps the local write usable when the remote service is unavailable. Streamed inputs larger than eight mebibytes remain in the local tier to preserve bounded memory use.
Before You Embed Once#
Use the action-key builder to partition each integration by namespace and add every input that can affect the result. Input order is significant and must be deterministic. The library cannot determine whether an application omitted an input or whether replaying a result is safe.
Start with the smallest useful operation in the language guide, then add action-result storage only after the application has a deterministic action identity.