Add SCCACHE_BASEDIRS support

Cargo.toml

@@ -101,6 +101,7 @@ tokio-serde = "0.8"
 tokio-util = { version = "0.7", features = ["codec", "io"] }
 toml = "0.8"
 tower-service = "0.3"
+typed-path = "0.12.0"
 url = { version = "2", optional = true }
 uuid = { version = "1.9", features = ["v4"] }
 walkdir = "2"

README.md

@@ -321,12 +321,49 @@ This is most useful when using sccache for Rust compilation, as rustc supports u
 
 ---
 
+Normalizing Paths with `SCCACHE_BASEDIRS`
+-----------------------------------------
+
+By default, sccache requires absolute paths to match for cache hits. To enable cache sharing across different build directories, you can set `SCCACHE_BASEDIRS` to strip a base directory from paths before hashing:
+
+```bash
+export SCCACHE_BASEDIRS=/home/user/project
+```
+
+You can also specify multiple base directories by separating them by `;` on Windows hosts and by `:` on any other operating system. When multiple directories are provided, the longest matching prefix is used:
+
+```bash
+export SCCACHE_BASEDIRS="/home/user/project:/home/user/workspace"
+```
+
+Path matching is **case-insensitive** on Windows and **case-sensitive** on other operating systems.
+
+This is similar to ccache's `CCACHE_BASEDIR` and helps when:
+* Building the same project from different directories
+* Sharing cache between CI jobs with different checkout paths
+* Multiple developers working with different username paths
+* Working with multiple project checkouts simultaneously
+
+**Note:** Only absolute paths are supported. Relative paths will prevent server from starting.
+
+You can also configure this in the sccache config file:
+
+```toml
+# Single directory
+basedirs = ["/home/user/project"]
+
+# Or multiple directories
+basedirs = ["/home/user/project", "/home/user/workspace"]
+```
+
+---
+
 Known Caveats
 -------------
 
 ### General
 
-* Absolute paths to files must match to get a cache hit. This means that even if you are using a shared cache, everyone will have to build at the same absolute path (i.e. not in `$HOME`) in order to benefit each other. In Rust this includes the source for third party crates which are stored in `$HOME/.cargo/registry/cache` by default.
+* By default, absolute paths to files must match to get a cache hit. To work around this, use `SCCACHE_BASEDIRS` (see above) to normalize paths before hashing.
 
 ### Rust
 

docs/Configuration.md

@@ -6,6 +6,26 @@
 # If specified, wait this long for the server to start up.
 server_startup_timeout_ms = 10000
 
+# Base directories to strip from source paths during cache key
+# computation.
+#
+# Similar to ccache's CCACHE_BASEDIR, but supports multiple paths.
+#
+# 'basedirs' enables cache hits across different absolute root
+# paths when compiling the same source code, such as between
+# parallel checkouts of the same project, Git worktrees, or different
+# users in a shared environment.
+# When multiple matching paths are provided, the longest prefix
+# is used.
+#
+# Path matching is case-insensitive on Windows and case-sensitive on other OSes.
+#
+# Example:
+#   basedir = ["/home/user/project"] results in the path prefix rewrite:
+#   "/home/user/project/src/main.c" -> "src/main.c"
+basedirs = ["/home/user/project"]
+# basedirs = ["/home/user/project", "/home/user/workspace"]
+
 [dist]
 # where to find the scheduler
 scheduler_url = "http://1.2.3.4:10600"
@@ -139,6 +159,7 @@ Note that some env variables may need sccache server restart to take effect.
 
 * `SCCACHE_ALLOW_CORE_DUMPS` to enable core dumps by the server
 * `SCCACHE_CONF` configuration file path
+* `SCCACHE_BASEDIRS` base directory (or directories) to strip from paths for cache key computation. This is similar to ccache's `CCACHE_BASEDIR` and enables cache hits across different absolute paths when compiling the same source code. Multiple directories can be separated by `;` on Windows hosts and by `:` on any other operating system. When multiple directories are specified, the longest matching prefix is used. Path matching is **case-insensitive** on Windows and **case-sensitive** on other operating systems. Environment variable takes precedence over file configuration. Only absolute paths are supported; relative paths will cause an error and prevent the server from start.
 * `SCCACHE_CACHED_CONF`
 * `SCCACHE_IDLE_TIMEOUT` how long the local daemon process waits for more client requests before exiting, in seconds. Set to `0` to run sccache permanently
 * `SCCACHE_STARTUP_NOTIFY` specify a path to a socket which will be used for server completion notification