hello-pybind11

Blazing-fast C++/Python bindings with pybind11, optimized for Windows/macOS/Linux with zero configuration.

🚀 Key Upgrade: Now requires uv>=0.7.20 for reproducible builds.

---

✨ Features

• One-command setup (just setup) with isolated environments
• 3x faster builds with Ninja + compiler caching (auto-detects sccache/ccache)
• Cross-platform cleanup (just clean handles all OS artifacts)
• Preconfigured CMake with pybind11/Python discovery

---

⚡ Quickstart

1. Install Prerequisites

# Install latest uv (required >=0.7.20)
pip install --upgrade "uv>=0.7.20" just

Platform-Specific Tools:

OS	Command
Windows	choco install ninja cmake --params 'ADD_CMAKE_TO_PATH=System'
macOS	brew install cmake ninja ccache
Linux	sudo apt-get install cmake ninja-build ccache or use conda

2. Build & Test

just setup  # Creates venv, installs deps, configures CMake
just dev    # Incremental build (watched by default)
just test   # Run test.py

---

🛠️ Key Commands

Command	Action
just setup	Full environment setup (venv + CMake config)
just dev	Build + install extension incrementally (uses uv run for isolation)
just check	Validate module imports (hello_pybind11.hello_world())
just clean	Cross-platform cleanup (build dirs, .so/.pyd, caches)
just rebuild	Nuclear rebuild (clean + reinstall)

💡 Pro Tip: Use just -f Justfile --list to see all commands.

---

🚀 Advanced Usage

Debug vs. Release Builds

just rebuild CMAKE_BUILD_TYPE=Debug    # Debug symbols
just rebuild CMAKE_BUILD_TYPE=Release  # Optimized (default)

Compiler Caching (Auto-Configured)

# Windows (uses sccache automatically if installed)
just dev USE_SCCACHE=1

# macOS/Linux (uses ccache)
just dev USE_CCACHE=1

Custom Python Version

just setup python_version="3.12"  # Override default 3.11.11

---

📁 Project Structure

hello_pybind11/
├── CMakeLists.txt    # Preconfigured for pybind11
├── main.cpp          # Your bindings code
├── pyproject.toml    # scikit-build-core config
├── Justfile          # Cross-platform tasks (see below)
└── scripts/          # Build helpers
     └── install_built_extensions.py  # Handles .so/.pyd installation

---

💡 Pro Tips

Windows-Specific

# Force sccache (faster than ccache on Windows)
$env:USE_SCCACHE = "1"
just dev

Unix/macOS

# Use LLD for faster linking (Linux/macOS)
export CMAKE_ARGS="-DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld"
just rebuild

All Platforms

# Build with verbose output
just dev --verbose

---

📜 License

MIT — Free for all platforms.

---

Why This Works Everywhere:

1. No OS-Specific Commands: The Justfile uses uv run and Python scripts for all operations.
2. Artifact Handling: just clean removes .so (Linux/macOS) and .pyd (Windows) automatically.
3. uv Isolation: Every command runs in the project’s venv, avoiding system conflicts.

Confirmed with:

• uv==0.7.20
• Windows (sccache), macOS (ccache), Linux (ccache)
• Python 3.11+