# IncludeCPP

Write C++ code, use it in Python. Auto-generates pybind11 bindings.

```bash
pip install IncludeCPP
```

## Setup

```bash
includecpp init
```

Creates `cpp.proj`, `include/`, `plugins/`.

## Write C++ Code

**Put your code in `namespace includecpp`:**

```cpp
// include/fast_list.cpp
#include <vector>

namespace includecpp {

class FastList {
public:
    void append(int val) { data.push_back(val); }
    int get(int i) { return data[i]; }
private:
    std::vector<int> data;
};

int add(int a, int b) { return a + b; }

}  // namespace includecpp
```

Without `namespace includecpp`, your code won't be found.

## Generate Plugin

```bash
includecpp plugin fast_list include/fast_list.cpp
```

Creates `plugins/fast_list.cp` with detected classes, methods, functions.

## Build

```bash
includecpp rebuild
```

Or `includecpp build` (same thing).

## Use in Python

```python
from includecpp import fast_list

my_list = fast_list.FastList()
my_list.append(42)
print(fast_list.add(1, 2))  # 3
```

Or classic style:

```python
from includecpp import CppApi

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

## Commands
> Use `includecpp <command> --help` for details.
| Command | What it does |
|---------|--------------|
| `init` | Create project structure |
| `plugin <name> <files>` | Generate .cp from C++ |
| `auto <plugin>` | Regenerate .cp + build in one step |
| `rebuild` / `build` | Compile modules |
| `get <module>` | Show module API |
| `install <name>` | Install community module |
| `update` | Update IncludeCPP |
| `bug` | Report issue |
| `--doc` | Show docs |

## Build Options

### rebuild

```bash
includecpp rebuild                  # Standard build with caching
includecpp rebuild --clean          # Full rebuild, clear all caches
includecpp rebuild --fast           # Fast incremental (0.4s if unchanged)
includecpp rebuild --verbose        # See compiler output
includecpp rebuild -m crypto        # Rebuild specific module
includecpp rebuild -j 8             # 8 parallel jobs
includecpp rebuild --keep           # Keep generator between builds
includecpp rebuild --no-incremental # Force full recompilation
includecpp rebuild --this          # Build current dir as module 
```

### auto

Regenerate plugin .cp file and build in one step:

```bash
includecpp auto fast_list           # Regenerate .cp + default build
includecpp auto fast_list --fast    # Regenerate .cp + fast build
includecpp auto fast_list -v        # Verbose output
```

## Fast Mode

`--fast` uses object file caching for near-instant rebuilds:

| Scenario | Time |
|----------|------|
| No changes | ~0.4s |
| Source changed | ~5-10s (only changed files) |
| Full rebuild | ~30s |

```bash
includecpp rebuild --fast <statements like 'modulename' or '--all'
```

Caches:
- Object files (.o) - only recompile changed sources
- CMake generator detection - check once, reuse
- Compiler detection - check once, reuse

Clear all caches with `--clean`.

## Incompatible Flags

These flag combinations will show a clear error:

| Combination | Why |
|-------------|-----|
| `--fast` + `--no-incremental` | --fast requires incremental compilation |
| `--fast` + `--clean` | --fast uses caches, --clean deletes them |
| `--fast` + `--this` | --this rebuilds current dir, incompatible with --fast |
| `--incremental` + `--no-incremental` | Contradictory flags |

## Plugin Syntax (.cp files)

```
SOURCE(fast_list.cpp) fast_list

PUBLIC:

fast_list CLASS(FastList) {
    CONSTRUCTOR()
    METHOD(append)
    METHOD(get)
}

fast_list FUNC(add)
```

### Overloaded Methods

```
MODULE CLASS(Circle) {
    METHOD_CONST(intersects, const Circle&)
    METHOD_CONST(intersects, const Rect&)
}
```

### Templates

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

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

### Dependencies

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

## VSCode Support

Generates `.pyi` stubs automatically. Full autocomplete works.

Enable in `cpp.proj`:

```json
{
  "CPI-IntelliSense": true
}
```

## cpp.proj

```json
{
  "project": "MyProject",
  "include": "/include",
  "plugins": "/plugins",
  "compiler": {
    "standard": "c++17",
    "optimization": "O3"
  }
}
```

## Requirements

- Python 3.8+
- C++ compiler (g++, clang++, MSVC)
- pybind11 (installed automatically)

## Performance

- **Object caching**: Only recompile changed .cpp → .o files
- **Generator caching**: CMake/compiler detection runs once
- **Parallel compilation**: Uses all CPU cores by default
- **SHA256 change detection**: Skip unchanged modules
- **Builds in AppData**: Source directory stays clean

## Changelog

### v2.9.10
- New `auto` command: regenerate .cp + build in one step
- `--fast` mode: 30s → 0.4s for unchanged builds
- Object file caching (.o files)
- CMake generator caching (detect once)
- Incompatible flag validation with clear errors
- Fixed `--info` pyd path detection

---

MIT License | v2.9.15 | [GitHub](https://github.com/liliassg/IncludeCPP)
