memory-vibes

Imported from phaus/memory-vibes (AGENTS.md). Install upstream with npx skills add phaus/memory-vibes. Copyright stays with the author.

Project Agents & Development Guidelines

This repository provides a small set of agents (convention‑based scripts) that automate common development workflows. In addition, the file defines the coding style and tooling expectations for contributors and for any automated coding agents that operate on this codebase.

Table of Contents

1. Agents Overview
2. Build Agent
3. Build Troubleshooting
4. Lint / Formatting Agent
5. Test Agent
6. Run Agent
7. CI/CD Monitoring
8. Code Style Guidelines
9.   - General C++ Conventions
10.   - Naming Conventions
11.   - Headers & Includes
12.   - Formatting Rules
13.   - Error Handling & Exceptions
14.   - Types & Const‑correctness
15.   - Testing Practices
16. Cursor / Copilot Rules
17. Agent Invocation Cheat‑Sheet

Agents Overview

All agents are thin wrappers around standard commands; they exist to give agents a predictable entry‑point.

Build Agent

# Build the project in Release mode (default)
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

*The resulting executable is ./mem_band (Linux/macOS) or Release\\mem_band.exe (Windows).

Optional flags:

• -DENABLE_SIMD=ON – enable AVX2 SIMD kernels (requires compatible compiler).
• -DCMAKE_BUILD_TYPE=Debug – for local debugging and symbol generation.

Build configurations:

• Default (core only): No external dependencies. Build works out-of-the-box.
• With SIMD: -DENABLE_SIMD=ON. Enables AVX2/SSE2/Altivec kernels.
• With CUDA: -DENABLE_CUDA=ON. Builds mem_band_cuda executable (requires CUDA toolkit).
• With ROCm: -DENABLE_ROCM=ON. Builds mem_band_rocm executable (requires ROCm toolkit).
• With JSON: -DENABLE_JSON_OUTPUT=ON. Enables JSON output format (requires nlohmann/json via CMake).
• With SQLite: -DENABLE_SQLITE_OUTPUT=ON. Enables SQLite persistence (requires SQLite3 via CMake).

One‑liner shortcut (available as ./scripts/build.sh):

#!/usr/bin/env bash
set -e
mkdir -p build && cd build
cmake .. "${@:- -DCMAKE_BUILD_TYPE=Release}" && cmake --build .

Build Troubleshooting

Common Build Issues

1. Missing CMakeLists.txt

   • Error: CMake Error: The source directory does not exist
   • Solution: Ensure you're in the project root directory with CMakeLists.txt

2. Compiler not found

   • Error: CMake Error: Cannot find CMAKE_C_COMPILER
   • Solution: Install a C++17-compatible compiler (gcc 7+, clang 5+, MSVC 2017+)

3. Missing dependencies

   • Error: Could NOT find CUDA, Could NOT find ROCm, etc.
   • Solution: Install the required toolkit or disable the feature with -DENABLE_*_FEATURE=OFF

4. Permission denied on Linux

   • Error: /sys/bus/pci/devices access denied
   • Solution: Add user to plugdev group: sudo usermod -a -G plugdev $USER

5. Windows HMODULE cast error

   • Error: C2664: 'FreeLibrary': cannot convert argument 1 from 'void *' to 'HMODULE'
   • Solution: Use static_cast<HMODULE>(handle) when calling FreeLibrary() on Windows

6. C++17 support required

   • Error: error: parallel algorithms require -std=c++17 or later
   • Solution: Ensure compiler supports C++17 or use set(CMAKE_CXX_STANDARD 17) in CMakeLists.txt

Platform-Specific Notes

Linux:

• May require additional packages: libdl-dev for dynamic loading
• For PCIe device detection: read access to /sys/bus/pci/devices

macOS:

• Use Xcode 11+ for C++17 support
• CoreFoundation framework required for platform detection

Windows:

• Use Visual Studio 2017+ or VS Build Tools 2017+
• WMI access required for platform detection (standard on modern Windows)

Lint / Formatting Agent

The project follows the LLVM/Google C++ style with a 2‑space indent.

# Run clang‑format on all source files (auto‑fix)
find src tests -name "*.cpp" -o -name "*.hpp" | xargs clang-format -i -style=file

# Run clang‑tidy (no‑fix) to surface warnings
cmake -B build -S . -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
clang-tidy -p build $(git ls-files "*.cpp" "*.hpp")

The repository contains a .clang-format file (generated by clang-format -style=Google). Ensure it is present; otherwise the default Google style is used.

Test Agent

Full Test Suite

# Run all CTest tests with verbose output
ctest --output-on-failure

Single Test Executable

You can execute any test binary directly, which is useful for quick iteration:

./build/test_alignment            # alignment sanity test
./build/test_benchmark            # benchmark unit test
./build/test_double               # double‑precision kernel test

Adding New Tests

1. Create a tests/<name>.cpp that includes <gtest/gtest.h> (GoogleTest is already a dependency).
2. Add the source to CMakeLists.txt with add_executable(test_<name> tests/<name>.cpp).
3. Register the test using add_test(NAME <Name> COMMAND test_<name>).
4. Re‑run the Build Agent to generate the new binary.

