From: Joel Rosdahl <joel@rosdahl.net>
Date: Mon, 5 Feb 2018 20:58:55 +0000 (+0100)
Subject: Document caveats related to colored warnings from compilers
X-Git-Tag: v3.4~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=67fdd3b53c19476d33a9f74acdf02046293437ab;p=thirdparty%2Fccache.git

Document caveats related to colored warnings from compilers
---

diff --git a/MANUAL.txt b/MANUAL.txt
index a27078d53..50fc574d4 100644
--- 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 f692d7af3..cbe191576 100644
--- 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
 ~~~~~~~~~