1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc:
3
4[[ccache]]
5==== Using +ccache+ in Buildroot
6
7http://ccache.samba.org[ccache] is a compiler cache. It stores the
8object files resulting from each compilation process, and is able to
9skip future compilation of the same source file (with same compiler
10and same arguments) by using the pre-existing object files. When doing
11almost identical builds from scratch a number of times, it can nicely
12speed 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
16build +ccache+ and use it for every host and target compilation.
17
18The cache is located in the directory defined by the +BR2_CCACHE_DIR+
19configuration option, which defaults to
20+$HOME/.buildroot-ccache+. This default location is outside of
21Buildroot output directory so that it can be shared by separate
22Buildroot builds. If you want to get rid of the cache, simply remove
23this directory.
24
25You can get statistics on the cache (its size, number of hits,
26misses, etc.) by running +make ccache-stats+.
27
28The make target +ccache-options+ and the +CCACHE_OPTIONS+ variable
29provide more generic access to the ccache. For example
30
31-----------------
32# set cache limit size
33make CCACHE_OPTIONS="--max-size=5G" ccache-options
34
35# zero statistics counters
36make CCACHE_OPTIONS="--zero-stats" ccache-options
37-----------------
38
39+ccache+ makes a hash of the source files and of the compiler options.
40If a compiler option is different, the cached object file will not be
41used. Many compiler options, however, contain an absolute path to the
42staging directory. Because of this, building in a different output
43directory would lead to many cache misses.
44
45To avoid this issue, buildroot has the +Use relative paths+ option
46(+BR2_CCACHE_USE_BASEDIR+). This will rewrite all absolute paths that
47point inside the output directory into relative paths. Thus, changing
48the output directory no longer leads to cache misses.
49
50A disadvantage of the relative paths is that they also end up to be
51relative paths in the object file. Therefore, for example, the debugger
52will no longer find the file, unless you cd to the output directory
53first.
54
55See https://ccache.samba.org/manual.html#_compiling_in_different_directories[the
56ccache manual's section on "Compiling in different directories"] for
57more details about this rewriting of absolute paths.
58
59When +ccache+ is enabled in Buildroot using the +BR2_CCACHE=y+ option:
60
61* +ccache+ is used during the Buildroot build itself
62
63* +ccache+ is not used when building outside of Buildroot, for example
64  when directly calling the cross-compiler or using the SDK
65
66One can override this behavior using the +BR2_USE_CCACHE+ environment
67variable: when set to +1+, usage of ccache is enabled (default during
68the Buildroot build), when unset or set to a value different from +1+,
69usage of ccache is disabled.
70