Update manual on why the direct mode is off by default

diff --git a/MANUAL.txt b/MANUAL.txt
index 506c1c5725f98830b5a06a40649f0f1e58d94f89..05b7864164dfef7a702b633c8fe27ffd62be19d9 100644 (file)
--- 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)