doc/INSTALL.md

   1 Ccache installation
   2 ===================
   3
   4 Prerequisites
   5 -------------
   6
   7 To build ccache you need:
   8
   9 - CMake 3.15 or newer.
  10 - A C++17 compiler. See [Supported platforms, compilers and
  11   languages](https://ccache.dev/platform-compiler-language-support.html) for
  12   details.
  13 - A C99 compiler.
  14 - [libzstd](http://www.zstd.net). If you don't have libzstd installed and can't
  15   or don't want to install it in a standard system location, it will be
  16   automatically downloaded, built and linked statically as part of the build
  17   process. To disable this, pass `-DZSTD_FROM_INTERNET=OFF` to `cmake`, or pass
  18   `-DZSTD_FROM_INTERNET=ON` to force downloading. You can also install zstd in a
  19   custom path and pass `-DCMAKE_PREFIX_PATH=/some/custom/path` to `cmake`.
  20
  21   To link libzstd statically (and you have a static libzstd available), pass
  22   `-DSTATIC_LINK=ON` to `cmake`. This is the default on Windows. Alternatively,
  23   use `-DZSTD_LIBRARY=/path/to/libzstd.a`.
  24
  25 Optional:
  26
  27 - [hiredis](https://github.com/redis/hiredis) for the Redis storage backend. If
  28   you don't have libhiredis installed and can't or don't want to install it in a
  29   standard system location, it will be automatically downloaded, built and
  30   linked statically as part of the build process. To disable this, pass
  31   `-DHIREDIS_FROM_INTERNET=OFF` to `cmake`, or pass `-DHIREDIS_FROM_INTERNET=ON`
  32   to force downloading.. You can also install hiredis in a custom path and pass
  33   `-DCMAKE_PREFIX_PATH=/some/custom/path` to `cmake`.
  34
  35   To link libhiredis statically (and you have a static libhiredis available),
  36   pass `-DSTATIC_LINK=ON` to `cmake`. This is the default on Windows.
  37   Alternatively, use `-DHIREDIS_LIBRARY=/path/to/libhiredis.a`.
  38 - GNU Bourne Again SHell (bash) for tests.
  39 - [Asciidoctor](https://asciidoctor.org) to build the HTML documentation.
  40 - [Python](https://www.python.org) to debug and run the performance test suite.
  41
  42 Reference configurations:
  43
  44 - See [CI configurations](../.github/workflows/build.yaml) for a selection of
  45   regularly tested build setups, including cross-compiling and explicit
  46   dependencies required in Debian/Ubuntu environment.
  47
  48 Installation
  49 ------------
  50
  51 Here is the typical way to build and install ccache:
  52
  53 ```bash
  54 mkdir build
  55 cd build
  56 cmake -DCMAKE_BUILD_TYPE=Release ..
  57 make
  58 make install
  59 ```
  60
  61 You can set the installation directory to e.g. `/usr` by adding
  62 `-DCMAKE_INSTALL_PREFIX=/usr` to the `cmake` command. You can set the directory
  63 where the system configuration file should be located to e.g. `/etc` by adding
  64 `-DCMAKE_INSTALL_SYSCONFDIR=/etc`.
  65
  66 There are two different ways to use ccache to cache a compilation:
  67
  68 1. Prefix your compilation command with `ccache`. This method is most convenient
  69    if you just want to try out ccache or wish to use it for some specific
  70    projects.
  71 2. Let ccache masquerade as the compiler. This method is most useful when you
  72    wish to use ccache for all your compilations. To do this, create a symbolic
  73    link to ccache named as the compiler. For example, here is how to set up
  74    ccache to masquerade as `gcc` and `g++`:
  75
  76    ```bash
  77    cp ccache /usr/local/bin/
  78    ln -s ccache /usr/local/bin/gcc
  79    ln -s ccache /usr/local/bin/g++
  80    ```
  81
  82    On platforms that don't support symbolic links you can simply copy ccache to the
  83    compiler name instead for a similar effect:
  84
  85    ```bash
  86    cp ccache /usr/local/bin/gcc
  87    cp ccache /usr/local/bin/g++
  88    ```
  89
  90    And so forth. This will work as long as the directory with symbolic links or
  91    ccache copies comes before the directory with the compiler (typically
  92    `/usr/bin`) in `PATH`.