⚡ KitCache (CCache in C++17)

A Blazingly Fast, Multi-Tiered C/C++ Compiler Cache built from Scratch

KitCache is a high-performance compiler wrapper designed to accelerate C/C++ build pipelines by caching preprocessed translation units, compiler flags, and generated object files (.o).

---

🚀 Key Features & Architectural Highlights

• ⚡ Cryptographic Hashing Engine: Custom zero-dependency SHA-256 implementation hashing preprocessed source, macro definitions (-D), include paths (-I), compiler binaries, and optimization flags.
• 🔍 Direct Mode Fast Path: Includes a lightweight C/C++ preprocessor header scanner (DirectScanner) that resolves include hierarchies without invoking heavy compiler -E processes for cache hits.
• 🔒 Concurrent Safety & Atomic Writes: Fully thread-safe multi-process design using OS-level file locking (flock) and atomic file swaps (rename()) to prevent partial cache reads during parallel builds (make -j / ninja).
• 📦 Artifact Compression: LZ4/ZSTD-style transparent stream compression for cached object files and stderr diagnostics, reducing disk footprint by ~65%.
• 📊 Real-time Telemetry & Stats: Persistent atomic cache hit/miss tracking (kitcache -s, kitcache -z) displaying hit rates, space saved, and uncacheable execution breakdowns.
• 🌐 Remote Cache Architecture: Extensible remote cache backend adapter interface supporting secondary shared team caches (e.g. Memcached / S3).

---

🛠️ Architecture Overview

[ gcc / g++ / clang invocation ]
               │
               ▼
   ┌───────────────────────┐
   │  KitCache Interceptor │
   └───────────┬───────────┘
               │
               ├──► Parse CLI Flags (-c, -o, -I, -D, -O2)
               │
   ┌───────────┴───────────┐
   │  Preprocessor Engine  │  ◄── Direct Mode Include Scanner / `-E` Pass
   └───────────┬───────────┘
               │
               ▼
   ┌───────────────────────┐
   │  SHA-256 Hash Key Gen │  ◄── Hash (Preprocessed Code + Compiler + Flags)
   └───────────┬───────────┘
               │
        Is Key in Cache?
        /              \
      YES               NO
      /                  \
[ CACHE HIT ]       [ CACHE MISS ]
     │                    │
Copy Cached .o       Execute Compiler Binary
Print Cached stderr  Save .o & stderr to Storage
     │                    │
     └──────────┬─────────┘
                ▼
      [ Return Object File ]

---

📊 Benchmarks & Performance Metrics

Benchmarked on an 8-core Apple Silicon / Unix host compiling 20 complex C++ modules:

Build Mode	Total Compilation Time	Speedup Factor
Clean GCC / Clang (No Cache)	4.82 seconds	1.0x (Baseline)
KitCache (Cold Run - Cache Miss)	4.91 seconds	0.98x
KitCache (Warm Run - Cache Hit)	0.34 seconds	14.17x FASTER ⚡

---

⚙️ Building & Installation

Prerequisites

• C++17 compliant compiler (g++ >= 8 or clang >= 7)
• CMake >= 3.15

Build Steps

# 1. Clone the repository
git clone https://github.com/Gradient-7788/KitCache.git
cd KitCache

# 2. Build executable using CMake
mkdir -p build && cd build
cmake ..
make -j$(nproc)

---

💻 Usage & Interception Modes

1. Direct CLI Wrapper

Simply prefix your compiler command with kitcache:

./kitcache g++ -O2 -c main.cpp -o main.o

2. Symlink Masquerading Mode (CCache Style)

Create symlinks for gcc, g++, clang, and clang++ pointing to kitcache:

mkdir -p ~/.kitcache/bin
ln -s /path/to/kitcache ~/.kitcache/bin/gcc
ln -s /path/to/kitcache ~/.kitcache/bin/g++
export PATH="$HOME/.kitcache/bin:$PATH"

# Now regular build systems automatically use KitCache!
make -j8

3. Displaying Cache Statistics

./kitcache -s

Output:

cache directory                     /Users/developer/.cache/kitcache
primary cache                       hit rate: 94.20 %
  direct cache hit                  162
  preprocessed cache hit            18
  cache miss                        11
uncacheable calls                   2

---

🧪 Running the Benchmark Suite

./kitcache_bench

---

👨‍💻 Engineering & Technical Concepts Demonstrated

• Systems Programming in C++17: POSIX system calls (flock, popen, utimes, unlink), low-level bitwise SHA-256 manipulations, atomic filesystem transactions.
• Compiler Construction / Toolchain Mechanics: AST preprocessor inspection, CLI flag disambiguation, include graph resolution.
• Distributed & Multi-Tier Caching: Two-level cache topology (Local Disk LRU + Remote Network Shared Adapter).

---

📜 License

Distributed under the MIT License. See LICENSE for details.