Configuration and sources
CacheCow 0.1.0 is published. Native CoW and process-lifecycle acceptance remain unverified; package installation does not establish native support or performance benefits.
Select the project and preset
Run CacheCow from the project directory you intend to build. In a monorepo, the current execution directory identifies the project. CacheCow detects a preset when possible; ambiguous detection must return an actionable error. Use --preset cargo, --preset rspack, or --preset rsbuild to select one explicitly.
These examples assume the real tool is installed and executable and that its cache configuration can be verified. The -- separates CacheCow options from the command and its arguments.
Cargo configuration
Keep Cargo's configured target-dir and build-dir. CacheCow must manage both, processing coincident paths once. Do not relocate source files or treat the whole checkout as a cache. Use Cargo's build-cache documentation to configure Cargo itself.
Toolchain selection and build settings must match the source cache. CacheCow must reject reuse when locations or compatibility cannot be verified. It must not change fingerprints or modification times to force a cache hit. Dirty tracked files and untracked files are allowed; Cargo and rustc retain responsibility for rebuilding them correctly.
sccache
The next source version supports sccache 0.14.x on macOS and Linux when selected with RUSTC_WRAPPER=sccache or an explicit path to the sccache executable. This support is not in the published 0.1.0 binary.
CacheCow verifies the executable and keeps sccache enabled. Each managed session uses a private sccache server so its compiler processes remain protected by the Cargo cache locks. Nested managed Cargo calls share that server. Existing shared sccache servers remain untouched. Your sccache storage settings remain in effect; CacheCow does not clone or manage sccache's own storage.
For managed builds, CacheCow replaces SCCACHE_SERVER_UDS with the session's private socket. Reject Cargo [env] entries that force SCCACHE_SERVER_UDS, including file and command-line configuration; remove force = true to keep the private server. It terminates that server and waits for its compiler processes before releasing the cache locks. Updates to the wrapper executable invalidate discovery and cache compatibility. Windows wrapper management, other wrappers, workspace wrappers, and wrappers selected through Cargo configuration or CARGO_BUILD_RUSTC_WRAPPER remain unsupported.
Rspack and Rsbuild configuration
Configure a persistent cache for the selected project. Only that cache is eligible for CacheCow management. node_modules, package download caches, and frontend final output directories are excluded.
Rspack exposes persistent cache configuration. Rsbuild must expose its configured persistent cache through the frontend integration. CacheCow needs verified cache locations and compatibility information for the actual tool invocation, including its version and build settings.
Use the installed package's executable or a symlink to its declared bin entry. CacheCow resolves versions from that executable's package, not another package installed in the current directory. Shell and batch wrappers, including .cmd launchers, and custom node script.js commands cannot currently prove this identity and are rejected. Windows frontend execution through those launchers remains unsupported.
Create .ccow/discover.cjs in the directory where you run the build. Export an async function that receives { preset, argv, cwd, env }, resolves the same configuration as your build, and returns:
Include every compiler's persistent cache and final output. Declare every configuration file, imported dependency, and absent configuration candidate that could change cache selection in the nonempty inputs list. CacheCow checks these files during discovery and again after waiting for caches. If they change, repeat the command to discover the new cache locations. Use absolute paths and a nonempty settings object that identifies the resolved build settings. This shape is an integration contract, not a complete configuration resolver: connect it to your project's actual Rspack or Rsbuild configuration. Reject options or dynamic configuration you cannot resolve faithfully. Do not build, write artifacts, or print to stdout from the hook. The hook runs as trusted project code.
Add managed cache contents to Git ignore rules. CacheCow refuses caches containing tracked or non-ignored files. Unknown locations and unverified compatibility stop reuse.
Use explicit ccow run when a package-manager script or local executable bypasses PATH shims. It still requires verified preset configuration. Automatic npm/pnpm/yarn script or local-bin integration is outside the first release.
Default and explicit sources
The default source is the repository's primary checkout. Select another checkout or worktree only within the same Git repository and under the same OS user.
The paths are examples; replace them with your source worktree. The source must have a usable, compatible cache. Different tool versions, platforms, architectures, or build settings make a source incompatible. Unknown compatibility also prohibits reuse.
When running in the default primary checkout itself, CacheCow uses its cache directly without cloning it into itself. If the cache is absent, the requested build runs directly there. Worktrees of a bare repository have no primary checkout: select a usable source explicitly or use the interactive no-source build choice described in cache recovery.
Save or clear a source
Settings apply to the current worktree:
Source precedence is:
- The current invocation's
--sourceoption. - The saved per-worktree source.
- The primary checkout default.
Clearing a saved source restores default selection. Changing source selection does not replace an existing working cache. Use an explicit replacement when that is intended. CacheCow has no saved snapshot catalog or automatic publication step.