Cache Management

A work-in-progress utility to tame package managers and keep your caches under control. Because your storage is not free real estate.

I highly recommend reading the Concept Document on why this utility exists.

Example output (commit)

Calculating usage statistics...
/home/magiruuvelvet/.gradle         -> /caches/1000/gradle     :   4.79GB (4791587980 bytes)
/caches/1000/node_modules                                      :   1.74GB (1742599173 bytes)
/home/magiruuvelvet/.npm            -> /caches/1000/npm        : 299.15MB (299146736 bytes)
/home/magiruuvelvet/.pub-cache      -> /caches/1000/pub-cache  : 282.39MB (282389093 bytes)
/home/magiruuvelvet/.dartServer     -> /caches/1000/dartServer : 216.64MB (216636701 bytes)
/tmp/preamble-*.pch                                            : 210.98MB (210975016 bytes)
/home/magiruuvelvet/.cargo          -> /caches/1000/cargo      : 191.27MB (191267914 bytes)
/home/magiruuvelvet/.m2             -> /caches/1000/m2         : 106.89MB (106892892 bytes)
/caches/1000/cmake                                             :  23.10MB (23098756 bytes)
/home/magiruuvelvet/.node-gyp       -> /caches/1000/node-gyp   :  12.23MB (12230361 bytes)
/home/magiruuvelvet/.cache/composer -> /caches/1000/composer   :      13B (13 bytes)
/home/magiruuvelvet/.bundle         -> /caches/1000/bundle     :       0B (0 bytes)
/home/magiruuvelvet/.cache/clangd   -> /caches/1000/clangd     :       0B (0 bytes)
/home/magiruuvelvet/.dub            -> /caches/1000/dub        :       0B (0 bytes)
/home/magiruuvelvet/.go             -> /caches/1000/go         :       0B (0 bytes)
/home/magiruuvelvet/.cache/go-build -> /caches/1000/go-build   :       0B (0 bytes)
/home/magiruuvelvet/.cache/zig      -> /caches/1000/zig        :       0B (0 bytes)
/home/magiruuvelvet/.cache/zls      -> /caches/1000/zls        :       0B (0 bytes)
                                                    total size :   7.88GB (7876824635 bytes)
                                 available space on cache root :  28.28GB (28276158464 bytes)

Requirements

• C++20 compiler
• C++ standard library with <filesystem> support
• CMake 3.25 or higher

Bundled dependencies

This project uses git submodules to manage its bundled dependencies. Ensure to make a recursive clone with git clone --recursive. If you have already cloned the repository without submodules, you can run git submodule update --init --recursive instead.

• rapidyaml: YAML is used to configure this application.
• {fmt}: Modern formatting library.
• quill: used for logging.
• simdjson: This library was chosen for the JSON parsing support in the package manager module. It works without exceptions and is also super fast.
• argparse-cpp: Simple stupid command line parser for C++
• sqlite3*: A SQLite database is used for local cache analytics. SQLite was chosen for flexibility, portability and ease-of-use. This allows you to easily analyze the database using 3rd party applications.

* can be build and linked against the system shared version if desired

Testing dependencies

• Catch2: Testing framework

Supported Operating Systems

As of right now, this utility only works on Linux, but it might compile and run on BSD platforms too.

To add support for other operating system, you technically only need to extend src/utils. If changes to the remaining codebase are needed, then this is considered a bug in the architecture of the application.

Building

Out of source builds are recommended.

cmake -B ./build
cmake --build ./build

Configuration

The configuration is stored in $XDG_CONFIG_HOME/cachemgr/cachemgr.yaml (~/.config/cachemgr/cachemgr.yaml if XDG_CONFIG_HOME is not set).

The log file is stored in $XDG_CACHE_HOME/cachemgr/cachemgr.log (~/.cache/cachemgr/cachemgr.log if XDG_CACHE_HOME is not set).

For an example configuration, see test.yaml from the unit tests.

Database

Attention:
Versions prior to 0.13.0 should not be used on production databases, as version 0.13.0 was the first version which introduced a schema version check on startup. Using an incompatible database can lead to data loss and data corruption.

This application creates a SQLite database to store local cache analytics. Each time the cache usage statistics are calculated, a cache trend record is created in the database. This allows you to keep track of cache growth and shrinkage, and even generate fancy graphs for visualization (using 3rd party software).

Database Tables

Notice: static typing is enforced using constraints

• schema_migration: internal table used for schema migrations (DO NOT TOUCH)

• cache_trends: cache trend records

  • timestamp (INTEGER NOT NULL CHECK(timestamp >= 0))
    UTC unix timestamp when the trend was calculated
  • cache_mapping_id (TEXT NOT NULL)
    user-defined cache mapping id (from the configuration file)
  • package_manager (TEXT)
    the package manager of the cache mapping
  • cache_size (INTEGER NOT NULL CHECK(cache_size >= 0))
    cache size in bytes
  • Hint: select all records with a human-readable date format: select datetime(timestamp, 'unixepoch'), * from cache_trends;