# IncludeCPP

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

```bash
pip install IncludeCPP
```

# First Steps

## Project Setup

```bash
includecpp init
```

Creates:
- `cpp.proj` - project configuration
- `include/` - your C++ source files
- `plugins/` - generated binding definitions

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

The parser only scans code inside `namespace includecpp`. Everything else is ignored.

## Generate Bindings

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

This runs a C++ parser that:
1. Scans your source files for classes, methods, functions
2. Extracts signatures, return types, parameter names
3. Generates `plugins/fast_list.cp` with binding instructions

## Build

```bash
includecpp rebuild
```

Compiles your C++ into a Python extension module (`.pyd` on Windows, `.so` on Linux/Mac).

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

Alternative syntax:

```python
from includecpp import CppApi

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

# How to Start

## Minimal Example

```bash
# 1. Create project
mkdir myproject && cd myproject
includecpp init

# 2. Write C++ (include/math.cpp)
cat > include/math.cpp << 'EOF'
namespace includecpp {
    int square(int x) { return x * x; }
}
EOF

# 3. Generate plugin
includecpp plugin math include/math.cpp

# 4. Build
includecpp rebuild

# 5. Use
python -c "from includecpp import math; print(math.square(7))"
```

## Development Workflow

For active development, use `auto`:

```bash
includecpp auto math
```

This regenerates the `.cp` file from source and rebuilds in one command.

For fastest iteration:

```bash
includecpp rebuild --fast
```

Skips unchanged files. ~0.4s when nothing changed.

# How IncludeCPP Works

## Architecture

```
Your C++ Source            Plugin File (.cp)           Python Module
include/math.cpp    --->   plugins/math.cp     --->    math.cpXXX.pyd
     ^                           ^                          ^
     |                           |                          |
  C++ parser              Binding config             pybind11 compiled
  extracts API            (editable)                 extension
```

## The Parser

The C++ parser (`parser.cpp`) runs as a compiled executable. It:

1. Tokenizes your C++ source files
2. Identifies the `namespace includecpp` block
3. Extracts:
   - Class names and inheritance
   - Method signatures (name, return type, parameters)
   - Function signatures
   - Template instantiations
   - Const/static qualifiers
4. Outputs structured binding instructions to `.cp` files

## Plugin Files (.cp)

The `.cp` format is a declarative binding specification:

```
SOURCE(math.cpp) math

