Skip to main content

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

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

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

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):

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

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

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):

[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

# 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

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:

License

MIT License

Author

R.E. (redelephant@foxmail.com)

Metadata

Release files for pycpp-tools 0.7.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycpp-tools 0.7.9
File Size Uploaded Provenance Actions
pycpp_tools-0.7.9.tar.gz 23.8 kB Without provenance Details for pycpp_tools-0.7.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pycpp-tools 0.7.9
File Interpreter ABI Platform Actions
pycpp_tools-0.7.9-py3-none-any.whl Python 3 none any Details for pycpp_tools-0.7.9-py3-none-any.whl

Total release size: 50.8 kB

Release files / pycpp_tools-0.7.9.tar.gz

Download URL pycpp_tools-0.7.9.tar.gz
Size 23.8 kB
Tags Source
SHA-256 checksum
How to use checksums
62974e24c4763774d9179f6e862787aa852ab1000e4abe7906b781d4a07ab2e7
BLAKE2b-256 checksum
How to use checksums
7ae8b55268f15724bddcd0edd25c1aa36d68c8c6b0b4f52c07a3f5b6a0e84d9b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / pycpp_tools-0.7.9-py3-none-any.whl

Download URL pycpp_tools-0.7.9-py3-none-any.whl
Size 27.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3cc927fa1955b20f1d3130a9d77dfa636199a3128a9906a9f962c9b64725fa65
BLAKE2b-256 checksum
How to use checksums
717972fac3090e637a8ceb540cef07bb00b8359cf8c2eebac0f9920d80e6ae94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for pycpp-tools 0.7.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page