Metadata-Version: 2.3
Name: pycpp_tools
Version: 0.4.1
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 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`)
- 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
```

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