index.empy

@# -*- html -*-

@{page_id = "overview"}
@{page_title = "Compiler cache"}
@empy.include("header.empy")

<h1>Overview</h1>

<p>
  Ccache is a compiler cache. It <a href="performance.html">speeds up
  recompilation</a> by caching previous compilations and detecting when the same
  compilation is being done again. Ccache is free software, released under
  the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public License
  version 3</a> or later. See also the <a href="license.html">license page</a>.
</p>

<p>Latest release: <a href="download.html">version @(latest_version)</a></p>

<h2>News</h2>

@{
import yaml
news = list(yaml.safe_load_all(open("news.yaml")))
}@

@[for x in news[:3]]
<div class="news"><i>@(x["date"]):</i> <a href="news.html#@(x["date"])"><b>@(x["header"])</b></a></div>
@[end for]
<a href="news.html">All news</a>

<h2 style="clear: right;">Features</h2>

<ul>
  <li>
    Supports GCC, Clang, MSVC (Microsoft Visual C++) and other similar
    compilers<sup class="footnote">[1]</sup>.
    (<a href="platform-compiler-language-support.html">details</a>)
  </li>
  <li>
    Works on Linux, Windows, macOS and other Unix-like operating
    systems<sup class="footnote">[1]</sup>.
    (<a href="platform-compiler-language-support.html">details</a>)
  </li>
  <li>
    Understands C, C++, assembler, CUDA,
    Objective-C<sup class="footnote">[1]</sup> and
    Objective-C++<sup class="footnote">[1]</sup>.
    (<a href="platform-compiler-language-support.html">details</a>)
  </li>
  <li>
    Supports remote caching using custom storage backends that can be adapted to
    any remote storage protocol. (<a href="storage-helpers.html">details</a>)
  </li>
  <li>
    Supports fast "direct" and "depend" modes that avoid running the
    preprocessor.
    (<a href="manual/@(latest_version).html#_how_ccache_works">details</a>)
  </li>
  <li>
    Uses an inode cache to avoid having to hash the same header files repeatedly
    during a build (on supported OSes and file systems).
    (<a href="manual/@(latest_version).html#config_inode_cache">details</a>)
  </li>
  <li>Supports compression using <a href="http://zstd.net">Zstandard</a>.</li>
  <li>
    Uses the fast and secure
    <a href="https://github.com/BLAKE3-team/BLAKE3">BLAKE3</a> algorithm for
    the main input hash.
  </li>
  <li>
    Checksums cache content using <a href="https://xxhash.com">XXH3</a> to
    detect data corruption.
  </li>
  <li>
    Keeps statistics on hits and misses.
    (<a href="manual/@(latest_version).html#_cache_statistics">details</a>)
  </li>
  <li>
    Automatic cache size management.
    (<a href="manual/@(latest_version).html#_cache_size_management">details</a>)
  </li>
  <li>
    Easy installation.
    (<a href="manual/@(latest_version).html#_run_modes">details</a>)
  </li>
  <li>
    Low overhead. (<a href="performance.html">details</a>)
  </li>
  <li>
    Support for rewriting absolute paths to relative paths to improve the cache
    hit ratio.
    (<a href="manual/@(latest_version).html#_compiling_in_different_directories">details</a>)
  </li>
  <li>
    Optionally uses file cloning (also known as “reflinks”) where possible to
    avoid copies.
  </li>
  <li>Optionally uses hard links where possible to avoid copies.</li>
</ul>

<p>
  <sup>[1]</sup> Might have limited support &mdash; see
  <a href="platform-compiler-language-support.html">supported platforms,
  compilers and languages</a>.
</p>

<h2>Limitations</h2>

<ul>
  <li>
    Only knows how to cache the compilation of a single file. Other types of
    compilations (multi-file compilation, linking, etc.) will silently fall back
    to running the real compiler.
  </li>
  <li>
    Some compiler flags are not supported. If such a flag is detected, ccache
    will silently fall back to running the real compiler.
  </li>
  <li>
    The fastest mode (the "direct mode") has a corner case that can result in
    false-positive cache hits. This and other minor limitations are listed
    under <a href="manual/@(latest_version).html#_caveats">caveats</a> in the
    manual.
  </li>
</ul>

<h2>Why bother?</h2>

<p>If you ever run <code>make clean; make</code>, you can probably benefit from
ccache. It is common for developers to do a clean build of a project for a
variety of reasons, and this discards the results of your previous
compilations. By using ccache, recompilation goes much faster.</p>

<p>Another reason to use ccache is that the same cache is used for builds in
different directories. If you have several versions or branches of a project
stored in different directories, many of the object files in a build directory
can often be taken from the cache even if they were compiled for another
version or branch.</p>

<p>A third scenario is using ccache to speed up clean builds performed by
servers or build farms that regularly verify that the code builds.</p>

<p>You can also share the cache between users, which can be very useful on
shared compilation servers.</p>

<h2>Is it safe?</h2>

<p>The most important aspect of a compiler cache is to always produce exactly
the same output that the real compiler would produce. This includes providing
exactly the same object files and emitting exactly the same compiler warnings
as if you invoked the real compiler. The only way you should be able to tell
that you are using ccache is the speed.</p>

<p>Ccache strives to provide these guarantees. However:</p>

<ul>
  <li>
    Compilers are moving targets. Newer compiler versions may, and often do,
    introduce features that ccache can't anticipate. In some cases it's also
    very hard for ccache to handle compiler behavior correctly, especially in a
    way that is backward-compatible with legacy compilers.
  </li>
  <li>
    The fastest mode (the "direct mode") has a corner case that can result in
    false-positive cache hits. This and other minor limitations are listed under
    <a href="manual/@(latest_version).html#_caveats">caveats</a> in the manual.
  </li>
</ul>

<p>If you experience any bugs or undocumented limitations, please
<a href="bugs.html">report them</a>.</p>

@empy.include("footer.empy")