From: Jean-Paul Pelteret <jppelteret@gmail.com>
Date: Sat, 25 Apr 2020 13:34:33 +0000 (+0200)
Subject: Add docs on how to use CCache
X-Git-Tag: v9.3.0-rc1~1598^2
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=52fe2cdb1b1f3b129f0bde80558b1a5e7b5a0b7f;p=dealii.git

Add docs on how to use CCache
---

diff --git a/doc/users/cmake_dealii.html b/doc/users/cmake_dealii.html
index 3a8630fd72..cb9e1de1d2 100644
--- a/doc/users/cmake_dealii.html
+++ b/doc/users/cmake_dealii.html
@@ -49,6 +49,7 @@
 	    <li><a href="#configurecomp">Component selection</a></li>
 	    <li><a href="#configurebuild">Build configuration</a></li>
 	    <li><a href="#compiler">Selecting a compiler</a></li>
+	    <li><a href="#compileccache">Compiling using Ccache</a></li>
 	    <li><a href="#configureinstall">Installation</a></li>
 	  </ol>
 	</li>
@@ -814,7 +815,7 @@ cmake -DLAPACK_FOUND=true \
           linkage of executables. Enabling this option forces
           <code>BUILD_SHARED_LIBS=OFF</code> and
           <code>DEAL_II_PREFER_STATIC_LIBS=ON</code>.
-          
+
         <li>
           <code>CMAKE_INSTALL_RPATH_USE_LINK_PATH</code>: If set
           (default), the <acronym>deal.II</acronym> library will be
@@ -894,6 +895,49 @@ cmake -DDEAL_II_CXX_FLAGS="-Wno-sign-compare" &lt;...&gt;
     </p>
 
 
+    <a name="compileccache"></a>
+    <h3> Compiling using Ccache </h3>
+    <p>
+      <a href="https://ccache.dev/">Ccache</a> is a compiler caching tool. It
+      accelerates recompilation by caching previously executed compilations
+      and subsequently detecting when the same compilation is being performed
+      again.
+    </p>
+
+    <p>
+      It is possible for the library to be built using the Ccache tool.
+      This may be useful for those who frequently rebuild the library, as it
+      caches the output of the compilation (the C++ components, at least).
+      The next time that the library is built, if the compilation objects remain
+      the same then rebuilding them can be avoided as the results will be taken
+      from directly the cache. Anecdotally, Ccache is not well suited to
+      everybody's workflow, so it may take some experimentation to determine if
+      it's effective and helpful, or offers no particular gain to you.
+    </p>
+
+    <p>
+      Building with Ccache can be enabled directly via the command line.
+      When using a version of CMake that is greater or equal to 3.4, then using
+      Ccache is easy. Passing the configure-time argument
+<pre class="cmake">
+  -DCXX_COMPILER_LAUNCHER="ccache"
+</pre>
+      to Cmake ensures that Ccache is invoked whenever C++ code is compiled.
+    </p>
+
+    <p>
+      For older versions of CMake, Ccache may be invoked by prefixing the
+      compiler commands passed to CMake by environment or configure-time
+      variables. For example, if building using GCC then
+<pre class="cmake">
+  -DCMAKE_C_COMPILER="ccache gcc" -DCMAKE_CXX_COMPILER="ccache g++"
+</pre>
+      would indicate that ccache should invoke the GCC compilers to build deal.II.
+      Ccache itself is invoked when calling <code>make</code> or
+      <code>ninja</code>.
+    </p>
+
+
     <a name="configureinstall"></a>
     <h3> Installation </h3>