docs: Add warning about base_dir

See #1042.

diff --git a/doc/MANUAL.adoc b/doc/MANUAL.adoc
index 601e6c6e29727adba5e7d1e4ad19c1b578fa8297..99ffa6b97d48abecee6ce903fb3784cd32a784dc 100644 (file)
--- 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*)::