PUBLIC(
    math CLASS(Calculator) {
        CONSTRUCTOR()
        CONSTRUCTOR(int)
        METHOD(add)
        METHOD_CONST(getValue)
        FIELD(value)
    }

    math FUNC(square)
    math TEMPLATE_FUNC(maximum) TYPES(int, float, double)
)
```

Key directives:
- `SOURCE(file.cpp) module_name` - links source to module
- `PUBLIC(...)` - defines public bindings
- `CLASS(Name)` - expose a class
- `STRUCT(Name)` - expose a struct
- `FUNC(name)` - expose a free function
- `METHOD(name)` - expose a class method
- `METHOD_CONST(name, signature)` - for overloaded methods
- `TEMPLATE_FUNC(name) TYPES(...)` - instantiate template
- `CONSTRUCTOR(args)` - expose constructor
- `FIELD(name)` - expose member variable
- `DEPENDS(mod1, mod2)` - declare module dependencies

## Build System

The build manager:

1. Reads `cpp.proj` configuration
2. Parses all `.cp` files in `plugins/`
3. Generates pybind11 binding code
4. Compiles using CMake with detected compiler (MSVC, GCC, Clang)
5. Places output in `~/.includecpp/builds/` (not in your project)
6. Creates a registry so Python can find modules

Caching layers:
- **Object files**: Only recompile changed `.cpp` files
- **Generator cache**: Compiler/CMake detection runs once
- **SHA256 hashes**: Skip unchanged modules entirely

# CLI Reference

Use `includecpp <command> --help` for details.

| Command | Description |
|---------|-------------|
| `init` | Create project structure |
| `plugin <name> <files>` | Generate .cp from C++ sources |
| `auto <plugin>` | Regenerate .cp and rebuild |
| `auto --all` | Regenerate and rebuild all plugins |
| `auto --all -x <name>` | All plugins except specified |
| `fix <module>` | Analyze C++ code for issues |
| `fix --all` | Analyze all modules |
| `fix --undo` | Revert last fix changes |
| `fix --ai <module>` | AI-enhanced code analysis |
| `ai key <key>` | Set OpenAI API key |
| `ai enable` | Enable AI features |
| `ai disable` | Disable AI features |
| `ai model --list` | List available models |
| `ai model set <name>` | Set active model |
| `ai --info` | Show AI configuration and usage |
| `ai optimize <module>` | AI code optimization |
| `ai optimize --agent "<task>"` | Custom AI task |
| `ai ask "<question>"` | Ask about project with full context |
| `ai ask "<question>" <module>` | Ask about specific module |
| `ai edit "<task>"` | Edit code with AI assistance |
| `ai edit "<task>" --think2` | Thorough edit mode |
| `ai undo` | Restore files after AI changes |
| `rebuild` / `build` | Compile all modules |
| `get <module>` | Show module API (classes, methods, functions) |
| `install <name>` | Install community module |
| `update` | Update IncludeCPP |
| `bug` | Report an issue |
| `--doc` | Show documentation |
| `--changelog` | Show latest version changelog |

## Build Flags

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

## Fast Mode

`--fast` enables object file caching:

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

Clear caches with `--clean`.

## Incompatible Flag Combinations

| Flags | Reason |
|-------|--------|
| `--fast` + `--no-incremental` | Fast mode requires incremental |
| `--fast` + `--clean` | Fast uses caches, clean deletes them |
| `--fast` + `--this` | Not supported together |
| `--incremental` + `--no-incremental` | Contradictory |

# Advanced Features

## AI Integration

IncludeCPP integrates with OpenAI for intelligent code analysis and optimization.

### Setup

```bash
includecpp ai key sk-your-api-key-here
includecpp ai enable
```

### Available Models

```bash
includecpp ai model --list
```

- `gpt-5` (default) - 256k context
- `gpt-5-nano` - 32k context, fast
- `gpt-4o` - 128k context
- `gpt-4-turbo` - 128k context
- `gpt-3.5-turbo` - 16k context

### AI-Enhanced Fix

```bash
includecpp fix --ai mymodule
includecpp fix --ai --all
```

Sends source files to AI for analysis, suggests improvements while preserving all existing functions.

### AI Optimize

```bash
includecpp ai optimize mymodule                        # Optimize module sources
includecpp ai optimize --file src/utils.cpp            # Optimize specific files
includecpp ai optimize --agent mymodule "add SIMD"     # Custom task
```

### AI Ask

Ask questions about your project with full context awareness:

```bash
includecpp ai ask "where is collision detection?"              # Search all modules
includecpp ai ask "how does chunk generation work?" chunk_utils  # Specific module
includecpp ai ask "explain the biome system" --file include/biomes.cpp
includecpp ai ask "list all public methods" --all -x tests      # All except tests
```

Supports: module name, --file, --all, -x/--exclude

### AI Edit

Edit code with AI assistance:

```bash
includecpp ai edit "add logging to all methods" collision
includecpp ai edit "optimize the loop" --file include/utils.cpp
includecpp ai edit "add error handling" --all --think2          # Thorough mode
```

Flags:
- `--file` - specific files
- `--all` - all modules
- `-x/--exclude` - exclude modules
- `--think2` - thorough analysis (more tokens)

### Build Error Analysis

When AI is enabled and `rebuild` fails, the build error is automatically analyzed:
- Root cause identification
- Code fix suggestions
- Prevention tips

### Configuration

```bash
includecpp ai --info          # Show status, model, usage stats
includecpp ai disable         # Disable without removing key
```

API key stored in `~/.includecpp/.secret`.

## Overloaded Methods

Specify the signature to disambiguate:

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

## Template Instantiation

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

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

Generates `maximum_int`, `maximum_float`, `maximum_double` and `Point_int`, `Point_float`.

## Module Dependencies

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

Ensures dependent modules build first.

## VSCode IntelliSense

Generates `.pyi` stub files for autocomplete. Enable in `cpp.proj`:

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

# Configuration

## cpp.proj

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

Options:
- `project` - project name
- `include` - C++ source directory
- `plugins` - plugin file directory
- `compiler.standard` - C++ standard (c++11, c++14, c++17, c++20)
- `compiler.optimization` - optimization level (O0, O1, O2, O3)

# Requirements

- Python 3.8+
- C++ compiler (g++, clang++, MSVC)
- pybind11 (installed automatically)
- CMake (for build generation)

# Changelog

## v3.2.4
- Fixed UTF-16/BOM encoding error in plugin command (source file reading)

## v3.2.3
- Fixed FIELD() syntax: now outputs `FIELD(name)` not `FIELD(type, name)`
- Fixed documentation: PUBLIC() not PUBLIC:
- Fixed AI context to match actual .cp syntax

## v3.2.2
- Plugin command now detects comma-separated field declarations (e.g., `double x, y, z;` generates 3 FIELD entries)
- Fixed `ai optimize` timeout for multi-file operations (increased to 5 minutes)
- AI `ask` now extracts relevant CLI implementation when asking about commands/flags

## v3.2.1
- Fixed encoding error in `ai ask` output on Windows (GPT Unicode characters like non-breaking hyphen)

## v3.2.0
- AI context limits: 3K (standard), 5K (`--think`), 10K (`--think2`), 25K (`--think3`) lines
- AI now has full IncludeCPP knowledge (namespace requirements, .cp format, common errors)
- New `--think` flag for short planning mode (5K context)
- New `--websearch` flag for web research (requires Brave API)
- Daily token limit: 220K default, auto-resets at midnight
- New commands: `ai limit`, `ai limit set <N>`, `ai limit get`
- Fixed "No changes needed" issue in `ai edit` (now more assertive)
- Improved `fix --ai` error detection with line numbers and error categorization
- Settings GUI now shows daily limit option
- Build info from AppData included in AI context

## v3.1.10
- Fixed diff view encoding on Windows (replaced Unicode box chars with ASCII)

## v3.1.9
- AI commands now show colored diff before confirmation prompts
- Renamed `--auto` to `--confirm` for AI confirmation skipping (`fix --confirm`, `ai edit --confirm`, `ai optimize --confirm`)
- Fixed Windows encoding errors (`'charmap' codec` issue)
- All file operations now use UTF-8 encoding explicitly

## v3.1.8
- `--think2` and `--think3` flags added to `ai ask` and `ai edit` commands
- Extended context and web research support for all AI commands
- Fixed `ai undo` command error

## v3.1.7
- `--auto-ai` flag for `rebuild`, `build`, and `auto` commands
- Auto-fix build errors with AI and retry automatically (max 3 attempts)
- AI has CLI access (can run `includecpp plugin <module>` for .cp regeneration)
- `--think2` for extended context (500 lines per file, careful analysis)
- `--think3` for max context + web research + planning mode (requires Brave API)
- `includecpp ai token --brave <TOKEN>` for Brave Search API
- `includecpp settings` opens PyQt6 settings panel (pip install PyQt6)
- Changes from `--auto-ai` can be reverted with `includecpp ai undo`

---

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