CLAUDE.md — C++ Module

This file provides guidance to Claude Code (claude.ai/code) when working with the C++ module.

Build Commands

# Build (Release, default)
bash build.sh

# Build variants
bash build.sh -t=Debug
bash build.sh -t=RelWithDebInfo
bash build.sh -a=ON              # Enable AddressSanitizer
bash build.sh -c=ON              # Enable code coverage

# Disable optional compression libraries
bash build.sh --disable-snappy --disable-lz4 --disable-lzokay --disable-zlib \
  --disable-zstd --disable-lzma2

# LZMA2 is opt-in; its bundled XZ build requires CMake 3.20+
bash build.sh --enable-lzma2=ON

# Or use CMake directly
mkdir -p build/Release && cd build/Release
cmake ../.. -DCMAKE_BUILD_TYPE=Release -DBUILD_TEST=ON
make -j$(nproc)

# Via Maven from repo root
./mvnw clean verify -P with-cpp

# Run all tests
./build/Release/lib/TsFile_Test

# Run specific test suite
./build/Release/lib/TsFile_Test --gtest_filter=SnappyCompressorTest.*

Build Options (CMake)

All ON by default unless noted:

OptionPurpose
BUILD_TESTCompile tests (GTest 1.12.1, auto-downloaded)
ENABLE_ANTLR4ANTLR4 parser runtime
ENABLE_SNAPPY / ENABLE_LZ4 / ENABLE_LZOKAY / ENABLE_ZLIB / ENABLE_ZSTDCompression libraries
ENABLE_LZMA2LZMA2 compression (OFF by default; bundled XZ requires CMake 3.20+)
ENABLE_THREADSMulti-threaded read/write via pthreads
ENABLE_ASANAddressSanitizer (OFF by default)
ENABLE_SIMDSIMD acceleration

Source Structure

cpp/src/
├── common/        # Core types: Schema, Tablet, DeviceId, TsBlock, allocators, config
├── compress/      # Compression: Snappy, LZ4, LZOKAY, Zlib (factory pattern)
├── encoding/      # Encoding: Plain, TS2Diff, Gorilla, Dictionary, RLE, Zigzag, SPRINTZ
├── file/          # File I/O: TsFileIOReader/Writer, RestorableTsFileIOWriter
├── reader/        # Read path: TsFileReader, QueryExecutor, filters, result sets
├── writer/        # Write path: TsFileWriter, TsFileTableWriter, ChunkWriter, PageWriter
├── parser/        # ANTLR4 path parser (grammars + generated code)
├── cwrapper/      # C language bindings (used by Python module)
└── utils/         # Utilities: error codes, date handling, fault injection

Architecture Notes

  • C++11 standard, targets CMake 3.11+; bundled XZ/LZMA2 requires CMake 3.20+, while older CMake can enable LZMA2 with a compatible system liblzma
  • Dual data model: tree-view (TsFileTreeWriter/Reader) and table-view (TsFileTableWriter, TableQueryExecutor)
  • Parallel column encoding in table write path, controlled by ENABLE_THREADS
  • Third-party dependencies are either retained under third_party/ or resolved from compatible system packages and verified source archives; see third_party/README.md.
  • cwrapper/ provides the C API that the Python module binds to via Cython

Code Style

  • Formatter: clang-format (Google style), configured in .clang-format
  • After modifying C++ code, run from the repo root to format: ./mvnw spotless:apply -P with-cpp

Testing

  • Framework: Google Test 1.12.1 (auto-downloaded during build, or supply third_party/googletest-release-1.12.1.zip)
  • Tests in cpp/test/, mirroring src/ structure
  • Test discovery via gtest_discover_tests()

License Header

Every new file must include the Apache License 2.0 header at the top. For C/C++ files, use the /* */ block comment style. See any existing .h or .cc file for the exact wording.

Git Commit

  • Do NOT add Co-Authored-By trailer to commit messages.