Metadata-Version: 2.3
Name: pycpp_tools
Version: 0.5.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)
- 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.

## Usage

### CMake C++ Project

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

Generates: `src/main.cpp`, `CMakeLists.txt`, `.vscode/tasks.json` (`config` / `build` / `run`), `.vscode/launch.json`.

### Pure C Project

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

### Godot GDExtension Project

在**目标空目录**下执行（`init` 会在当前工作目录生成文件）：

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

生成内容：

| Path | Description |
|------|-------------|
| `CMakeLists.txt` | 链接 godot-cpp，扩展库输出到 `bin/` |
| `src/wrapper.cpp` | 示例 GDExtension（旋转 Sprite2D） |
| `.vscode/tasks.json` | debug / release 两套 cmake configure + build |
| `.gitignore` | 忽略 `build/`、`bin/` 等 |

默认 `CMakeLists.txt` 中的路径（可用 CLI 覆盖，或在 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"
```

构建：VS Code 任务 **cmake: configure & build (debug)** 或 **(release)**，产物在 `bin/`。

### Pybind11 Project

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

Naming:

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

Generated layout:

| Path | Description |
|------|-------------|
| `cpp-src/pywrapper.cpp` | C++ / pybind11 sources |
| `src/pydemo/__init__.py` | Empty package init |
| `src/pydemo/demo.pyi` | Stub for the extension module |
| `CMakeLists.txt` | Extension output under `src/<package>/`; paths injected via `-D` |
| `pyproject.toml` | `[tool.pycpp]`, `package-data`; `requires-python = "==X.Y.*"` |
| `setup.py` | Marks a binary distribution so the wheel gets `cp3xx-<plat>` tags |
| `scripts/cmake-config.py` | Reads toml and passes `-D` flags to cmake |
| `scripts/clear.py` | Cleans build artifacts and extension binaries |
| `scripts/package.py` | clear → config → cmake build → `python -m build` (uses Python from `[tool.pycpp].python_dir`) |
| `test.py` | `from pydemo import demo` |
| `.vscode/tasks.json` | `config` / `build` / `run` / `clear` / `package` |
| `.vscode/launch.json` | debugpy + CodeLLDB |

Default `[tool.pycpp]` fields:

```toml
[tool.pycpp]
python_dir = "..."          # current env sys.prefix
pybind11_dir = "..."        # .../share/cmake/pybind11
python_version = "3.13"
build_type = "Release"
cxx_standard = 23
cxx_compile = "clang-cl"
generator = "Ninja"
```

After editing toml, re-run **config** / **package** to apply changes (including output dir from `[project].name`).

**Options:**

- `--name <name>`: C++ module name; Python package is `py{name}`
- `--pybind11`: initialize as a pybind11 project
- `--pure-c`: pure C project
- `--godot`: initialize as a Godot GDExtension project
- `--godot-cpp-dir`: path to godot-cpp source (with `--godot`)
- `--godot-api-version`: target Godot API version (with `--godot`)
- `--inplace-vscode`: force overwrite existing `.vscode` tasks/launch files

#### Develop and debug

```bash
python scripts/cmake-config.py
cmake --build build
pip install -e .
python test.py
```

Or use VS Code tasks: **config** → **build** → **run**.  
Use `pip install -e .` for imports and IDE hints; no `sys.path` hacks in `test.py`.

#### Package and publish

Build the extension in the repo first, then package (no on-the-fly cmake inside the wheel build):

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

Flow: clear → cmake configure/build → `python -m build`.  
`package.py` switches to the interpreter under `[tool.pycpp].python_dir` so wheel tags (e.g. `cp313-cp313-win_amd64`) match the Python used for compilation.

Requires `build` (and setuptools from the generated project's `build-system`) in that environment.

## Requirements

- Python 3.13+ (for this tool)
- CMake 3.30+
- 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 (go-to-definition, completion, etc.; uses `compile_commands.json` from cmake config)

## License

MIT License

## Author

R.E. (redelephant@foxmail.com)
