]> git.ipfire.org Git - thirdparty/ccache.git/commit
feat: Add support for remote storage helpers 1672/head
authorJoel Rosdahl <joel@rosdahl.net>
Sun, 18 Jan 2026 13:48:06 +0000 (14:48 +0100)
committerJoel Rosdahl <joel@rosdahl.net>
Sun, 25 Jan 2026 08:41:34 +0000 (09:41 +0100)
commit7f40418930cae9f86f5e80fd92b6d79baf621d34
treeeba1ddad69192a1c483a9e08d3316d0160bd55e0
parentab427b623ca208a46d0e71f39c12e79b104dd848
feat: Add support for remote storage helpers

This commit adds support for communicating with a remote storage server
using a long-lived local helper process, started by ccache on demand.
The helper process can keep connections alive (thus amortizing the
session setup cost), and knowledge about remote storage protocols can be
kept out of the ccache code base, making it possible to develop and
release support for different storage server protocols independently.

The storage helper listens to a Unix-domain socket on POSIX systems and
a named pipe on Windows systems. Ccache communicates with it using a
custom IPC protocol, described in doc/remote_storage_helper_spec.md. The
helper is named ccache-storage-<scheme> (e.g. ccache-storage-https) and
can be placed in $PATH, next to the ccache executable or in ccache's
libexec directory. Storage helpers time terminate after a while on
inactivity.

Built-in support for http and redis is kept for now but will likely be
removed in a future ccache release.

- The syntax of the remote_storage/CCACHE_REMOTE_STORAGE configuration
  option has been improved (in a backward compatible way): What used to
  be called "attributes" are now split into "properties" and "custom
  attributes", where properties are things that ccache knows about and
  acts on (e.g. read-only and shards) while attributes are custom
  key-value pairs sent to the helper without ccache knowing or caring
  about them. Syntax: A property is "key=value", a custom attribute is
  "@key=value".
- Properties/attributes are now separated by whitespace instead of pipe
  characters.

New remote storage properties:

- data-timeout: Timeout for send/receive data transfer. Resets whenever
  data is received or can be sent. Default: 1s.
- request-timeout: Timeout for the whole request. Default: 10s.
- idle-timeout: Timeout for the helper process to wait before exiting
  after client inactivity (0s: stay up indefinitely). Default: 10m.
- helper: Override which storage helper to spawn (either a filename or a
  full path). This is mainly useful when developing or testing new
  helpers.

The new command line option "--stop-storage-helpers" can be used to ask
spawned storage helpers to stop immediately.

A new "libexec_dirs" configuration option is available for overriding
the default libexec determined at build time.
30 files changed:
ci/prepare-release
cmake/GenerateConfigurationFile.cmake
cmake/config.h.in
doc/manual.adoc
misc/Makefile.posix-binary-release
misc/patch-binary.py [new file with mode: 0755]
src/ccache/ccache.cpp
src/ccache/config.cpp
src/ccache/config.hpp
src/ccache/context.cpp
src/ccache/context.hpp
src/ccache/core/mainoptions.cpp
src/ccache/storage/remote/CMakeLists.txt
src/ccache/storage/remote/filestorage.cpp
src/ccache/storage/remote/helper.cpp [new file with mode: 0644]
src/ccache/storage/remote/helper.hpp [new file with mode: 0644]
src/ccache/storage/remote/httpstorage.cpp
src/ccache/storage/remote/httpstorage.hpp
src/ccache/storage/remote/redisstorage.cpp
src/ccache/storage/remote/remotestorage.cpp
src/ccache/storage/remote/remotestorage.hpp
src/ccache/storage/storage.cpp
src/ccache/storage/storage.hpp
test/CMakeLists.txt
test/run
test/suites/remote_file.bash
test/suites/remote_helper.bash [new file with mode: 0644]
test/suites/remote_http.bash
test/suites/remote_url.bash
unittest/test_config.cpp