Skip to content

Build the library as a single translation unit - #365

Merged
lovyan03 merged 1 commit into
m5stack:developfrom
ainyan03:unity_build
Sep 15, 2026
Merged

lovyan03 merged 1 commit into
m5stack:developfrom
ainyan03:unity_build

Conversation

@ainyan03

@ainyan03 ainyan03 commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Why

Every implementation file pulls in the same set of framework headers, and the Arduino build pre-scans every source file for includes before compiling it, so that header parsing happened about 70 times per build. On Windows each pass costs around 3 s.

This PR builds the library as one translation unit: the .cpp files become .inl and are included from src/M5Unified.cpp.

Measured with arduino-cli, CoreS3 sketch, sequential build:

Windows before Windows after macOS before macOS after
Compiling library "M5Unified" 71 s 6 s 10 s 2 s

(The detection pass shrinks by the same 35 files.)

What changed

  • src/**/*.cpp*.inl, included from the new hub src/M5Unified.cpp (36 → 1 translation unit; the former M5Unified.cpp is now M5Unified.inl). The hub file carries the maintenance notes.
  • File-local names that collided once they shared a scope:
    • led_count in LED_PaperMono / LED_PowerHub: private static constexpr member of each class
    • bcd2ToByte / byteToBcd2, duplicated in three RTC drivers: protected static helpers of RTC_Base
    • the I2S helpers and handle arrays of Speaker_Class / Mic_Class: _spk_i2s_* / _mic_i2s_* (the two arrays are distinct on purpose: TX and RX channels of the same port)
    • i2c_freq and the shared on-board device addresses: utility/m5unified_i2c_addr.hpp
    • IS_BIT_SET (AXP2101): #undef at the end of the file
  • CMakeLists.txt lists the hub instead of globbing *.cpp.
  • Each *.inl checks for M5UNIFIED_IMPLEMENTATION, which the hub defines around its includes, and stops with a clear #error when included on its own (a direct include used to surface only as duplicate symbols at link time).

Compatibility

  • Arduino IDE, PlatformIO and ESP-IDF users need no changes. Custom build scripts that glob src/**/*.cpp will now pick up M5Unified.cpp only, which is the intended set.
  • Public headers: two private constants and two protected static helpers were added; no class layout or virtual table changes, so downstream libraries that derive from these classes are unaffected.
  • Binary size is unchanged within a few hundred bytes.

Verification

  • Arduino builds for esp32 / esp32s2 / esp32s3 / esp32c3 / esp32c6 / esp32p4 (core 3.x) with the same warnings as develop; ESP-IDF 5.5 build; native SDL build.
  • The CI of this repository run on a fork of this branch: Arduino Build and ESP-IDF Build pass.

Rename every implementation file to *.inl and include them from
src/M5Unified.cpp. All of them pull in the same framework headers, so parsing
those once instead of once per file cuts the library build time substantially;
the Arduino build also pre-scans each source file for includes, which doubled
that cost. Measured with the Arduino toolchain on Windows (CoreS3 sketch,
sequential): compiling this library went from 71 s to 6 s, and the detection
pass shrank by the same 35 files.

File-local names that collided once they shared a scope:
- led_count (LED_PaperMono / LED_PowerHub): moved into each class
- bcd2ToByte / byteToBcd2 (three RTC drivers): moved to RTC_Base
- I2S helpers and handle arrays in Speaker / Mic: renamed _spk_i2s_* / _mic_i2s_*
  (the two arrays are distinct on purpose, TX and RX channels of the same port)
- i2c_freq and shared device addresses (M5Unified / Power / LED_PaperMono):
  moved to utility/m5unified_i2c_addr.hpp
- IS_BIT_SET (AXP2101): undefined at the end of the file

ESP-IDF: CMakeLists.txt lists the hub file instead of globbing *.cpp. The hub
file carries the maintenance notes.

Each *.inl checks for M5UNIFIED_IMPLEMENTATION, which the hub defines around its
includes, and stops with a clear #error when included on its own.
@lovyan03
lovyan03 merged commit 935b9e8 into m5stack:develop Sep 15, 2026
27 checks passed
@ainyan03
ainyan03 deleted the unity_build branch September 15, 2026 04:51
@ainyan03 ainyan03 mentioned this pull request Sep 21, 2026
lovyan03 added a commit that referenced this pull request Sep 21, 2026
Build the library as a single translation unit

(cherry picked from commit 935b9e8)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants