# IncludeCPP - C++ Performance in Python, Zero Hassle

Write performance-critical code in C++, use it in Python like native modules. No boilerplate, no manual bindings, no complexity.

## Installation

```bash
pip install IncludeCPP
```

## Quick Start

### 1. Initialize Project
```bash
python -m includecpp init
```

Creates:
- `cpp.proj` - Configuration
- `include/` - C++ source files
- `plugins/` - Module definitions

### 2. Auto-Generate Plugin Definition

```bash
python -m includecpp plugin fast_list include/fast_list.cpp include/fast_list.h
```

Automatically generates `plugins/fast_list.cp` by analyzing your C++ code.

### 3. Build

```bash
python -m includecpp rebuild
```

### 4. Use in Python

```python
from includecpp import CppApi

api = CppApi()
fast_list = api.include("fast_list")

my_list = fast_list.FastList()
my_list.append(42)
```

## CLI Commands

### `init`
Initialize new IncludeCPP project.

```bash
python -m includecpp init
```

### `plugin`
Auto-generate `.cp` plugin definition from C++ files.

```bash
python -m includecpp plugin <name> <file1.cpp> [file2.h] [...]
```

**Options:**
- `-p, --private <func>` - Exclude function from public API

**Example:**
```bash
python -m includecpp plugin math_tools include/math.cpp include/math.h -p InternalHelper
```

### `rebuild`
Build or rebuild C++ modules.

```bash
python -m includecpp rebuild [OPTIONS]
```

**Options:**
- `--clean` - Force clean rebuild (ignore incremental cache)
- `--full` - Complete rebuild including generator and all caches
- `--verbose` - Detailed build output
- `--no-incremental` - Disable incremental builds
- `--parallel/--no-parallel` - Enable/disable parallel compilation (default: enabled)
- `-j, --jobs <N>` - Max parallel jobs (default: 4)
- `-m, --modules <name>` - Rebuild specific modules only

**Examples:**
```bash
python -m includecpp rebuild --full --verbose
python -m includecpp rebuild -m crypto -m networking
```

### `install`
Install community modules from GitHub.

```bash
python -m includecpp install <module_name>
```

Downloads from `https://github.com/liliassg/IncludeCPP/tree/main/minstall/<module_name>`

**Example:**
```bash
python -m includecpp install fast_list
python -m includecpp rebuild
```

## Features

### VSCode IntelliSense Support
Automatic type hint generation for full IDE autocomplete.

**Enable/Disable** in `cpp.proj`:
```json
{
  "CPI-IntelliSense": true
}
```

When enabled, `.pyi` stub files are generated during rebuild, providing:
- Function signatures
- Class methods and attributes
- Module-level exports
- Full VSCode autocomplete

### Template Structs (v2.0+)

```cpp
template<typename T>
struct Point {
    T x;
    T y;
};
```

```
geometry STRUCT(Point) TYPES(int, float) {
    FIELD(T, x)
    FIELD(T, y)
}
```

Auto-generates:
- `.to_dict()` method
- `.from_dict()` static method
- Full type hints

### Module Dependencies

```
DEPENDS(math_utils, geometry)
```

Build system handles dependency order automatically.

### Multi-File Modules

```
SOURCE(module.cpp helpers.cpp utils.cpp) my_module
```

### Incremental Builds

SHA256-based change detection. Only rebuilds modified modules.

### Cross-Platform

- Windows (MSVC, MinGW, g++)
- Linux (g++, clang++)
- macOS (clang++)

## Type Support

- **Basic:** `int`, `float`, `double`, `bool`, `string`
- **STL:** `vector`, `map`, `set`, `array`, `pair`
- **Custom:** Structs, classes, templates

## Configuration

`cpp.proj`:

```json
{
  "project": "MyProject",
  "version": "1.0.0",
  "include": "/include",
  "plugins": "/plugins",
  "compiler": {
    "standard": "c++17",
    "optimization": "O3",
    "flags": ["-Wall", "-pthread"]
  },
  "types": {
    "common": ["int", "float", "double", "string"]
  },
  "threading": {
    "enabled": true,
    "max_workers": 8
  },
  "CPI-IntelliSense": true
}
```

## Advanced Examples

### Class with Methods

```cpp
class Crypto {
public:
    std::string md5(const std::string& data);
    std::string sha256(const std::string& data);
};
```

```
crypto CLASS(Crypto) {
    METHOD(md5)
    METHOD(sha256)
}
```

```python
crypto = api.include("crypto")
hash = crypto.Crypto().md5("hello")
```

### Template Functions

```cpp
template<typename T>
T maximum(T a, T b) {
    return a > b ? a : b;
}
```

```
math TEMPLATE_FUNC(maximum) TYPES(int, float, string)
```

```python
math.maximum(10, 20)        # 20
math.maximum(1.5, 2.3)      # 2.3
math.maximum("a", "z")      # "z"
```

## Requirements

- **Python:** 3.8+
- **C++ Compiler:** g++, clang++, or MSVC
- **CMake:** 3.15+ (optional, falls back to direct compilation)
- **pybind11:** Installed automatically

## Build System

- **AppData Storage:** Builds stored in `%APPDATA%\IncludeCPP` (Windows) or `~/.local/share/includecpp` (Linux)
- **Clean Projects:** Source directory stays clean
- **Incremental:** SHA256-based change detection
- **Parallel:** Multi-threaded compilation
- **Caching:** Reuses unchanged binaries

## Why IncludeCPP?

**For developers who:**
- Need C++ performance with Python productivity
- Don't want complex build configurations
- Value fast iteration and simple workflows
- Want production-ready bindings without boilerplate

**Not for:**
- Pure Python projects
- When CPython extensions are overkill
- Projects requiring custom build pipelines

---

**License:** MIT
**Version:** 2.0.5
**Status:** Production Ready
**Repository:** https://github.com/liliassg/IncludeCPP
