|
| 1 | +# Project Guidelines |
| 2 | + |
| 3 | +## Code Style |
| 4 | +- Treat `libCacheSim/` and `test/` as the primary source of truth for style. Most of the codebase is C; use C++17 only in areas that already use C++ wrappers or implementations. |
| 5 | +- Follow the existing formatting and lint configuration in `.clang-format` and `.clang-tidy`. The project uses a Google-based format with 2-space indentation and an 80-column limit. |
| 6 | +- Keep changes warning-free. The CMake build enables strict warning sets and `-Werror` for both C and C++. |
| 7 | +- Prefer small, performance-aware changes in hot paths such as cache algorithms, trace readers, and profilers. |
| 8 | + |
| 9 | +## Architecture |
| 10 | +- `libCacheSim/cache/` contains cache implementations, eviction/admission/prefetch algorithms, and plugin support. |
| 11 | +- `libCacheSim/traceReader/` contains trace parsers and reader dispatch; `libCacheSim/traceAnalyzer/`, `libCacheSim/profiler/`, and `libCacheSim/mrcProfiler/` contain analysis and miss-ratio tooling. |
| 12 | +- `libCacheSim/dataStructure/` and `libCacheSim/utils/` provide shared infrastructure; the public C API starts at `libCacheSim/include/libCacheSim.h`. |
| 13 | +- `libCacheSim/bin/` contains CLI entry points, `test/` contains CTest-backed unit tests, `example/` contains integration patterns, and `libCacheSim-node/` is a separate Node.js binding layer. |
| 14 | + |
| 15 | +## Build And Test |
| 16 | +- Prefer the workspace debug build for code changes: run the VS Code `build-debug` task or `bash scripts/debug.sh -c`. This configures and builds `_build_dbg/` with Ninja and the same strict warning flags used by the project. |
| 17 | +- Use a standard out-of-source CMake build for release-style work: `cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release` then `cmake --build build`. |
| 18 | +- CMake tests are enabled by default. Run `ctest --test-dir _build_dbg --output-on-failure` after the debug build, or the equivalent `build/` test directory if you used a separate build tree. |
| 19 | +- If you change installation, packaging, or the public library surface, also review `test/test_lib.sh`. |
| 20 | +- Use sample traces in `data/` for quick validation unless the task specifically requires the large traces in `2024_google/`. |
| 21 | + |
| 22 | +## Project-Specific Conventions |
| 23 | +- When adding a new eviction algorithm, reader, or plugin, follow `doc/advanced_lib_extend.md` instead of inventing a new integration path. These changes usually require updates to implementation files, registration headers, CMake lists, CLI/parser wiring, and tests. |
| 24 | +- For API-level work, confirm the public interface against `doc/API.md` and existing examples in `example/cacheSimulator/`, `example/cacheHierarchy/`, and `example/cacheCluster/`. |
| 25 | +- Optional features such as GLCache, LRB, and 3LCache have extra external dependencies. Do not enable or modify those paths unless the task requires them. |
| 26 | +- Zstd trace support is on by default and is required for compressed traces. Release builds may link tcmalloc; the debug workflow avoids that to stay debugger-friendly. |
| 27 | + |
| 28 | +## Docs To Link |
| 29 | +- Installation and dependencies: `doc/install.md` |
| 30 | +- CLI usage: `doc/quickstart_cachesim.md` |
| 31 | +- Debug workflow: `doc/debug.md` |
| 32 | +- Public API and library usage: `doc/API.md` and `doc/advanced_lib.md` |
| 33 | +- Extension workflows: `doc/advanced_lib_extend.md` and `doc/quickstart_plugin.md` |
| 34 | +- Trace and MRC tooling: `doc/quickstart_traceAnalyzer.md`, `doc/quickstart_traceUtils.md`, `doc/quickstart_mrcProfiler.md`, and `doc/performance.md` |
0 commit comments