Skip to content

README.md

Latest commit

 

History

History
183 lines (140 loc) · 8.36 KB

README.md

File metadata and controls

183 lines (140 loc) · 8.36 KB
Raw

UTF Strings - Cross-Platform C++23 Library

CI/CD Pipeline SAST Security Scanning CodeQL Security Analysis Extended Fuzz Testing Release Validation

C++23 CMake Conan License

Linux Windows macOS

Performance Security Quality

Modern C++23 UTF utilities (UTF-8/16/32) with explicit endianness policy and comprehensive testing.

Cross-Platform Support:

  • Linux: GCC 13+ or Clang 18+
  • Windows: MSVC 2022 or Clang-CL 16+
  • macOS: Clang 16+ (Apple Clang or LLVM)

Key Features:

  • 🚀 Single Bootstrap Configuration - One command for complete setup
  • 🔒 Security Hardened - Stack protection, ASLR, DEP, Control Flow Integrity
  • ⚡ Performance Optimized - LTO, native CPU optimization, vectorization
  • 🧪 Comprehensive Testing - Unit tests, fuzz testing, sanitizers, benchmarks
  • 🎯 Code Quality - clang-format integration, extensive warnings, static analysis

Integrated Security Scanning:

  • 🛡️ SAST Scanning - Trivy, Checkov, Gitleaks, Cppcheck, Semgrep (all-in-one workflow)
  • 🔍 CodeQL Analysis - Advanced semantic security analysis
  • 🚨 Automated Security Reports - All findings uploaded to GitHub Security tab
  • 📊 Configurable Intensity - Basic/Comprehensive/Deep security scanning levels

Quick Start

Automated Setup (Recommended)

Linux/macOS:

./bootstrap_cmake.sh                 # Auto-detect compiler and full setup
./bootstrap_cmake.sh --compiler gcc  # Force GCC 
./bootstrap_cmake.sh --compiler clang # Force Clang

Windows (cmd/PowerShell):

bootstrap_cmake.bat                  # Auto-detect and full setup

That's it! The bootstrap script will:

  • ✅ Detect your platform and available compilers
  • ✅ Install missing tools (CMake, Conan, clang-format)
  • ✅ Configure optimized builds (Debug + Release)
  • ✅ Run comprehensive tests and benchmarks
  • ✅ Set up development environment

Manual Setup (Advanced)

If you prefer manual control:

# Install dependencies
conan install . -s build_type=Debug   --output-folder=build --build=missing
conan install . -s build_type=Release --output-folder=build --build=missing

# Configure (using presets)
cmake --preset conan-debug    # Debug build
cmake --preset conan-release  # Release build

# Build
cmake --build --preset conan-debug --parallel
cmake --build --preset conan-release --parallel

# Test
build/Debug/utf_strings-tests      # Linux/macOS
build\Debug\utf_strings-tests.exe  # Windows

# Benchmark  
build/build/utf_strings-bench --benchmark_min_time=0.1s

Advanced Compiler Configuration

The build system supports fine-grained compiler control through external flags:

# Standard optimized build
cmake --preset conan-release \
  -DCOMPILER_TYPE=GCC \
  -DUSE_LTO=ON \
  -DUSE_NATIVE_ARCH=ON \
  -DENABLE_SHARED_LIBRARY=ON

# Maximum performance build (Clang with libc++)
cmake --preset conan-release \
  -DCOMPILER_TYPE=CLANG \
  -DUSE_LTO=ON \
  -DUSE_NATIVE_ARCH=ON \
  -DUSE_LIBC_PLUS_PLUS=ON \
  -DENABLE_SHARED_LIBRARY=ON

# Debug-friendly build (no aggressive optimizations)
cmake --preset conan-debug \
  -DCOMPILER_TYPE=CLANG \
  -DUSE_LTO=OFF \
  -DUSE_NATIVE_ARCH=OFF \
  -DENABLE_SHARED_LIBRARY=OFF

Available Configuration Flags:

  • COMPILER_TYPE: GCC|CLANG|MSVC - Explicit compiler identification
  • USE_LTO: ON|OFF - Link Time Optimization
  • USE_NATIVE_ARCH: ON|OFF - Native CPU optimization (-march=native)
  • USE_MSVC_LTO: ON|OFF - MSVC-specific LTO flags (/LTCG, /GL)
  • USE_LIBC_PLUS_PLUS: ON|OFF - Use libc++ instead of libstdc++ (Clang only)
  • ENABLE_SHARED_LIBRARY: ON|OFF - Build shared libraries

🤖 AI Assistant Integration

This project includes comprehensive context files to help AI assistants (ChatGPT, Claude, GitHub Copilot) provide accurate assistance:

Context Files

  • .ai-context - Complete project overview, standards, and guidelines
  • .copilot-instructions.md - GitHub Copilot-specific coding patterns and conventions

For Best AI Assistance

When working with AI assistants on this project:

  1. Reference the context: "Use the project context from .ai-context"
  2. Specify the domain: "This is for the UTF Strings C++23 library"
  3. Mention requirements: "Follow the project's C++23 standards and UTF handling patterns"
  4. Ask for tests: "Include appropriate unit tests and consider fuzz testing"

Common AI Prompts

# For code generation
"Generate a UTF-8 to UTF-16 converter following the UTF Strings project patterns in .ai-context"

# For debugging  
"Help debug this UTF conversion issue, considering the project context and C++23 standards"

# For optimization
"Optimize this UTF processing code for performance, following the project's benchmarking approach"

# For testing
"Create comprehensive tests for this UTF function, including edge cases and fuzz targets"

The AI context files ensure consistent, project-appropriate assistance across all AI platforms! 🚀

Code Quality & Reviews

This project maintains high standards for production-ready C++ code:

Mandatory Code Reviews

  • 📋 Code Review Guidelines - Comprehensive review parameters for all code changes
  • ⚡ Performance Analysis - Efficiency, algorithmic complexity, optimization opportunities
  • 🔒 Security Analysis - Memory safety, undefined behavior, vulnerability assessment
  • 🐛 Correctness Validation - Edge cases, error handling, logic verification
  • 🚀 Modern C++23 Standards - Best practices, proper feature usage, API design

Review Standards

Every change must meet:

  • 🔴 Zero Critical Issues - No security vulnerabilities, undefined behavior, or crashes
  • 🟡 Address Important Issues - Performance and correctness concerns resolved
  • ✅ Production Ready - Code must be deployable to production environments

Development Workflow

  1. Pre-Push Review - Complete comprehensive review using guidelines
  2. CI Validation - All automated tests, security scans, and quality checks pass
  3. Peer Review - Team review focusing on design and maintainability
  4. Integration - Merge only after all standards are met

See CONTRIBUTING.md for complete development guidelines.