Skip to content

README.md

Latest commit

 

History

History
116 lines (95 loc) · 4.52 KB

README.md

File metadata and controls

116 lines (95 loc) · 4.52 KB

Embedded Python Template (Cookiecutter)

This repository is a Cookiecutter template that scaffolds a Zig-based project embedding CPython. It generates a ready-to-build runtime, a Zig executable, and a packaging workflow for bundling Python libraries with your application.

Overview

  • Generate a Zig project that calls the Python C API safely.
  • Build steps for runtime, app binary, and Python packages.
  • Ships third-party Python libraries inside site-packages/.
  • Cross-platform strategy: Windows bundles CPython; Linux/macOS load system Python.

Prerequisites

  • Python 3.8+ and pip (to run Cookiecutter)
  • Cookiecutter installed via pip install cookiecutter
  • Zig 0.15+ installed and on PATH
  • C toolchain:
    • Windows: Visual Studio 2022 (MSBuild, C++ build tools)
    • Linux: GCC
    • macOS: Clang (Xcode Command Line Tools)
  • git for dependency fetching (optional but recommended)

Generate a Pr (for optional Rust extensions in packages)oject

You can generate from this local folder or from a git URL.

  • Local path (cross-platform):
    • cookiecutter . (run from the repo root)
  • From a git URL:
    • cookiecutter https://github.com/krita-frag/embedded-python-template.git

Cookiecutter will prompt you for values. After generation:

  • cd <project_slug>
  • zig build (runs the full build: runtime → app → packages)
  • The built binary and runtime will be placed under dist/.

Cookiecutter Prompts

This template asks for the following values:

  • project_name: Human-friendly project name (default Python Embedded Runtime).
  • project_slug: Directory and package slug (default embedded_python).
  • exe_name: Executable name (defaults to {{ cookiecutter.project_slug }}).
  • python_package: Default Python package name under packages/ (default core).
  • python_module_artifact: The compiled module artifact name (default _core).
  • description: Short description (default Embed CPython into Zig applications).
  • author_name: Your author name.
  • license: License string (default MIT).

Note: Some directories are copied without Jinja rendering to preserve internal tooling paths.

Project Layout

After generation, you will see a structure similar to:

<project_slug>/
├── build.zig
├── build.zig.zon
├── src/
│   ├── cli.zig
│   ├── main.zig
│   ├── python_runtime.zig
│   ├── root.zig
│   └── runtime_config.zig
├── packages/
│   └── <python_package>/
├── package_builder/
│   ├── README.md
│   └── (packaging tooling)
└── README.md

Build and Run

Common commands from the project root:

  • zig build — full build (runtime → app → packages)
  • zig build -Dbuild_step=runtime — prepare the embedded runtime only
  • zig build -Dbuild_step=app — build the Zig executable to dist/
  • zig build -Dbuild_step=packages — package Python libs into site-packages/

Useful options:

  • zig build -Dcpython_version=3.12.3
  • zig build -Dbuild_dir=build -Ddist_dir=dist
  • zig build -Dexe_name=<your-exe-name>

Run the built executable from dist/:

  • Windows: dist\<exe_name>.exe
  • POSIX: ./dist/<exe_name>

Packaging Python Libraries

  • Place your Python code under packages/<python_package>/.
  • The packaging workflow uses the embedded interpreter to build and copy artifacts to site-packages/.
  • See package_builder/README.md inside the generated project for details and advanced usage.

Configuration

Runtime configuration is controlled by runtime/py_config.txt (generated by the template). Typical fields:

version=3.12.3
site_packages_dir=site-packages;runtime
optimize_level=0
python_malloc=pymalloc
hash_seed=random
gc_enabled=true
gc_thresholds=700,10,10

Adjust these to match your deployment needs. On Windows, the template sets PYTHONHOME to the runtime bundle and uses the CPython standard library zip.

Platform Notes

  • Windows bundles headers, import libs, and pythonXY.zip into runtime/.
  • Linux/macOS load the system Python dynamically (ensure the correct version is installed).

Troubleshooting

  • Ensure zig is on PATH and matches the required version.
  • On Windows, install the Visual Studio C++ build tools and restart your shell.
  • If package builds fail, verify your Python environment and read package_builder/README.md.
  • For verbose build logs, use zig build -Dlog_level=debug (if supported by the template’s build script).

License

This template is provided under the MIT license. Generated projects may use the license you select during Cookiecutter prompts.