# IncludeCPP - Professional C++ Python Bindings

Professional C++ ↔ Python binding system with type-generic templates, native threading support, and maximum performance.

## Features

- **Type-Generic System**: Functions work with ANY type automatically
  ```python
  algorithms.fast_sort([1,2,3])      # int version
  algorithms.fast_sort([1.5, 2.3])   # float version
  algorithms.fast_sort(["a","b"])    # string version
  ```

- **Native Threading with GIL Release**: True parallelism
  ```python
  game = CPP.include("threading").GameEngine()
  CPP.threadThis(game)  # Runs in C++ thread with GIL released
  ```

- **Dynamic Configuration**: `cpp.proj` JSON configuration
- **AppData Build System**: Clean separation of project and build artifacts
- **CLI Tool**: `includecpp --rebuild` for easy building
- **Zero Overhead**: Template instantiation eliminates runtime overhead

## Installation

```bash
pip install IncludeCPP
```

## Quick Start

### 1. Initialize Project

```bash
cd YourProject
includecpp init
```

This creates:
- `cpp.proj` - Configuration file
- `include/` - Your C++ source files
- `plugins/` - Plugin definitions (.cp files)

### 2. Create C++ Module

**include/mymodule.cpp**:
```cpp
#include <vector>
#include <algorithm>

namespace includecpp {

std::vector<int> custom_sort(const std::vector<int>& data) {
    std::vector<int> result = data;
    std::sort(result.begin(), result.end());
    return result;
}

}
```

**plugins/mymodule.cp**:
```
SOURCE(include/mymodule.cpp) mymodule

PUBLIC(
    mymodule FUNC(custom_sort)
)
```

### 3. Build

```bash
includecpp --rebuild
```

Build artifacts go to:
- **Windows**: `%APPDATA%/YourProject&gcc-build-proj/`
- **Linux**: `~/.local/share/includecpp/YourProject&gcc-build-proj/`

### 4. Use in Python

```python
import IncludeCPP as cpp

CPP = cpp.CppApi()
CPP.noFeedback()  # Disable warnings

mymodule = CPP.include("mymodule")
result = mymodule.custom_sort([5, 2, 9, 1])
print(result)  # [1, 2, 5, 9]
```

## Type-Generic Templates

```python
# plugins/algorithms.cp
SOURCE(include/algorithms.cpp) && HEADER(include/algorithms.h) algorithms

PUBLIC(
    algorithms TEMPLATE_FUNC(fast_sort) TYPES(int, float, double, string)
)
```

## Configuration

**cpp.proj** (auto-created by `includecpp init`):
```json
{
  "project": "MyProject",
  "version": "1.0.0",
  "include": "/include",
  "plugins": "/plugins",
  "compiler": {
    "standard": "c++17",
    "optimization": "O3",
    "flags": ["-Wall", "-pthread"]
  }
}
```

## Requirements

- Python >= 3.8
- C++ compiler (g++, clang++, or MSVC)
- pybind11 >= 2.11.0
- CMake >= 3.15

## License

MIT License

## Links

- **Documentation**: https://includecpp.readthedocs.io
- **GitHub**: https://github.com/includecpp/includecpp
- **PyPI**: https://pypi.org/project/IncludeCPP

## Example: Complete Module

See the `examples/` directory for complete working examples including:
- Type-generic algorithms
- Threading with GIL release
- Map and Array containers
- Custom C++ classes
