Document caveats related to colored warnings from compilers

diff --git a/MANUAL.txt b/MANUAL.txt
index a27078d536fc2fc577626bceaa72930f11ef5329..50fc574d4228fe62b55e4bf863d7b4369dc99ecb 100644 (file)
--- a/MANUAL.txt
+++ b/MANUAL.txt
@@ -987,6 +987,19 @@ Caveats
 
 * The direct mode fails to pick up new header files in some rare scenarios. See
   <<_the_direct_mode,THE DIRECT MODE>> above.
+* When run via ccache, warning messages produced by GCC 4.9 and newer will only
+  be colored when the environment variable *GCC_COLORS* is set. An alternative
+  to setting *GCC_COLORS* is to pass `-fdiagnostics-color` explicitly when
+  compiling (but then color codes will also be present when redirecting stderr
+  to a file).
+* If ccache guesses that the compiler may emit colored warnings, then a
+  compilation with stderr referring to a TTY will be considered different from
+  a compilation with a redirected stderr, thus not sharing cache entries. This
+  happens for clang by default and for GCC when *GCC_COLORS* is set as
+  mentioned above. If you want to share cache hits, you can pass
+  `-f[no-]diagnostics-color` (GCC) or `-f[no-]color-diagnostics` (clang)
+  explicitly when compiling (but then color codes will be either on or off for
+  both the TTY and the redirected case).
 
 
 Troubleshooting

diff --git a/NEWS.txt b/NEWS.txt
index f692d7af32ff4ac7632c64ccca31e0208022d7be..cbe191576252a7a31c3ba0e8736740a15b927700 100644 (file)
--- a/NEWS.txt
+++ b/NEWS.txt
@@ -37,6 +37,8 @@ New features and enhancements
 
 - Documented more pitfalls with enabling `hard_links` (`CCACHE_HARDLINK`).
 
+- Documented caveats related to colored warnings from compilers.
+
 
 Bug fixes
 ~~~~~~~~~