Metadata-Version: 2.3
Name: pycpp_tools
Version: 0.7.0
Summary: A utility to initialize basic CMake C++ / pybind11 projects.
Author: R.E.
Author-email: R.E. <redelephant@foxmail.com>
License: MIT
Requires-Dist: pybind11
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# pycpp-tools

A command-line utility to initialize basic CMake C++ / pybind11 / Godot GDExtension projects.

## Features

- Initialize a CMake C++ project (CMake 3.30, C++23, Ninja, Conan)
- Initialize a pure C project (`--pure-c`)
- Initialize a pybind11 project (`--pybind11`)
- Initialize a Godot GDExtension project (`--godot`)
- Generate VS Code `tasks.json` / `launch.json` (CodeLLDB + clangd workflow)

## Installation

```bash
pip install .
# or editable mode
pip install -e .
```

After installation, the `pycpp` command is available.

## Build workflow (CMake / pure-c / pybind11)

These project types use **Conan 2** for C++ dependencies and CMake presets for configure.

Typical flow (VS Code tasks or equivalent CLI):

1. **conan** — install Debug and Release dependencies
2. **config-debug** or **config-release** — configure with the matching preset (run conan yourself first if needed)
3. **build** — `cmake --build build`
4. **run** — depends on **build**

```bash
# after editing conanfile.py requirements, refresh deps:
# VS Code task: conan

cmake --preset conan-debug    # or: conan-release
cmake --build build
```

Add C++ packages in `conanfile.py` (`requirements()`). For pybind11 projects, pybind11 itself still comes from the current Python environment (`[tool.pycpp].pybind11_dir` in `pyproject.toml`); Conan is for other C++ deps.

## Usage

### CMake C++ Project

```bash
pycpp init --name myproject
```

Creates a minimal C++23 app with Conan + VS Code tasks (`conan`, `config-debug`, `config-release`, `build`, `run`).

### Pure C Project

```bash
pycpp init --name myproject --pure-c
```

Same Conan / tasks workflow as the CMake C++ template.

### Godot GDExtension Project

Run in an empty extension source directory (`init` writes into the current working directory):

```bash
pycpp init --name demo --godot
```

Defaults (override via CLI or cmake `-D`):

- `GODOT_CPP_DIR`: `E:/work_data/third_libs/godot-cpp-10.0.0-rc1`
- `GODOTCPP_API_VERSION`: `4.6`

```bash
pycpp init --name demo --godot \
  --godot-cpp-dir "E:/work_data/third_libs/godot-cpp-10.0.0-rc1" \
  --godot-api-version "4.6"
```

Build with the VS Code **cmake: configure & build (debug)** or **(release)** tasks. Output goes under `bin/`.

Godot projects do not use the Conan workflow above.

#### Attach to an existing Godot project (`--attach`)

```bash
pycpp init --name gdes_demo --godot --attach "../my-godot-project"
```

`--attach` accepts a relative path (from the extension directory). This also writes a `.code-workspace` and `.gdextension` into the Godot project, and points build output at that project's `bin/`.

If `.gdextension` already exists, you are asked whether to overwrite (default **no**).

Example outputs:

- debug: `<project>/bin/libgdes_demo.windows.template_debug.x86_64.dll`
- release: `<project>/bin/libgdes_demo.windows.template_release.x86_64.dll`

Open `<project>/gdes_demo.code-workspace` in VS Code to edit the Godot project and extension together.

### Pybind11 Project

```bash
pycpp init --name demo --pybind11
```

Naming:

- `--name`: C++ extension module name (default: `demo`)
- Python package: `py` + name (e.g. `pydemo` → `src/pydemo/`)
- Import: `from pydemo import demo`

Useful files after init:

- `cpp-src/` — C++ sources
- `src/<package>/` — Python package (extension binary is built here)
- `pyproject.toml` — package metadata and `[tool.pycpp]` paths
- `scripts/cmake-config.py` — `debug` / `release` configure helpers
- `scripts/clear.py` / `scripts/package.py` — clean and package
- VS Code tasks: `conan`, `config-debug`, `config-release`, `build`, `run`, `clear`, `package`

`[tool.pycpp]` (set at init from the current environment):

```toml
[tool.pycpp]
python_dir = "..."
pybind11_dir = "..."
python_version = "3.13"
cxx_standard = 23
```

After changing toml, re-run **config-debug** / **config-release** (or **package**).

#### Develop and debug

```bash
# VS Code: conan → config-debug (or config-release) → build → run
python scripts/cmake-config.py debug
cmake --build build
pip install -e .
python test.py
```

Use `pip install -e .` so imports and IDE hints work without `sys.path` hacks.

#### Package

```bash
python scripts/package.py
# or VS Code task: package
```

This clears, refreshes Conan deps, configures **release**, builds, then runs `python -m build` with the interpreter from `[tool.pycpp].python_dir` (so wheel tags match). Requires the `build` package in that environment.

### CLI options

- `--name <name>`: project / module name
- `--pybind11`: pybind11 project
- `--pure-c`: pure C project
- `--godot`: Godot GDExtension project
- `--godot-cpp-dir`: path to godot-cpp (with `--godot`)
- `--godot-api-version`: target Godot API version (with `--godot`)
- `--attach <dir>`: link to an existing Godot project (with `--godot`)
- `--inplace-vscode`: overwrite existing `.vscode` tasks/launch files

## Requirements

- Python 3.13+ (for this tool)
- Conan 2 (for cmake / pure-c / pybind11 projects)
- CMake 3.30+ (3.23+ recommended for presets)
- C++23-capable compiler (default: clang-cl)
- Ninja
- VS Code extensions:
  - [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) — C/C++ debugging
  - [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) — C/C++ IntelliSense

## License

MIT License

## Author

R.E. (redelephant@foxmail.com)
