docs/manual/ccache-support.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[ccache]]
   5 ==== Using +ccache+ in Buildroot
   6
   7 http://ccache.samba.org[ccache] is a compiler cache. It stores the
   8 object files resulting from each compilation process, and is able to
   9 skip future compilation of the same source file (with same compiler
  10 and same arguments) by using the pre-existing object files. When doing
  11 almost identical builds from scratch a number of times, it can nicely
  12 speed up the build process.
  13
  14 +ccache+ support is integrated in Buildroot. You just have to enable
  15 +Enable compiler cache+ in +Build options+. This will automatically
  16 build +ccache+ and use it for every host and target compilation.
  17
  18 The cache is located in +$HOME/.buildroot-ccache+. It is stored
  19 outside of Buildroot output directory so that it can be shared by
  20 separate Buildroot builds. If you want to get rid of the cache, simply
  21 remove this directory.
  22
  23 You can get statistics on the cache (its size, number of hits,
  24 misses, etc.) by running +make ccache-stats+.
  25
  26 The make target +ccache-options+ and the +CCACHE_OPTIONS+ variable
  27 provide more generic access to the ccache. For example
  28
  29 -----------------
  30 # set cache limit size
  31 make CCACHE_OPTIONS="--max-size=5G" ccache-options
  32
  33 # zero statistics counters
  34 make CCACHE_OPTIONS="--zero-stats" ccache-options
  35 -----------------
  36
  37 +ccache+ makes a hash of the source files and of the compiler options.
  38 If a compiler option is different, the cached object file will not be
  39 used. Many compiler options, however, contain an absolute path to the
  40 staging directory. Because of this, building in a different output
  41 directory would lead to many cache misses.
  42
  43 To avoid this issue, buildroot has the +Use relative paths+ option
  44 (+BR2_CCACHE_USE_BASEDIR+). This will rewrite all absolute paths that
  45 point inside the output directory into relative paths. Thus, changing
  46 the output directory no longer leads to cache misses.
  47
  48 A disadvantage of the relative paths is that they also end up to be
  49 relative paths in the object file. Therefore, for example, the debugger
  50 will no longer find the file, unless you cd to the output directory
  51 first.
  52
  53 See https://ccache.samba.org/manual.html#_compiling_in_different_directories[the
  54 ccache manual's section on "Compiling in different directories"] for
  55 more details about this rewriting of absolute paths.