update AGENTS.md
This commit is contained in:
@@ -1,165 +1,66 @@
|
||||
# PIP Codebase Guide for AGENTS
|
||||
|
||||
## Build Commands
|
||||
C++11 platform-independent library ("Platform-Independent Primitives", version in root `CMakeLists.txt`). No CI, no pre-commit; only clang-format governs style.
|
||||
|
||||
### Basic Build
|
||||
```bash
|
||||
# Configure with CMake (release build)
|
||||
cmake -B build
|
||||
## Build
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### With Tests
|
||||
```bash
|
||||
cmake -B build -DTESTS=ON -DTESTS_RUN=ON
|
||||
cmake --build build -j16
|
||||
cd build && ctest
|
||||
```
|
||||
|
||||
### Build Only
|
||||
```bash
|
||||
cmake --build build -j16
|
||||
```
|
||||
- **Configure-time network dependency**: a standalone configure clones the SHS CMake toolchain (`git.shstk.ru/SHS/cmake`) into `<build>/cmake-src` (the source tree has `cmake/PIPMacros.cmake` but not `SHSTKMacros.cmake`). Reuse an existing build dir when possible; a fresh `cmake -B <new>` fails without network access to that host.
|
||||
- Tests need network too: GoogleTest is fetched (FetchContent, pinned zip) when `TESTS=ON`.
|
||||
- Optional deps (libsodium, zlib, curl, libmicrohttpd, fftw3, libusb, OpenCL) are located via `find_library`; a module is **silently skipped** if its library is missing (check the `----------PIP----------` summary at configure time: `module: yes/no`).
|
||||
- Embedded builds: `PICO_BOARD` (Raspberry Pi Pico SDK, see `esp-pip/`) or `PIP_FREERTOS`/PlatformIO (`library.json`, `platformio_pre.py`) force `LOCAL` install and disable most modules.
|
||||
|
||||
### 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
|
||||
```
|
||||
### Key options
|
||||
- `TESTS=ON` — build gtest suites; `TESTS_RUN=ON` — additionally register tests with CTest (**without it `ctest` finds nothing**).
|
||||
- `COVERAGE=ON` (needs gcov), `STD_IOSTREAM=ON`, `INTROSPECTION=ON` (slows down), `LOCAL=ON` (install to build/bin|lib|include).
|
||||
- `ICU=ON` — OFF by default (README claims ON; trust CMakeLists).
|
||||
- `PIP_BUILD_<MODULE>` — per-module on/off. Modules: `console crypt compress usb fftw opencl io_utils client_server cloud lua http_client http_server mqtt_client`.
|
||||
- `PIP_HAS_<FEATURE>` — feature flags (`FILESYSTEM THREADS SOCKET PROCESS DYNLIB FFT SERIAL`), default ON. A dependency table auto-disables dependents (e.g. `PIP_HAS_SOCKET=OFF` turns off `cloud`, `client_server`, `http_server`, `mqtt_client`).
|
||||
|
||||
### 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`)
|
||||
### Targets
|
||||
- Main library target is **`pip`** (`libpip.so`); feature modules are `pip_<module>` (`pip_console`, `pip_crypt`, ...).
|
||||
- `pip_test` (from root `main.cpp`, built only with `PIP_MANUAL_TEST=ON` + curl + microhttpd) is a manual dev harness, **not** a gtest suite.
|
||||
|
||||
### 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)
|
||||
## Tests
|
||||
|
||||
### 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 Базовый класс
|
||||
- gtest binaries: `build/tests/pip_<suite>_test`, suites: `math core piobject io` always; `client_server` only if libsodium found; `system` if `PIP_HAS_PROCESS`; `thread` if `PIP_HAS_THREADS`.
|
||||
- Run:
|
||||
```bash
|
||||
cd build && ctest # all (300+ tests)
|
||||
ctest -R "Vector2DTest" -V # regex is matched case-sensitively against gtest suite names (e.g. "PIMathMatrix_Test", "Vector2DTest")
|
||||
./tests/pip_math_test --gtest_filter="Vector2DTest.*"
|
||||
```
|
||||
Note: `ctest -R math` matches nothing (names are PascalCase).
|
||||
- Test sources: `tests/<suite>/test<name>.cpp`, added via `pip_test(<suite>)` in `tests/CMakeLists.txt`.
|
||||
- A `doc` CMake target builds Doxygen docs when Doxygen is installed.
|
||||
|
||||
### 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"`
|
||||
## Architecture
|
||||
|
||||
### 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 { ... }`)
|
||||
- **Module header/source split is non-obvious**: public headers of feature modules live in `libs/main/<module>/`, their sources in `libs/<module>/` (e.g. `libs/main/crypt/picrypt.h` + `libs/crypt/picrypt.cpp`). All of `libs/main/**` compiles into the `pip` target.
|
||||
- `libs/main/` core areas: `core` (PIObject, events), `containers`, `types`, `text`, `math`, `thread`, `system`, `io_devices`, `serialization`, `units`, `geo`, `resources`, `introspection`.
|
||||
- Bundled in `3rd/`: PCRE2 (built 16-bit static only), BLAKE2, SipHash, Lua + LuaBridge, paho.mqtt.c.
|
||||
- Feature-flag macros (`PIP_HAS_*`, `PIP_<MODULE>_EXPORT`, ...) are defined per-target by CMake; guard platform-specific code with them, not raw OS macros where a flag exists.
|
||||
- Non-Android POSIX builds use `-fno-exceptions`; MSVC uses `/EH-`. Avoid exceptions/RTTI in new code.
|
||||
|
||||
### 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)
|
||||
## Codegen tools (built under `utils/`)
|
||||
|
||||
### 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
|
||||
- `pip_cmg` — code model generator; downstream CMake: `pip_code_model(<out> files...)` macro.
|
||||
- `pip_rc` — resource compiler (`.conf` → C++); downstream CMake: `pip_resources(<out> file)`.
|
||||
- `pip_tr` — translation compiler (`lang/*.btf`); `deploy_tool` — version/deploy metadata.
|
||||
|
||||
### 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
|
||||
## Style
|
||||
|
||||
## 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()`
|
||||
- `clang-format` is the authority (`.clang-format`: 140 cols, 4-space indent, sorted case-sensitive includes, C++11). Run `clang-format -i <file>` on touched files.
|
||||
- Doxygen comments on public APIs are **bilingual**: `\~english` + `\~russian` lines (see `libs/main/core/piobject.h`).
|
||||
- Naming: classes `PascalCase`, methods/vars `camelCase`; files `pi<name>.h`, private `pi<name>_p.h`, tests `test<name>.cpp`.
|
||||
- `NO_COPY_CLASS(X)` disables copies; `PIP_EXPORT` marks exported symbols.
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
# Run all tests
|
||||
ctest
|
||||
## Repo notes
|
||||
|
||||
# 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
|
||||
- `AGENTS.md`, `build*/`, `plans/` are gitignored (local-only).
|
||||
- `.guides/BUGHUNT_GUIDE.md` (Russian) documents the bug-hunting workflow; `.guides/BUGHUNT_FALSE_POSITIVES.md` lists already-verified non-bugs — read it before flagging similar patterns.
|
||||
- `plans/` holds in-progress work plans (e.g. `wasm_build.md`); check before touching related code.
|
||||
|
||||
Reference in New Issue
Block a user