# PIP Codebase Guide for AGENTS

## Build Commands

### Basic Build
```bash
# Configure with CMake (release build)
cmake -B build -j16

# Build the project
cmake --build build -j16

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

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

### With Tests
```bash
cmake -B build -DTESTS=ON -j16
cmake --build build -j16
cd build && ctest
```

### Build Only
```bash
cmake --build build -j16
```

### Run Single Test
```bash
# 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:
  ```cpp
  //! \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
```bash
# 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