From ddb73c654c97cfdce4d947f650edb8f85a7e8479 Mon Sep 17 00:00:00 2001 From: Joel Rosdahl Date: Mon, 5 Feb 2018 19:11:02 +0100 Subject: [PATCH] Document more pitfalls with hard links --- MANUAL.txt | 25 +++++++++++++++++-------- NEWS.txt | 2 ++ 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/MANUAL.txt b/MANUAL.txt index 0d37a42e2..a27078d53 100644 --- a/MANUAL.txt +++ b/MANUAL.txt @@ -43,7 +43,6 @@ Features * Can cache compilations that generate warnings. * Easy installation. * Low overhead. -* Optionally uses hard links where possible to avoid copies. * Optionally compresses files in the cache to reduce disk space. @@ -370,13 +369,23 @@ WRAPPERS>>. *hard_link* (*CCACHE_HARDLINK* or *CCACHE_NOHARDLINK*, see <<_boolean_values,Boolean values>> above):: If true, ccache will attempt to use hard links from the cache directory - when creating the compiler output rather than using a file copy. Using hard - links may be slightly faster in some situations, but can confuse programs - like ``make'' that rely on modification times. Another thing to keep in - mind is that if the resulting object file is modified in any way, this - corrupts the cached object file as well. Hard links are never made for - compressed cache files. This means that you should not enable compression - if you want to use hard links. The default is false. + when creating the compiler output rather than using a file copy. Hard links + are never made for compressed cache files. This means that you should not + enable compression if you want to use hard links. The default is false. ++ +WARNING: Do not enable this option unless you are aware of the consequences. +Using hard links may be slightly faster in some situations, but there are +several pitfalls since the resulting object file will share i-node with the +cached object file: ++ +1. If the resulting object file is modified in any way, the cached object file + will be modified as well. For instance, if you run *strip object.o* or *echo + >object.o*, you will corrupt the cache. +2. Programs that rely on modification times (like ``make'') can be confused + since ccache updates the cached files' modification times as part of the + automatic cache size management. This will affect object files in the build + tree as well, which can retrigger the linking step even though nothing + really has changed. *hash_dir* (*CCACHE_HASHDIR* or *CCACHE_NOHASHDIR*, see <<_boolean_values,Boolean values>> above):: diff --git a/NEWS.txt b/NEWS.txt index 12d589730..f692d7af3 100644 --- a/NEWS.txt +++ b/NEWS.txt @@ -35,6 +35,8 @@ New features and enhancements extension is non-standard. This should make it easier to use EDG-based compilers (e.g. GHS) which don't understand `-MQ`. +- Documented more pitfalls with enabling `hard_links` (`CCACHE_HARDLINK`). + Bug fixes ~~~~~~~~~ -- 2.47.2