From: Joel Rosdahl <joel@rosdahl.net>
Date: Wed, 2 Dec 2020 20:56:05 +0000 (+0100)
Subject: Improve documentation of compression levels and -X/--recompress
X-Git-Tag: v4.2~84
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=fa21e9653b4ff07be2694365b88afa2b813d76a7;p=thirdparty%2Fccache.git

Improve documentation of compression levels and -X/--recompress

Related to issue #728.
---

diff --git a/doc/MANUAL.adoc b/doc/MANUAL.adoc
index 1a860313d..58ad1f25e 100644
--- a/doc/MANUAL.adoc
+++ b/doc/MANUAL.adoc
@@ -134,8 +134,8 @@ Common options
 
 *`-X`* _LEVEL_, *`--recompress`* _LEVEL_::
 
-    Recompress the cache using compression level _LEVEL_. The level can be an
-    integer, with the same semantics as the
+    Recompress the cache to level _LEVEL_ using the Zstandard algorithm. The
+    level can be an integer, with the same semantics as the
     <<config_compression_level,*compression_level*>> configuration option), or
     the special value *uncompressed* for no compression. See
     <<_cache_compression,CACHE COMPRESSION>> for more information. This can
@@ -514,17 +514,24 @@ Semantics of *compression_level*:
     A positive value corresponds to normal Zstandard compression levels. Lower
     levels (e.g. *1*) mean faster compression but worse compression ratio.
     Higher levels (e.g. *19*) mean slower compression but better compression
-    ratio. The maximum possible value depends on the libzstd version.
-    Decompression speed is essentially the same for all levels.
+    ratio. The maximum possible value depends on the libzstd version, but at
+    least up to 19 is available for all versions. Decompression speed is
+    essentially the same for all levels. As a rule of thumb, use level 5 or
+    lower since higher levels may slow down compilations noticeably. Higher
+    levels are however useful when recompressing the cache with command line
+    option *-X/--recompress*.
 *< 0*::
     A negative value corresponds to Zstandard's “ultra-fast” compression
     levels, which are even faster than level 1 but with less good compression
     ratios. For instance, level *-3* corresponds to “--fast=3” for the *zstd*
-    command line tool.
+    command line tool. In practice, there is little use for levels lower than
+    *-5* or so.
 *0* (default)::
     The value *0* means that ccache will choose a suitable level, currently
     *1*.
 --
++
+See the http://zstd.net[Zstandard documentation] for more information.
 
 [[config_cpp_extension]] *cpp_extension* (*CCACHE_EXTENSION*)::
 
@@ -900,11 +907,11 @@ Cache compression
 -----------------
 
 Ccache will by default compress all data it puts into the cache using the
-compression algorithm Zstandard (zstd) using compression level 1. The algorithm
-is fast enough that there should be little reason to turn off compression to
-gain performance. One exception is if the cache is located on a compressed file
-system, in which case the compression performed by ccache of course is
-redundant. See the documentation for the configuration options
+compression algorithm http://zstd.net[Zstandard] (zstd) using compression level
+1. The algorithm is fast enough that there should be little reason to turn off
+compression to gain performance. One exception is if the cache is located on a
+compressed file system, in which case the compression performed by ccache of
+course is redundant. See the documentation for the configuration options
 <<config_compression,*compression*>> and
 <<config_compression_level,*compression_level*>> for more information.
 
diff --git a/src/ccache.cpp b/src/ccache.cpp
index b7c3013fa..654af6f87 100644
--- a/src/ccache.cpp
+++ b/src/ccache.cpp
@@ -119,8 +119,9 @@ Common options:
     -M, --max-size SIZE        set maximum size of cache to SIZE (use 0 for no
                                limit); available suffixes: k, M, G, T (decimal)
                                and Ki, Mi, Gi, Ti (binary); default suffix: G
-    -X, --recompress LEVEL     recompress the cache to LEVEL (integer level or
-                               "uncompressed")
+    -X, --recompress LEVEL     recompress the cache to level LEVEL (integer or
+                               "uncompressed") using the Zstandard algorithm;
+                               see "Cache compression" in the manual for details
     -o, --set-config KEY=VAL   set configuration item KEY to value VAL
     -x, --show-compression     show compression statistics
     -p, --show-config          show current configuration options in
@@ -145,7 +146,7 @@ Options for scripting or debugging:
         --print-stats          print statistics counter IDs and corresponding
                                values in machine-parsable format
 
-See also <https://ccache.dev>.
+See also the manual on <https://ccache.dev/documentation.html>.
 )";
 
 // How often (in seconds) to scan $CCACHE_DIR/tmp for left-over temporary