diff --git a/AGENTS.md b/AGENTS.md index ff968768..0c982375 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 `/cmake-src` (the source tree has `cmake/PIPMacros.cmake` but not `SHSTKMacros.cmake`). Reuse an existing build dir when possible; a fresh `cmake -B ` 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_` — 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 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_` (`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 ` 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.h` (e.g., `piobject.h`, `pistring.h`) -- Private headers: `pi_p.h` (e.g., `piobject_p.h`) -- Test files: `test.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__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//test.cpp`, added via `pip_test()` 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.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//`, their sources in `libs//` (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__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( files...)` macro. +- `pip_rc` — resource compiler (`.conf` → C++); downstream CMake: `pip_resources( 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//test.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 ` 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.h`, private `pi_p.h`, tests `test.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 -│ └── ... -└── / # 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.