diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index d57a71209..602b3c4e6 100644 --- a/docs/en/api-guides/build-system.rst +++ b/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 `` allows overriding the project directory from the default current working directory. +- ``-B `` 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 -------------------- @@ -1474,3 +1486,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/ diff --git a/tools/ci/test_build_system_cmake.sh b/tools/ci/test_build_system_cmake.sh index 42f6ebf7a..6ee3559a9 100755 --- a/tools/ci/test_build_system_cmake.sh +++ b/tools/ci/test_build_system_cmake.sh @@ -465,11 +465,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 diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake index 483b66060..81bf37dd5 100644 --- a/tools/cmake/project.cmake +++ b/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") diff --git a/tools/docker/Dockerfile b/tools/docker/Dockerfile index 05db8cb89..ffb00124d 100644 --- a/tools/docker/Dockerfile +++ b/tools/docker/Dockerfile @@ -8,7 +8,6 @@ RUN apt-get update && apt-get install -y \ ca-certificates \ ccache \ check \ - cmake \ curl \ flex \ git \ @@ -53,8 +52,14 @@ RUN echo IDF_CHECKOUT_REF=$IDF_CHECKOUT_REF IDF_CLONE_BRANCH_OR_TAG=$IDF_CLONE_B git submodule update --init --recursive; \ fi -RUN $IDF_PATH/install.sh && \ - rm -rf $IDF_TOOLS_PATH/dist +# Install all the required tools, plus CMake +RUN $IDF_PATH/tools/idf_tools.py --non-interactive install required \ + && $IDF_PATH/tools/idf_tools.py --non-interactive install cmake \ + && $IDF_PATH/tools/idf_tools.py --non-interactive install-python-env \ + && rm -rf $IDF_TOOLS_PATH/dist + +# Ccache is installed, enable it by default +ENV IDF_CCACHE_ENABLE=1 COPY entrypoint.sh /opt/esp/entrypoint.sh diff --git a/tools/idf.py b/tools/idf.py index 2cee97441..8ce5109bd 100755 --- a/tools/idf.py +++ b/tools/idf.py @@ -966,9 +966,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"],