diff --git a/SerialPrograms/BuildInstructions/CompilingForMac.md b/SerialPrograms/BuildInstructions/CompilingForMac.md index 8569cd0f76..af12896b66 100644 --- a/SerialPrograms/BuildInstructions/CompilingForMac.md +++ b/SerialPrograms/BuildInstructions/CompilingForMac.md @@ -94,11 +94,18 @@ brew install cmake ### Install Ninja -Ninja is a build tool that CMake can use to find out quickly what files need rebuilding. Install it using Homebrew by running in Terminal +Ninja is a build tool that CMake can use to find out quickly what files need rebuilding by file modification time. Install it using Homebrew by running in Terminal ``` brew install ninja ``` +### Install ccache + +ccache is another build tool that saves build time. It uses a cache to skip building a source code file if that file's content has been compiled before. Install it using Homebrew by running in Terminal +``` +brew install ccache +``` + ### Install Qt6 We use Qt6 software library to build UI (windows, panels, buttons...) for **SerialPrograms**. It also plays and decodes audio. @@ -268,11 +275,13 @@ This makes a new folder called "build_mac" in "Arduino-Source" and moves the Ter Execute the command in Terminal: ``` -cmake ../SerialPrograms/ -G Ninja -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_PREFIX_PATH=$HOME/Qt/6.10.2/macos +cmake ../SerialPrograms/ -G Ninja -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_PREFIX_PATH=$HOME/Qt/6.10.2/macos -DPA_USE_CCACHE=ON ``` -This command uses CMake to configure our code to prepare for compilation. `-G Ninja` tells CMake to compile with Ninja, and `-DCMAKE_PREFIX_PATH` tells CMake where the Qt you installed is. If successful, it should print texts like +This command uses CMake to configure our code to prepare for compilation. `-G Ninja` tells CMake to compile with Ninja, `-DCMAKE_PREFIX_PATH` tells CMake where the Qt you installed is, and `-DPA_USE_CCACHE=ON` tells CMake to compile with ccache. If successful, it should print texts like ``` ... +-- Using ccache: /opt/homebrew/bin/ccache cache_dir=/Users//Library/Caches/ccache/PA-Arduino-Source base_dir= +... -- Configuring done -- Generating done -- Build files have been written to: /build_mac @@ -286,6 +295,7 @@ cmake --build . -j 10 ``` to compile and build the program in "build_mac" folder. It will take a while to build depending on your computer's speed. +Later builds should be faster thanks to Ninja and ccache. Each line starts with a counter like `[25/1613]`. If successful, the counter reaches the total, and the last lines in Terminal look like ``` @@ -351,11 +361,26 @@ rm -rf build_mac to delete the old "build_mac" folder. Then follow [Part 4: Compile the Program](#part-4-compile-the-program) again, with the new Qt version in the `-DCMAKE_PREFIX_PATH` part of the CMake command. +## Part 7: Tuning ccache (optional) + +The default ccache settings work for most people. This part is for developers who build often or keep several copies of the code (a.k.a worktrees) in the filesystem. + +To check cache statistics on the codebase (how many cache hits and misses so far and storage space uses), run in Terminal +``` +ccache --dir $(ccache --get-config cache_dir)/PA-Arduino-Source -s +``` + +By default ccache has a max cache size of 5 GB. When the storage is full, ccache deletes the files it used least recently. +If you often switch between many branches and worktrees of the codebase, you can increase its size to say 20 GB by +``` +ccache --dir $(ccache --get-config cache_dir)/PA-Arduino-Source --set-config max_size=20G +``` +For more info on how we set up ccache when configuring the program, see `SerialPrograms/cmake/Ccache.cmake`.
-Guide Written by: jw098 +Guide Written by: Gin, jw098 **Discord Server:** diff --git a/SerialPrograms/CMakeLists.txt b/SerialPrograms/CMakeLists.txt index 35bb597e32..892a04d94b 100644 --- a/SerialPrograms/CMakeLists.txt +++ b/SerialPrograms/CMakeLists.txt @@ -26,6 +26,9 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_EXPORT_COMPILE_COMMANDS ON) #set(CMAKE_VERBOSE_MAKEFILE ON) +# Compile through ccache when it is installed. See cmake/Ccache.cmake for the options. +include(cmake/Ccache.cmake) + # Set these three on globally so all intermediate Qt targets can get processed automatically set(CMAKE_AUTOMOC ON) set(CMAKE_AUTORCC ON) diff --git a/SerialPrograms/cmake/Ccache.cmake b/SerialPrograms/cmake/Ccache.cmake new file mode 100644 index 0000000000..6ebad144a1 --- /dev/null +++ b/SerialPrograms/cmake/Ccache.cmake @@ -0,0 +1,93 @@ +# Ccache.cmake: set up ccache to save compile time on mac/Linux. +# +# Included from CMakeLists.txt right after project() and before any target is created. +# +# Options, passed to CMake as -D=: +# PA_USE_CCACHE Use ccache on mac/Linux if it is installed (default OFF). Needs +# ccache 4.8+. Stops with an error if a compiler launcher is also +# given, e.g. -DCMAKE_CXX_COMPILER_LAUNCHER=ccache: use one or the other. +# PA_CCACHE_CONFIG ccache settings for every compile (default: Arduino-Source has +# its own ccache folder, and base_dir set to the checkout's root +# folder). base_dir allows builds to share the cache across worktrees. +# PA_CCACHE_DEBUG_PATHS Change to using relative paths in debug (Debug and RelWithDebInfo) +# builds (default ON) when ccache is on. This allows debug builds +# to also share the cache across worktrees. + +option(PA_USE_CCACHE "Compile through ccache on mac/Linux if it is installed" OFF) + +# set _pa_checkout_dir to be the repo root path +cmake_path(GET CMAKE_CURRENT_SOURCE_DIR PARENT_PATH _pa_checkout_dir) + +# By default, builds with debug info (Debug and RelWithDebInfo) store the build folder's +# full paths in it, so ccache can't share cache across different worktrees, as worktrees +# have their own full paths. +# When both PA_USE_CCACHE and PA_CCACHE_DEBUG_PATHS are on, we added option +# -fdebug-prefix-map +# -fdebug-compilation-dir=. +# as compiler flags. This lets the debug builds use relative paths, enabling cache sharing +# across worktrees. +option(PA_CCACHE_DEBUG_PATHS "With ccache, use relative paths in debug info so Debug and RelWithDebInfo builds share the cache across worktrees" ON) + +if(PA_USE_CCACHE AND NOT MSVC) + find_program(CCACHE_PROGRAM ccache) + if(CCACHE_PROGRAM) + if(CMAKE_C_COMPILER_LAUNCHER OR CMAKE_CXX_COMPILER_LAUNCHER) + message(FATAL_ERROR + "PA_USE_CCACHE=ON also sets up CMAKE_C_COMPILER_LAUNCHER and CMAKE_CXX_COMPILER_LAUNCHER.\n" + "Either remove CMAKE_C_COMPILER_LAUNCHER and CMAKE_CXX_COMPILER_LAUNCHER or disable PA_USE_CCACHE." + ) + endif() + + execute_process( + COMMAND "${CCACHE_PROGRAM}" --version + OUTPUT_VARIABLE _pa_ccache_version_output + ERROR_QUIET + ) + string(REGEX MATCH "version ([0-9]+\\.[0-9]+(\\.[0-9]+)?)" _ "${_pa_ccache_version_output}") + set(_pa_ccache_version "${CMAKE_MATCH_1}") + + # ccache 4.8 is the first version that takes settings on the command line, which is how + # PA_CCACHE_CONFIG reaches every compile. + if(_pa_ccache_version VERSION_LESS 4.8) + message(FATAL_ERROR + "PA_USE_CCACHE=ON needs ccache 4.8 or newer, but ${CCACHE_PROGRAM} is version ${_pa_ccache_version}.\n" + "Either upgrade ccache or disable PA_USE_CCACHE." + ) + endif() + + execute_process( + COMMAND "${CCACHE_PROGRAM}" --get-config cache_dir + OUTPUT_VARIABLE _pa_ccache_main_dir + OUTPUT_STRIP_TRAILING_WHITESPACE + ERROR_QUIET + ) + if(_pa_ccache_main_dir) + set(_pa_ccache_default_config "cache_dir=${_pa_ccache_main_dir}/PA-Arduino-Source;base_dir=${_pa_checkout_dir}") + else() + set(_pa_ccache_default_config "base_dir=${_pa_checkout_dir}") + endif() + + # set PA_CCACHE_CONFIG in CMake cache + set(PA_CCACHE_CONFIG "${_pa_ccache_default_config}" + CACHE STRING "ccache settings passed on every compile's command line, as key=value pairs") + + set(_pa_ccache_launcher "${CCACHE_PROGRAM}" ${PA_CCACHE_CONFIG}) + list(JOIN _pa_ccache_launcher " " _pa_ccache_launcher_text) + message(STATUS "Using ccache: ${_pa_ccache_launcher_text}") + set(CMAKE_C_COMPILER_LAUNCHER "${_pa_ccache_launcher}") + set(CMAKE_CXX_COMPILER_LAUNCHER "${_pa_ccache_launcher}") + + if(PA_CCACHE_DEBUG_PATHS) + # Only builds with debug info get these options. + set(_pa_has_debug_info "$") + add_compile_options("$<${_pa_has_debug_info}:-fdebug-prefix-map=${_pa_checkout_dir}=.>") + # Clang has this option, but not every compiler does. Without it, the prefix map + # above still covers the compile folder when the build folder is inside the checkout. + include(CheckCompilerFlag) + check_compiler_flag(CXX "-fdebug-compilation-dir=." PA_HAS_DEBUG_COMPILATION_DIR) + if(PA_HAS_DEBUG_COMPILATION_DIR) + add_compile_options("$<${_pa_has_debug_info}:-fdebug-compilation-dir=.>") + endif() + endif() + endif() +endif()