From: Joel Rosdahl <joel@rosdahl.net>
Date: Sun, 8 May 2022 14:31:37 +0000 (+0200)
Subject: docs: Add warning about base_dir
X-Git-Tag: v4.6.1~15
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e15af963082f39a0595a7d623da2316b2fe3b282;p=thirdparty%2Fccache.git

docs: Add warning about base_dir

See #1042.
---

diff --git a/doc/MANUAL.adoc b/doc/MANUAL.adoc
index 601e6c6e2..99ffa6b97 100644
--- a/doc/MANUAL.adoc
+++ b/doc/MANUAL.adoc
@@ -411,6 +411,12 @@ differ. With *base_dir* set to `/` there will be a cache miss since the
 relative path to `/usr/include/example` will be different. With *base_dir* set
 to `/home/bob/stuff/project1` there will a cache miss since the path to
 project2 will be a different absolute path.
++
+WARNING: Rewriting absolute paths to relative is kind of a brittle hack. It
+works OK in many cases, but there might be cases where things break. One known
+issue is that absolute paths are not reproduced in dependency files, which can
+mess up dependency detection in tools like Make and Ninja. If possible, use
+relative paths in the first place instead instead of using *base_dir*.
 
 [#config_cache_dir]
 *cache_dir* (*CCACHE_DIR*)::