# 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

**First-time Setup:** When you run `init` for the first time on your system, IncludeCPP automatically registers the global `includecpp` command. After that, you can use `includecpp <command>` instead of `python -m includecpp <command>` (restart your terminal for Windows).

### 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. Detects classes, methods, constructors (including parametrized ones), functions, and structs.

### 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
includecpp init
```

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

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

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

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

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

```bash
includecpp rebuild [OPTIONS]
```

**Options:**
- `--clean` - Force clean rebuild (delete all cached files)
- `--keep` - Keep existing generator (skip automatic generator rebuild)
- `--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

**Note:** The generator is automatically rebuilt on each run to ensure it's up-to-date. Use `--keep` to skip this if you know the generator is current.

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

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

```bash
includecpp install <module_name>
includecpp install --list-all
```

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

### `update`
Update IncludeCPP to latest version or manage versions.

```bash
includecpp update              # Upgrade to latest version
includecpp update --version    # Show installed version
includecpp update --all        # List all available PyPI versions
includecpp update 2.4.0        # Install specific version
```

### `reboot`
Reinstall current IncludeCPP version (uninstall + install).

```bash
includecpp reboot
```

Useful for fixing corrupted installations.

### `get`
Display detailed module API information.

```bash
includecpp get <module_name>
```

Shows classes, methods, functions, structs with type information.

### `bug`
Report bugs to GitHub or view existing issues.

```bash
includecpp bug                 # Report a new bug
includecpp bug --get           # List open bugs from GitHub
```

### `--doc`
Show documentation with color highlighting.

```bash
includecpp --doc
```

Fetches and displays the latest README from PyPI.

## Plugin Definition Syntax (.cp files)

### Classes with Constructors

```
module CLASS(MyClass) {
    CONSTRUCTOR()                    # Default constructor
    CONSTRUCTOR(int, double)         # Parametrized constructor
    METHOD(doSomething)
    FIELD(value)
}
```

### Functions

```
module FUNCTION(calculate)
```

### Methods with Overload Support (v2.5+)

For overloaded methods (same name, different parameters):

```
module CLASS(Circle) {
    CONSTRUCTOR()
    METHOD_CONST(intersects, const Circle&)
    METHOD_CONST(intersects, const Rect&)
    METHOD(setRadius, double)
}
```

- `METHOD(name)` - Simple method (no overloads)
- `METHOD(name, type1, type2)` - Method with parameter types for overload resolution
- `METHOD_CONST(name, types...)` - Const method with overload support

The plugin generator auto-detects overloads and generates the correct format.

### Template Functions

```
module TEMPLATE_FUNC(maximum) TYPES(int, float, double)
```

### Structs

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

### Dependencies

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

### Multi-File Modules

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

## Features

### VSCode IntelliSense Support
Automatic `.pyi` stub generation for full IDE autocomplete.

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

Provides:
- Function signatures with types
- Class methods and attributes
- Constructor overloads
- Module-level exports
- Full VSCode/PyCharm autocomplete

### Parametrized Constructors (v2.4.3+)

C++ constructors with parameters are automatically bound:

```cpp
class Vector2D {
public:
    Vector2D();                      // Default
    Vector2D(double x, double y);    // Parametrized
};
```

```
geometry CLASS(Vector2D) {
    CONSTRUCTOR()
    CONSTRUCTOR(double, double)
    METHOD(length)
}
```

```python
v = geometry.Vector2D(3.0, 4.0)  # Works!
```

### 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
}
```

## Python API

### Simple Import (v2.6+)

```python
from includecpp import fast_list
result = fast_list.fast_sort([3, 1, 2])
```

### Classic API

```python
from includecpp import CppApi

api = CppApi(auto_update=True)
module = api.include("my_module")

# API Methods
api.need_update("module_name")  # Check if rebuild needed
api.update("module_name")       # Rebuild single module
api.list_modules()              # List available modules
api.exists("module_name")       # Check if module exists
```

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

---

**License:** MIT
**Version:** 2.6.1
**Repository:** https://github.com/liliassg/IncludeCPP
