165 lines
5.0 KiB
Markdown
165 lines
5.0 KiB
Markdown
# PIP Codebase Guide for AGENTS
|
|
|
|
## Build Commands
|
|
|
|
### Basic Build
|
|
```bash
|
|
# 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
|
|
```bash
|
|
cmake -B build -DTESTS=ON
|
|
cmake --build build
|
|
cd build && ctest
|
|
```
|
|
|
|
### Build Only
|
|
```bash
|
|
cmake --build build
|
|
```
|
|
|
|
### 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 |