[aphelps]

Closes Issue #5533

Summary

build_cache_dir (a SCons CacheDir) is never pruned, so it grows without bound. This adds two optional settings, both off by default (no behaviour change):

• build_cache_max_age: remove entries not used for N days (integer >= 1)
• build_cache_max_size: cap the cache size, e.g. 500MB / 10GB; least recently used entries go first

SCons updates a cache file's mtime on every hit (SCons/CacheDir.py), so mtime is the last-used time. The prune:

• runs at most once a day when a build starts (stamp file in the cache dir)
• is best-effort and never fails a build
• only touches entries inside the cache's bucket sub-folders, so SCons' own root files (config, .sconsign*) are left alone

Invalid values (build_cache_max_size = lots, build_cache_max_age = -1) fail with a clear config error. Size is enforced at build start, so a build can exceed the cap by what it adds.

Real-world motivation: an ESP32/Arduino (WLED) project reached ~62 GB / 75k files in ~10 months, ~93% unused for over 45 days.

Test plan

• pytest tests/misc tests/project: new tests/misc/test_build_cache_prune.py covers age, size/LRU, both limits, root files and symlinks kept, dry run, throttle, future stamp, env vars, zero size, and invalid options
• black / isort / pylint clean on changed files
• Real builds (native unit tests of a sample project, isolated core and cache dirs):
  • no limits: all entries kept
  • PLATFORMIO_BUILD_CACHE_MAX_AGE=45: backdated entries removed, backdated root config and .sconsign* survived
  • an immediate second run was throttled
  • a bad size value stops with a clean error

Not included: docs (separate docs submodule), a pio system prune --build-cache flag. Happy to add either if wanted.

Developed with AI assistance (Claude Code) and reviewed by the author.

[CLAassistant]

All committers have signed the CLA.