Ruby Software Development Kit

The Ruby library is the buildonce gem. It exposes Once cache primitives for Ruby applications and tools. Script execution belongs to the command line and is not part of this library. See the language-library overview to compare the available bindings.

require "buildonce"

cache = Once::Cache.new
digest = cache.put_blob("hello")
bytes = cache.get_blob(digest)

raise unless bytes == "hello"

Installation

Install the gem from RubyGems:

gem install buildonce

The gem includes prebuilt native Once libraries for supported platforms. Set ONCE_LIBRARY_PATH when you need to load a custom libonce build.

Cache

Once::Cache can open the default local cache, an explicit local root, or the effective provider for a workspace. The default follows the X Desktop Group base-directory convention: its cache root is $XDG_CACHE_HOME/once/cas when XDG_CACHE_HOME is set, and $HOME/.cache/once/cas otherwise.

Ruby methods are synchronous. digest(bytes) only hashes bytes and does not touch storage. When bytes is a string, the library uses the string's byte representation.

Application programming interface	Use
Once::Cache.new	Opens the default local cache using the operating-system convention.
Once::Cache.new(local_cache_root:)	Opens an isolated local cache at a caller-owned root.
Once::Cache.new(workspace_root:)	Resolves the effective provider for a workspace.
version	Returns the linked Once version.
digest(bytes)	Returns the content digest for bytes without writing them to the cache.
put_blob(bytes)	Stores bytes and returns their content digest.
put_file(path)	Stores a file without loading its complete contents into Ruby memory.
get_blob(digest)	Reads bytes for a digest.
get_blob_to_file(digest, path)	Writes a blob to a file and returns its byte count.
has_blob?(digest)	Returns whether a blob exists.
put_action_result(result, action_digest:)	Stores a cached result for an action digest.
get_action_result(action_digest)	Returns a cached result when one exists.
forget_action(action_digest)	Removes one cached action result. Referenced blobs are left intact.
stats	Returns local cache statistics.

Prefer put_file and get_blob_to_file for logs, archives, compiler outputs, and other payloads whose size is not tightly bounded.

Action Keys

Once::ActionKey builds a versioned identity from ordered, labeled inputs:

source = cache.put_file("inputs/source")
action_digest = Once::ActionKey.new("example.compile")
                               .add_bytes("tool", "compiler")
                               .add_digest("source", source)
                               .digest

Input order is significant and must be deterministic.

Types

Use Once::ActionResult for cached action metadata:

Once::ActionResult.new(
  exit_code: 0,
  stdout: stdout_digest,
  stderr: nil,
  outputs: {},
)

stats returns Once::CacheStats with blob_count, blob_bytes, action_count, and action_bytes.