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

  **Example:**
  ```bash
  includecpp rebuild
  includecpp plugin my_module include/module.cpp
  ```

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

  ## Python API

  ### Selective Module Updates

  ```python
  from includecpp import CppApi

  api = CppApi()

  if api.need_update("crypto"):
      api.update("crypto")

  crypto = api.include("crypto")
  ```

  ### Auto-Update on Include

  ```python
  api = CppApi(auto_update=True)
  crypto = api.include("crypto")
  ```

  ### API Methods

  - **`need_update(module_name) -> bool`** - Check if source is newer than build
  - **`update(module_name)`** - Rebuild single module
  - **`include(module_name, auto_update=None)`** - Load module with optional auto-rebuild
  - **`list_modules()`** - List all available modules
  - **`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

  ## 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.2.1
  **Status:** Production Ready
  **Repository:** https://github.com/liliassg/IncludeCPP
