Deprecate `IREE_ENABLE_CCACHE` option (#11283)
This setting uses `RULE_LAUNCH_COMPILE` which is discouraged:
https://cmake.org/cmake/help/latest/prop_gbl/RULE_LAUNCH_COMPILE.html.
It's also unnecessary. As of CMake 3.4, the
`CMAKE_<LANG>_COMPILER_LAUNCHER` can be used to set the compiler
launcher per language. They can be set as a configuration option or via
an environment variable. There's really no reason for us to have a
project-specific configuration for this.
While I was here, I made it an error if `IREE_ENABLE_CCACHE` is set and
`ccache` is not found. This is an easy case where we can tell people to
stop using it :-)
See some discussion in https://github.com/iree-org/iree/pull/3689
diff --git a/CMakeLists.txt b/CMakeLists.txt
index d469847..696c991 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -288,12 +288,20 @@
endif()
endif()
-option(IREE_ENABLE_CCACHE "Use ccache if installed to speed up rebuilds." OFF)
+option(IREE_ENABLE_CCACHE
+ "[DEPRECATED: Use CMAKE_<LANG>_COMPILER_LAUNCHER configure options or environment variables instead.] Use ccache if installed."
+ OFF)
if(IREE_ENABLE_CCACHE)
+ message(WARNING
+ "IREE_ENABLE_CCACHE is deprecated. Use CMAKE_<LANG>_COMPILER_LAUNCHER"
+ " configure options or environment variables instead.")
find_program(CCACHE_PROGRAM ccache)
if(CCACHE_PROGRAM)
set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE "${CCACHE_PROGRAM}")
+ else()
+ message(SEND_ERROR
+ "IREE_ENABLE_CCACHE was set, but executable `ccache` was not found.")
endif()
endif()
diff --git a/build_tools/cmake/build_all.sh b/build_tools/cmake/build_all.sh
index 2c72f34..4188ed6 100755
--- a/build_tools/cmake/build_all.sh
+++ b/build_tools/cmake/build_all.sh
@@ -17,7 +17,6 @@
BUILD_DIR="${1:-${IREE_BUILD_DIR:-build}}"
INSTALL_DIR="${IREE_INSTALL_DIR:-${BUILD_DIR}/install}"
IREE_ENABLE_ASSERTIONS="${IREE_ENABLE_ASSERTIONS:-ON}"
-IREE_ENABLE_CCACHE="${IREE_ENABLE_CCACHE:-OFF}"
IREE_PYTHON3_EXECUTABLE="${IREE_PYTHON3_EXECUTABLE:-$(which python3)}"
"$CMAKE_BIN" --version
@@ -37,7 +36,6 @@
"-DCMAKE_BUILD_TYPE=RelWithDebInfo"
"-DCMAKE_INSTALL_PREFIX=$(realpath ${INSTALL_DIR})"
"-DIREE_ENABLE_ASSERTIONS=${IREE_ENABLE_ASSERTIONS}"
- "-DIREE_ENABLE_CCACHE=${IREE_ENABLE_CCACHE}"
# Use `lld` for faster linking.
"-DIREE_ENABLE_LLD=ON"
diff --git a/build_tools/cmake/build_and_test_asan.sh b/build_tools/cmake/build_and_test_asan.sh
index 98f791a..30b7b49 100755
--- a/build_tools/cmake/build_and_test_asan.sh
+++ b/build_tools/cmake/build_and_test_asan.sh
@@ -29,7 +29,6 @@
CMAKE_BIN=${CMAKE_BIN:-$(which cmake)}
BUILD_DIR="${1:-${IREE_ASAN_BUILD_DIR:-build-asan}}"
IREE_ENABLE_ASSERTIONS="${IREE_ENABLE_ASSERTIONS:-ON}"
-IREE_ENABLE_CCACHE="${IREE_ENABLE_CCACHE:-OFF}"
"$CMAKE_BIN" --version
ninja --version
@@ -51,7 +50,6 @@
"-DIREE_BUILD_MICROBENCHMARKS=ON"
"-DIREE_ENABLE_ASSERTIONS=${IREE_ENABLE_ASSERTIONS}"
- "-DIREE_ENABLE_CCACHE=${IREE_ENABLE_CCACHE}"
# Enable CUDA compiler and runtime builds unconditionally. Our CI images all
# have enough deps to at least build CUDA support and compile CUDA binaries
diff --git a/docs/developers/debugging/releases.md b/docs/developers/debugging/releases.md
index e9ef4c3..ee505bb 100644
--- a/docs/developers/debugging/releases.md
+++ b/docs/developers/debugging/releases.md
@@ -70,7 +70,7 @@
ln -s /usr/bin/llvm-symbolizer-9.0 /usr/bin/llvm-symbolizer
# You can manipulate cmake flags. These may get you a better debug experience.
-cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DIREE_ENABLE_ASAN=ON -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=gold -DIREE_ENABLE_CCACHE=ON .
+cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DIREE_ENABLE_ASAN=ON -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=gold -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache .
ninja
diff --git a/docs/developers/developing_iree/ccache.md b/docs/developers/developing_iree/ccache.md
index 4d9566f..b7e2ca2 100644
--- a/docs/developers/developing_iree/ccache.md
+++ b/docs/developers/developing_iree/ccache.md
@@ -3,6 +3,7 @@
[`ccache`](https://ccache.dev/) is a compilation cache. In principle, just
prepending compiler invocations with `ccache` is all one needs to enable it,
e.g.
+
```shell
ccache clang foo.c -c -o foo.o
```
@@ -10,7 +11,8 @@
`foo.o`. The next invocation then skips executing `clang` altogether.
When the cache is hit, the speedup is such that the "compilation" becomes
-essentially free. However, `ccache` only caches compilation, [not linking](https://stackoverflow.com/a/29828811).
+essentially free. However, `ccache` only caches compilation,
+[not linking](https://stackoverflow.com/a/29828811).
Here a few scenarios where `ccache` helps:
* Incremental rebuilds. While `cmake` always tries to avoid unnecessary work in
@@ -29,6 +31,7 @@
`ccache` is available on most platforms. On Debian-based Linux distributions,
do:
+
```shell
sudo apt install ccache
```
@@ -36,6 +39,7 @@
The one `ccache` setting that you probably need to configure is the maximum
cache size. The default `5G` is too small for our purposes. To set the cache max
size, do this once:
+
```shell
ccache --max-size=20G
```
@@ -48,30 +52,22 @@
## Telling CMake to use `ccache`
-In the initial CMake configuration step, set the `IREE_ENABLE_CCACHE` and
-`LLVM_CCACHE_BUILD` options, like this:
-```shell
-cmake -G Ninja \
- -DIREE_ENABLE_CCACHE=ON \
- -DLLVM_CCACHE_BUILD=ON \
- ... other options as usual
-```
+Use the CMake
+[COMPILER_LAUNCHER functionality](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER_LAUNCHER.html)
+by setting `CMAKE_C_COMPILER_LAUNCHER=ccache` and
+`CMAKE_CXX_COMPILER_LAUNCHER=ccache` in your
Notes:
-* This approach only works with the `Ninja` and `Makefile` generators (`cmake
- -G` flag). When using other generators, another approach is needed, based on
- wrapping the compiler in a script that prepends `ccache`. See this
+* This approach only works with the `Ninja` and `Makefile` generators
+ (`cmake -G` flag). When using other generators, another approach is needed,
+ based on wrapping the compiler in a script that prepends `ccache`. See this
[article](https://crascit.com/2016/04/09/using-ccache-with-cmake/).
-* We do need two separate options `IREE_ENABLE_CCACHE` and `LLVM_CCACHE_BUILD`,
- because of how CMake leaves it up to each project to define how to control the
- use of `ccache`, and `llvm-project` is a `third_party/` project in IREE. Note
- that most of the compilation time is spent in `llvm-project`, so
- `LLVM_CCACHE_BUILD` is the most important flag here.
## Ensuring that `ccache` is used and monitoring cache hits
The `ccache -s` command dumps statistics, including a cache hit count and ratio.
It's convenient to run periodically with `watch` in a separate terminal:
+
```shell
watch -n 0.1 ccache -s # update the stats readout every 0.1 seconds
```
diff --git a/docs/website/docs/building-from-source/getting-started.md b/docs/website/docs/building-from-source/getting-started.md
index 89e2193..2c0f748 100644
--- a/docs/website/docs/building-from-source/getting-started.md
+++ b/docs/website/docs/building-from-source/getting-started.md
@@ -76,7 +76,9 @@
# Additional quality of life CMake flags:
# Enable ccache:
- # -DIREE_ENABLE_CCACHE=ON
+ # See https://github.com/iree-org/iree/blob/main/docs/developers/developing_iree/ccache.md
+ # -DCMAKE_C_COMPILER_LAUNCHER=ccache
+ # -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
```
=== "Windows"
