Developers

Name: poly-bench
Author: poly-bench

Early development notice, bug-prone areas, and contributor guides for poly-bench

Docs in progress. Some content or features may be missing or not covered in detail.

poly-bench is in early development. There may be bugs, and some features are still evolving. We welcome feedback and contributions.

Early Development Notice

poly-bench is actively developed. APIs, CLI behavior, and runtime behavior may change. If you encounter issues, please report them — your feedback helps improve the project.

Contributions are welcome. Start with the Adding a Runtime guide or the Python Case Study for a step-by-step walkthrough.

Bug-Prone Areas

Some areas are more likely to cause issues than others. If you hit problems in one of these areas, you are not alone. The table below lists the main trouble spots and what tends to go wrong:

Area	Likely Issues
Zig	Version compatibility (0.15 vs 0.13/0.14), package patches for `for`-loop syntax, packages targeting older Zig
C	External dependencies via vcpkg, CMake toolchain, `VCPKG_ROOT`, system vs vcpkg OpenSSL
C#	.NET version mismatch (net8.0 default vs .NET 6/7), `global.json` SDK pin
Python	venv creation on Debian/Ubuntu (`python3-venv`), pyenv/conda conflicts

Zig and C with external deps — Zig package version compatibility and C's vcpkg/CMake setup are the most common sources of build failures. See Requirements for per-language gotchas.

How to File an Issue

Use the Bug Report template on GitHub. When filing an issue, include the following:

poly-bench version: Run poly-bench --version
Command / workflow: What you were running when the issue occurred
Environment: OS and toolchain versions (Rust, Node.js, Go, etc.)
Steps to reproduce: Minimal sequence to reproduce the behavior
Minimal reproduction: Smallest example (benchmark file, command, or snippet)
Error output: Full error message or stack trace

The more detail you provide, the faster we can help. A minimal .bench file and the exact command that fails are especially useful.

Contributor Guides

The following guides help contributors add runtimes, understand the codebase, and contribute effectively:

Topic	Description
Runtime Not Available	The runtime you need isn't supported — here's how to add it
Adding a Runtime	Extreme-detail guide: spec, checklists, LSP, execution, integration tests
Case Study: Python	Step-by-step walkthrough of how the Python runtime was implemented

Bug-Prone Areas

Some areas are more likely to cause issues than others. If you hit problems in one of these areas, you are not alone. The table below lists the main trouble spots and what tends to go wrong:

Area	Likely Issues
Zig	Version compatibility (0.15 vs 0.13/0.14), package patches for `for`-loop syntax, packages targeting older Zig
C	External dependencies via vcpkg, CMake toolchain, `VCPKG_ROOT`, system vs vcpkg OpenSSL
C#	.NET version mismatch (net8.0 default vs .NET 6/7), `global.json` SDK pin
Python	venv creation on Debian/Ubuntu (`python3-venv`), pyenv/conda conflicts

Zig and C with external deps — Zig package version compatibility and C's vcpkg/CMake setup are the most common sources of build failures. See Requirements for per-language gotchas.

How to File an Issue

Use the Bug Report template on GitHub. When filing an issue, include the following:

poly-bench version: Run poly-bench --version

Command / workflow: What you were running when the issue occurred

Environment: OS and toolchain versions (Rust, Node.js, Go, etc.)

Steps to reproduce: Minimal sequence to reproduce the behavior

Minimal reproduction: Smallest example (benchmark file, command, or snippet)

Error output: Full error message or stack trace

The more detail you provide, the faster we can help. A minimal .bench file and the exact command that fails are especially useful.

Contributor Guides

The following guides help contributors add runtimes, understand the codebase, and contribute effectively:

Topic	Description
Runtime Not Available	The runtime you need isn't supported — here's how to add it
Adding a Runtime	Extreme-detail guide: spec, checklists, LSP, execution, integration tests
Case Study: Python	Step-by-step walkthrough of how the Python runtime was implemented