From: Joel Rosdahl <joel@rosdahl.net>
Date: Fri, 7 Sep 2012 18:30:02 +0000 (+0200)
Subject: Update manual on why the direct mode is off by default
X-Git-Tag: v3.2~98
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=568ca99324970bba4a498a32ef14b535f596a118;p=thirdparty%2Fccache.git

Update manual on why the direct mode is off by default
---

diff --git a/MANUAL.txt b/MANUAL.txt
index 506c1c572..05b786416 100644
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -332,7 +332,8 @@ WRAPPERS>>.
 
 *direct_mode* (*CCACHE_DIRECT*) [boolean]::
 
-    If true, the direct mode will be used. The default is true.
+    If true, the direct mode will be used. The default is false. See
+    <<_the_direct_mode,THE DIRECT MODE>>.
 
 *disable* (*CCACHE_DISABLE*) [boolean]::
 
@@ -548,9 +549,17 @@ files that were read. The paths and hash sums of those include files are then
 stored in the manifest along with information about the produced compilation
 result.
 
+There is a catch with the direct mode: header files that were used by the
+compiler are recorded, but header files that were *not* used, but would have
+been used if they existed, are not. So, when ccache checks if a result can be
+taken from the cache, it currently can't check if the existence of a new header
+file should invalidate the result. This is why the direct mode is off by
+default. In practice, the direct mode is safe to use in the absolute majority
+of cases.
+
 The direct mode will be disabled if any of the following holds:
 
-* the configuration setting *direct_mode* is false
+* the configuration setting *direct_mode* is false (which is the default)
 * a modification time of one of the include files is too new (needed to avoid a
   race condition)
 * the unifier is enabled (the configuration setting *unify* is true)