idf.py: Add environment variable to enable ccache by default

docs/en/api-guides/build-system.rst

@@ -99,6 +99,18 @@ Advanced Commands
 
 The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
 
+idf.py options
+^^^^^^^^^^^^^^
+
+To list all available options, run ``idf.py --help``.
+
+- ``-C <dir>`` allows overriding the project directory from the default current working directory.
+- ``-B <dir>`` allows overriding the build directory from the default ``build`` subdirectory of the project directory.
+- ``--ccache`` flag can be used to enable CCache_ when compiling source files, if the CCache_ tool is installed. This can dramatically reduce some build times.
+
+Note that some older versions of CCache may exhibit bugs on some platforms, so if files are not rebuilt as expected then try disabling ccache and build again. CCache can be enabled by default by setting the ``IDF_ENABLE_CCACHE`` environment variable to a non-zero value.
+- ``-v`` flag causes both ``idf.py`` and the build system to produce verbose build output. This can be useful for debugging build problems.
+
 Using CMake Directly
 --------------------
 
@@ -1365,3 +1377,4 @@ Flashing from make
 .. _quirc: https://github.com/dlbeer/quirc
 .. _pyenv: https://github.com/pyenv/pyenv#README
 .. _virtualenv: https://virtualenv.pypa.io/en/stable/
+.. _CCache: https://ccache.dev/

tools/ci/test_build_system_cmake.sh

@@ -439,11 +439,11 @@ endmenu\n" >> ${IDF_PATH}/Kconfig;
 
     print_status "Check ccache is used to build"
     touch ccache && chmod +x ccache  # make sure that ccache is present for this test
-    (export PATH=$PWD:$PATH && idf.py --ccache reconfigure | grep "ccache will be used for faster builds") || failure "ccache should be used when --cache is specified"
+    (export PATH=$PWD:$PATH && idf.py --ccache reconfigure | grep "ccache will be used") || failure "ccache should be used when --cache is specified"
     idf.py fullclean
-    (export PATH=$PWD:$PATH && idf.py reconfigure| grep -c "ccache will be used for faster builds" | grep -wq 0) \
+    (export PATH=$PWD:$PATH && idf.py reconfigure| grep -c "ccache will be used" | grep -wq 0) \
         || failure "ccache should not be used even when present if --ccache is not specified"
-    (export PATH=$PWD:$PATH && idf.py --no-ccache reconfigure| grep -c "ccache will be used for faster builds" | grep -wq 0) \
+    (export PATH=$PWD:$PATH && idf.py --no-ccache reconfigure| grep -c "ccache will be used" | grep -wq 0) \
         || failure "--no-ccache causes no issue for backward compatibility"
     rm -f ccache
 

tools/cmake/project.cmake

@@ -247,7 +247,7 @@ macro(project project_name)
     if(CCACHE_ENABLE)
         find_program(CCACHE_FOUND ccache)
         if(CCACHE_FOUND)
-            message(STATUS "ccache will be used for faster builds")
+            message(STATUS "ccache will be used for faster recompilation")
             set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)
         else()
             message(WARNING "enabled ccache in build but ccache program not found")

tools/idf.py

@@ -988,9 +988,9 @@ def init_cli():
             },
             {
                 "names": ["--ccache/--no-ccache"],
-                "help": "Use ccache in build. Disabled by default.",
+                "help": "Use ccache in build. Disabled by default, unless IDF_CCACHE_ENABLE environment variable is set to a non-zero value.",
                 "is_flag": True,
-                "default": False,
+                "default": os.getenv("IDF_CCACHE_ENABLE") not in [None, "", "0"],
             },
             {
                 "names": ["-G", "--generator"],