# 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