Merge branch 'bugfix/idf_py_ccache_options' into 'master'

idf.py: Add way to enable CCache by default, remove dead CCache options code

Closes IDF-948

See merge request espressif/esp-idf!5971

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

@@ -310,15 +310,6 @@ def build_target(target_name, ctx, args):
     _ensure_build_directory(args)
     generator_cmd = GENERATOR_CMDS[args.generator]
 
-    if args.ccache:
-        # Setting CCACHE_BASEDIR & CCACHE_NO_HASHDIR ensures that project paths aren't stored in the ccache entries
-        # (this means ccache hits can be shared between different projects. It may mean that some debug information
-        # will point to files in another project, if these files are perfect duplicates of each other.)
-        #
-        # It would be nicer to set these from cmake, but there's no cross-platform way to set build-time environment
-        # os.environ["CCACHE_BASEDIR"] = args.build_dir
-        # os.environ["CCACHE_NO_HASHDIR"] = "1"
-        pass
     if args.verbose:
         generator_cmd += [GENERATOR_VERBOSE[args.generator]]
 
@@ -997,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"],