Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions SerialPrograms/BuildInstructions/CompilingForMac.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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/<YOUR_MAC_USERNAME>/Library/Caches/ccache/PA-Arduino-Source base_dir=<YOUR_PATH_TO_ARDUINO-SOURCE_FOLDER>
...
-- Configuring done
-- Generating done
-- Build files have been written to: <YOUR_PATH_TO_ARDUINO-SOURCE_FOLDER>/build_mac
Expand All @@ -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
```
Expand Down Expand Up @@ -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`.

<hr>

Guide Written by: jw098
Guide Written by: Gin, jw098

**Discord Server:**

Expand Down
3 changes: 3 additions & 0 deletions SerialPrograms/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
93 changes: 93 additions & 0 deletions SerialPrograms/cmake/Ccache.cmake
Original file line number Diff line number Diff line change
@@ -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<name>=<value>:
# 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 <repo root path>
# -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 "$<CONFIG:Debug,RelWithDebInfo>")
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()
Loading