163 lines
4.4 KiB
Markdown
163 lines
4.4 KiB
Markdown
# AGENTS.md - Agent Guidelines for PIP
|
|
|
|
This file provides guidance for agentic coding agents working on the PIP (Platform Independent Primitives) codebase.
|
|
|
|
## Project Overview
|
|
|
|
PIP is a C++ cross-platform library providing platform-independent abstractions for:
|
|
- Core/Types: Strings, variants, containers, datetime, networks
|
|
- Threading: Mutexes, semaphores, thread pools, timers
|
|
- I/O: Files, serial, CAN, GPIO, SPI, Ethernet
|
|
- Math: Vectors, matrices, FFT, quaternions
|
|
- Crypto: MD5, SHA, BLAKE2, SipHash
|
|
- Compression: zlib support
|
|
- HTTP: Client and server support
|
|
- Serialization: JSON, binary, XML
|
|
|
|
## Build Commands
|
|
|
|
### Basic Build
|
|
```bash
|
|
cmake -B build
|
|
cmake --build build
|
|
```
|
|
|
|
### Build with Tests
|
|
```bash
|
|
cmake -B build -DTESTS=ON
|
|
cmake --build build
|
|
```
|
|
|
|
### Run Tests
|
|
```bash
|
|
ctest --test-dir build/tests # Run all tests
|
|
ctest --test-dir build/tests -R <regex> # Run specific tests matching regex
|
|
ctest --test-dir build/tests -V # Verbose output
|
|
```
|
|
|
|
To run a single test:
|
|
```bash
|
|
# Build the test executable, then run directly:
|
|
./build/tests/pip_<test_name>_test
|
|
# Or use ctest with specific test name
|
|
ctest --test-dir build/tests -R "TestName"
|
|
```
|
|
|
|
### Other Commands
|
|
```bash
|
|
cmake --build build --target clean # Clean build
|
|
cmake --install build_pip # Install
|
|
cmake --build build --target doc # Build documentation
|
|
```
|
|
|
|
### Build Options
|
|
```bash
|
|
-DTESTS=ON # Build tests
|
|
-DCOVERAGE=ON # Build with coverage
|
|
-DICU=ON # ICU support for codepage conversion
|
|
-DSTD_IOSTREAM=ON # std::iostream operators support
|
|
-DINTROSPECTION=ON # Build with introspection
|
|
-DPIP_BUILD_CRYPT=ON # Crypt module (requires libsodium)
|
|
-DPIP_BUILD_FFTW=ON # FFT support
|
|
```
|
|
|
|
## Code Style Guidelines
|
|
|
|
### File Organization
|
|
- Header files: `libs/main/**/*.h`
|
|
- Source files: `libs/main/**/*.cpp`
|
|
- Private headers: `*_p.h`
|
|
- Tests: `tests/<module>/`
|
|
- Use Doxygen comments (`/*! ... */`) for documentation with `\brief`, `\param`, `\return`
|
|
|
|
### Naming Conventions
|
|
- **Classes**: PascalCase with `PI` prefix (e.g., `PIString`, `PIByteArray`, `PIVariant`)
|
|
- **Functions**: camelCase (e.g., `toAscii()`, `isEmpty()`, `append()`)
|
|
- **Member variables**: snake_case, or just lowercase (e.g., `array_size`, `count`)
|
|
- **Constants**: PascalCase or UPPER_SNAKE_CASE
|
|
- **Enums**: PascalCase for enum names and values
|
|
|
|
### Code Formatting
|
|
- **Indentation**: Use tabs (4 spaces equivalent) or spaces - match existing code
|
|
- **Braces**: Opening brace on same line for functions, new line for namespaces/classes
|
|
- **Includes**: System includes first, then project headers
|
|
- **Use forward declarations** where possible to reduce compile times
|
|
- **Use `nullptr`** instead of `NULL`
|
|
|
|
### C++ Standards
|
|
- C++11 standard (enforced in CMakeLists.txt)
|
|
- Use `override` keyword for virtual function overrides
|
|
- Use `explicit` for single-argument constructors
|
|
- Use `const` member functions where applicable
|
|
- Use range-based `for` loops when possible
|
|
|
|
### Error Handling
|
|
- Return error codes
|
|
- DO NOT USE exceptions
|
|
- Use `piCerr` and `piCout` for error messages
|
|
- Check for null pointers where appropriate
|
|
|
|
### Module Structure
|
|
|
|
Each module typically has:
|
|
1. Public header: `pip_<module>.h` or `<classname>.h`
|
|
2. Private implementation: `<classname>.cpp` or `<classname>_p.cpp`
|
|
3. Use `PIP_EXPORT` macro for symbols that need to be exported from the library
|
|
|
|
Example class structure:
|
|
```cpp
|
|
// header.h
|
|
#ifndef MODULE_CLASSNAME_H
|
|
#define MODULE_CLASSNAME_H
|
|
|
|
#include "pip_export.h"
|
|
|
|
class PIP_EXPORT ClassName {
|
|
public:
|
|
ClassName();
|
|
~ClassName();
|
|
|
|
void doSomething();
|
|
bool isValid() const;
|
|
|
|
private:
|
|
void privateMethod();
|
|
int data;
|
|
};
|
|
|
|
#endif // MODULE_CLASSNAME_H
|
|
|
|
// source.cpp
|
|
#include "header.h"
|
|
#include "piincludes_p.h"
|
|
|
|
ClassName::ClassName() : data(0) {}
|
|
```
|
|
|
|
### Testing
|
|
- Use Google Test framework
|
|
- Test files go in `tests/<module>/`
|
|
- Use `TEST(TestSuite, TestName)` or `TEST_F(TestFixture, TestName)` for test cases
|
|
- Use `ASSERT_*` for fatal failures, `EXPECT_*` for non-fatal
|
|
- Test naming: `<ClassName>_<TestDescription>`
|
|
|
|
Example:
|
|
```cpp
|
|
#include "pistring.h"
|
|
#include "gtest/gtest.h"
|
|
|
|
TEST(PIString_Tests, constructor_empty) {
|
|
PIString str;
|
|
ASSERT_TRUE(str.isEmpty());
|
|
}
|
|
```
|
|
|
|
### Module Dependencies
|
|
- Main library: `libs/main/`
|
|
- Third-party: `3rd/`
|
|
- Utils: `utils/`
|
|
|
|
### Key Files
|
|
- `CMakeLists.txt` - Main build configuration
|
|
- `tests/CMakeLists.txt` - Test configuration
|