pip/AGENTS.md

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

cmake -B build
cmake --build build

Build with Tests

cmake -B build -DTESTS=ON
cmake --build build

Run Tests

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:

# 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

cmake --build build --target clean    # Clean build
cmake --install build_pip             # Install
cmake --build build --target doc      # Build documentation

Build Options

-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:

// 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:

#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

Lint/Format Commands

• For formatting, use clang-format with .clang-format in repo root