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.

ruby

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:

bash

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:

ruby

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:

ruby

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.