pip/AGENTS.md

PIP Codebase Guide for AGENTS

Build Commands

Basic Build

# Configure with CMake (release build)
cmake -B build

# Build the project
cmake --build build

# Install (default system location)
cmake --build build --target install

# Local install (bin/lib/include in build directory)
cmake -B build -DLOCAL=ON

With Tests

cmake -B build -DTESTS=ON
cmake --build build
cd build && ctest

Build Only

cmake --build build

Run Single Test

# After building with TESTS=ON
./build/tests/math/pip_math_test --gtest_filter="Vector2DTest.defaultConstructor*"
# Or use ctest
ctest -R math -V
# List all tests
ctest -N

Build Options

• TESTS=ON - Build tests (requires Google Test)
• COVERAGE=ON - Build with coverage instrumentation
• ICU=ON - Enable ICU support for string conversion
• STD_IOSTREAM=ON - Enable std::iostream operators
• INTROSPECTION=ON - Build with introspection support
• PIP_BUILD_* - Enable/disable modules (e.g., PIP_BUILD_CRYPT=OFF)

Code Generation Tools

• pip_cmg - Code model generator (auto-generates code from comments)
• pip_rc - Resources compiler (embeds resources into C++ code)
• pip_tr - Translation tool (compiles .btf translation files)

Linting & Formatting

• clang-format: Run clang-format -i <file> or find . -name "*.cpp" -o -name "*.h" | xargs clang-format -i
• Format config: .clang-format (ColumnLimit: 140, IndentWidth: 4, BraceWrapping: Attach)
• Includes sorting: Enabled (CaseSensitive, SortIncludes: true)
• Macro blocks: PRIVATE_DEFINITION_START/END, STATIC_INITIALIZER_BEGIN/END, DECLARE_UNIT_CLASS_BEGIN/END
• No Cursor/Copilot rules found in this repository

Code Style Guidelines

General

• Language Standard: C++11 (CMAKE_CXX_STANDARD 11)
• File Encoding: UTF-8
• Line Endings: Unix (LF)
• Column Limit: 140 characters

Naming Conventions

• Classes: PascalCase (e.g., PIObject, PIString)
• Functions/Methods: camelCase (e.g., toString(), isEmpty())
• Variables: camelCase (e.g., rowCount, isReady)
• Constants: kPrefixCamelCase (e.g., kMaxSize)
• Macros: UPPER_CASE (e.g., PIP_EXPORT, NO_COPY_CLASS)
• Types: PascalCase with p prefix for internal/private (e.g., PIString_p.h)

File Naming

• Headers: pi<name>.h (e.g., piobject.h, pistring.h)
• Private headers: pi<name>_p.h (e.g., piobject_p.h)
• Test files: test<name>.cpp (e.g., testpivector2d.cpp)

Comments & Documentation

• Use Doxygen-style comments for all public APIs
• Include \~english and \~russian translations
• Group related classes/modules with //! \defgroup
• Use \ingroup to assign files to groups
• Example:

  //! \file piobject.h
  //! \ingroup Core
  //! \~\brief
  //! \~english Base object
  //! \~russian Базовый класс
  

Includes

• Order: System headers → PIP headers → Local headers
• Sort alphabetically within groups
• Use #pragma once or include guards
• PIP includes use #include "pi<name>.h"

Formatting (clang-format)

• Indentation: 4 spaces (no tabs for code)
• Braces: Attach style (if (x) {)
• Pointers/References: Type* ptr, Type& ref
• Templates: Always break before > in nested templates
• Empty Lines: Max 2 consecutive empty lines
• Namespace: No indentation (Namespace { ... })

Error Handling

• Use PIString for error messages
• Return bool for success/failure
• Use assert() for debug-only checks
• Avoid exceptions (RTTI disabled in some builds)

Memory Management

• Prefer stack allocation
• Use NO_COPY_CLASS(MyClass) to disable copy
• Implement proper move semantics when needed
• Use std::unique_ptr/std::shared_ptr sparingly

Macros

• PIMETA(...) - Add metadata for code model generator
• PIP_EXPORT - Export/import symbols for DLLs
• NO_COPY_CLASS - Disable copy constructor and operator=
• PRIVATE_DECLARATION - Private implementation macro

Testing

• Framework: Google Test (fetched automatically when TESTS=ON)
• Test files: tests/<module>/test<name>.cpp
• Use pip_test(module) macro in tests/CMakeLists.txt
• Test discovery via gtest_discover_tests()

Running Tests

# Run all tests
ctest

# Run specific test suite
ctest -R math -V

# List all available tests
ctest -N

# Run single test with gtest filter
./build/tests/math/pip_math_test --gtest_filter="Vector2DTest.defaultConstructor*"

Module Structure

libs/
├── main/          # Core modules
│   ├── core/      # Base types, PIObject, PIString
│   ├── thread/    # Threading primitives
│   ├── math/      # Math functions, vectors, matrices
│   └── ...
└── <module>/      # Feature modules (fftw, crypt, compress, etc.)

Additional Notes

• Project uses custom CMake macros from cmake/ directory
• Version format: MAJOR.MINOR.REVISION (e.g., 5.6.0)
• All files have LGPL license header
• Support for multiple platforms: Windows, Linux, QNX, Android, Apple