Run Agent

# Default run (copies 256 MiB, 20 iterations, float)
./mem_band

# Custom example – 1 GiB, 30 iterations, double precision, SIMD enabled
./mem_band --size 1024 --iters 30 --type double -S

All options are listed by ./mem_band --help.

CI/CD Monitoring

Checking Build Status

The CI/CD pipeline runs on every push to maintain code quality across all platforms (Linux, macOS, Windows).

View current build status:

# Visit GitHub Actions for this repository
open https://github.com/phaus/memory-vibes/actions

Or use GitHub CLI:

gh run list --limit 10

Understanding CI/CD Results

The CI/CD workflow runs:

• Linux: gcc and clang with various build configurations
• macOS: Latest Xcode toolchain
• Windows: Visual Studio 2022 (MSVC)

Status Indicators:

• ✓ Green: All platform builds and tests passed
• ⚠ Yellow: Warning-only builds (may indicate deprecation warnings)
• ✗ Red: Build or test failure requiring immediate attention

Troubleshooting CI Failures

1. Click on the failed workflow run in the GitHub Actions UI
2. Expand the failed job (Linux/macOS/Windows)
3. Inspect the error in the build logs
4. Local reproduction: Build with the same compiler flags locally

Common issues:

• Header include paths: Verify paths in CMakeLists.txt and #include directives
• Platform-specific code: Use #ifdef _WIN32, #ifdef __APPLE__, #ifdef __linux__
• Compiler-specific warnings: Add -Wno-<warning> in CMakeLists.txt for known issues

Expected CI Behavior After Changes

• New feature added: All tests pass, new tests added
• Bug fix: Existing tests pass, regression test added
• Refactoring: No functional changes, all tests pass
• Platform support: All three platforms (Linux/macOS/Windows) build and test

CI Build Matrix

The CI pipeline tests multiple configurations across three platforms:

Dependency configurations tested:

• Default build: No external dependencies (core functionality only)
• SIMD build: AVX2/SSE2/Altivec enabled via -DENABLE_SIMD=ON
• CUDA build: NVIDIA GPU benchmarking via -DENABLE_CUDA=ON
• ROCm build: AMD GPU benchmarking via -DENABLE_ROCM=ON
• JSON build: JSON output format via -DENABLE_JSON_OUTPUT=ON
• SQLite build: SQLite persistence via -DENABLE_SQLITE_OUTPUT=ON

Linux platform builds also test legacy configurations:

• PowerPC32/64: Toolchain-based cross-compilation
• i386: 32-bit x86 support

Code Style Guidelines

General C++ Conventions

• Use C++17 language features exclusively; avoid compiler‑specific extensions.
• Prefer standard library over hand‑rolled utilities (e.g., std::vector, std::array).
• Keep header files self‑contained: include everything they need, guard with #ifndef/#define.
• Each translation unit must compile with -Wall -Wextra -Werror in CI.

Naming Conventions

Headers & Includes

• Order: 1) C system headers, 2) C++ standard library, 3) third‑party, 4) project headers.
• Separate each group with a blank line.
• Prefer include‑what‑you‑use; never rely on transitive includes.
• Use #include "<relative_path>" for project headers.

Formatting Rules

• Indentation: 2 spaces, no tabs.
• Maximum line length: 100 characters (except long literals or URLs).
• Braces follow K&R style:

  if (cond) {
    // ...
  } else {
    // ...
  }

• Trailing whitespace is prohibited.
• Files end with a single newline.
• Use clang-format with the repository‑provided .clang-format file.

Error Handling & Exceptions

• The codebase does not use exceptions; all error paths return nullptr or bool where appropriate.
• For fatal conditions (e.g., allocation failure) return nullptr and let the caller decide.
• Use assert for invariant violations that should never happen in production.
• Prefer RAII for resource management (std::unique_ptr, custom deleters).

Types & Const‑correctness

• Pass read‑only parameters by const T& or const T*; mutable buffers use non‑const pointers.
• Use fixed‑width integer types (std::uint32_t, std::size_t) for sizes.
• Avoid raw int for sizes; prefer std::size_t.
• Mark functions that do not modify members as const.
• Use constexpr for compile‑time constants.

Testing Practices

• Keep tests small, deterministic, and fast (< 0.1 s each).
• Use GoogleTest assertions (EXPECT_EQ, ASSERT_TRUE).
• Test edge cases: zero size, non‑multiple‑of‑alignment, allocation failure simulation (mock aligned_alloc).
• Verify SIMD code paths via compile‑time ENABLE_SIMD flag.

Cursor / Copilot Rules

The repository does not contain a .cursor/ directory or a .github/copilot-instructions.md file, so no special instruction sets are enforced. Agents should follow the general style described above.

Agent Invocation Cheat‑Sheet

Add these scripts to package.json or a Makefile if you prefer make‑based shortcuts.

Generated by the OpenCode assistant.