Getting Started

Get up and running with poly-bench in minutes

Installation

Install poly-bench using Cargo:

$curl -sSL https://install.evm-tooling.tools | bash

Prerequisites

poly-bench generates and runs native code in each target language. Make sure you have the runtimes installed for the languages you want to benchmark:

Language	Requirement
Go	Go 1.21+ (`go version`)
TypeScript	Node.js 18+ (`node --version`)
Rust	Rust 1.70+ (`rustc --version`)

You only need the runtimes for languages you're actually benchmarking. If you're only comparing Go and TypeScript, Rust isn't required.

Quick Start

Follow this guide to create your first benchmark comparing a keccak256 implementation across Go, TypeScript, and Rust.

1. Initialize a Project

Create a new poly-bench project:

$poly-bench init my-benchmarks
$cd my-benchmarks

This creates a project structure:

1my-benchmarks/
2├── polybench.toml      # Project configuration
3├── benchmarks/
4│   └── example.bench   # Example benchmark file
5└── .polybench/
6  └── runtime-env/    # Generated runtime environments

2. Add Dependencies

Add the libraries you want to benchmark. poly-bench manages dependencies for each language:

$# Add Go dependencies
$poly-bench add --go golang.org/x/crypto

$# Add npm dependencies  
$poly-bench add --ts viem

$# Add Rust crates
$poly-bench add --rs tiny-keccak

Then install all dependencies:

$poly-bench install

Dependencies are isolated per-project in the .polybench/runtime-env/ directory. This keeps your benchmarks reproducible and avoids polluting your global environment.

3. Create a Benchmark

Create a new .bench file in the benchmarks/ directory:

1suite keccak {
2  description: "Keccak256 hash benchmark"
3  warmup: 100
4  compare: true
5  baseline: "go"
6  mode: "auto"
7  targetTime: 3000ms
8  count: 3
9
10  setup go {
11      import "golang.org/x/crypto/sha3"
12      helpers {
13          func keccak256Go(data []byte) []byte {
14              h := sha3.NewLegacyKeccak256()
15              h.Write(data)
16              return h.Sum(nil)
17          }
18      }
19  }
20
21  setup ts {
22      import { keccak256 } from 'viem';
23      helpers {
24          function keccak256Ts(data: Uint8Array): Uint8Array {
25              return keccak256(data, 'bytes')
26          }
27      }
28  }
29
30  setup rust {
31      import { use tiny_keccak::{Hasher, Keccak}; }
32      helpers {
33          fn keccak256_rust(data: &[u8]) -> [u8; 32] {
34              let mut hasher = Keccak::v256();
35              let mut output = [0u8; 32];
36              hasher.update(data);
37              hasher.finalize(&mut output);
38              output
39          }
40      }
41  }
42
43  fixture data {
44      hex: "68656c6c6f20776f726c64"
45  }
46
47  bench keccak256Bench {
48      go: keccak256Go(data)
49      ts: keccak256Ts(data)
50      rust: keccak256_rust(&data)
51  }
52}

The fixture block defines shared test data as hex-encoded bytes. This ensures all languages hash the exact same input for fair comparison.

4. Run Benchmarks

Execute your benchmark:

$poly-bench run benchmarks/keccak.bench

You'll see output like:

1Running suite: keccak
2Calibrating iterations...
3Target time: 3000ms
4
5Running: keccak256Bench
6  go:   1,234 ns/op (810,372 ops/s) ± 2.1%
7  ts:   15,678 ns/op (63,784 ops/s) ± 3.4%
8  rust: 987 ns/op (1,013,171 ops/s) ± 1.8%
9
10Comparison (baseline: go):
11  rust: 1.25x faster
12  ts:   12.70x slower
13
14✓ Suite completed in 9.2s

5. Generate Reports

poly-bench can output results in multiple formats:

$# Console output (default)
$poly-bench run keccak.bench

$# Markdown report
$poly-bench run keccak.bench --report markdown --output results/

$# JSON for CI/automation
$poly-bench run keccak.bench --report json --output results/

$# Generate SVG charts (via charting directives in .bench file)
$poly-bench run keccak.bench --output results/

Add charting.drawTable(...) directives in your after block to automatically generate SVG visualizations. See the Reporting page for details.

Configuration Options

The suite configuration controls how benchmarks run:

Option	Description	Default
`iterations`	Fixed iteration count (legacy mode)	-
`warmup`	Warmup iterations before timing	0
`mode`	`"auto"` (calibrate) or `"fixed"`	`"fixed"`
`targetTime`	Target time for auto mode	`3000ms`
`minIterations`	Minimum iterations (auto mode)	1
`maxIterations`	Maximum iterations (auto mode)	10000000
`count`	Runs per benchmark for statistics	1
`baseline`	Language for comparison ratios	-
`compare`	Enable comparison table	false
`memory`	Enable memory profiling	false

Run Specific Languages

You don't have to run all languages every time:

$# Run only Go benchmarks
$poly-bench run keccak.bench --lang go

$# Run Go and Rust only
$poly-bench run keccak.bench --lang go --lang rust

Validate Without Running

Check your .bench file for errors without executing:

$poly-bench check benchmarks/keccak.bench

Next Steps

Learn about the DSL Reference for full syntax documentation
Explore the Standard Library for std::anvil and std::charting
See Examples for real-world benchmark patterns
Check out CLI Reference for all command options

Need help? Run poly-bench --help or poly-bench run --help for command-line documentation.

Language

Requirement

Go 1.21+ (go version)

TypeScript

Node.js 18+ (node --version)

Rust

Rust 1.70+ (rustc --version)

1my-benchmarks/ 2├── polybench.toml # Project configuration 3├── benchmarks/ 4│ └── example.bench # Example benchmark file 5└── .polybench/ 6 └── runtime-env/ # Generated runtime environments

1suite keccak { 2 description: "Keccak256 hash benchmark" 3 warmup: 100 4 compare: true 5 baseline: "go" 6 mode: "auto" 7 targetTime: 3000ms 8 count: 3 9 10 setup go { 11 import "golang.org/x/crypto/sha3" 12 helpers { 13 func keccak256Go(data []byte) []byte { 14 h := sha3.NewLegacyKeccak256() 15 h.Write(data) 16 return h.Sum(nil) 17 } 18 } 19 } 20 21 setup ts { 22 import { keccak256 } from 'viem'; 23 helpers { 24 function keccak256Ts(data: Uint8Array): Uint8Array { 25 return keccak256(data, 'bytes') 26 } 27 } 28 } 29 30 setup rust { 31 import { use tiny_keccak::{Hasher, Keccak}; } 32 helpers { 33 fn keccak256_rust(data: &[u8]) -> [u8; 32] { 34 let mut hasher = Keccak::v256(); 35 let mut output = [0u8; 32]; 36 hasher.update(data); 37 hasher.finalize(&mut output); 38 output 39 } 40 } 41 } 42 43 fixture data { 44 hex: "68656c6c6f20776f726c64" 45 } 46 47 bench keccak256Bench { 48 go: keccak256Go(data) 49 ts: keccak256Ts(data) 50 rust: keccak256_rust(&data) 51 } 52}

1Running suite: keccak 2Calibrating iterations... 3Target time: 3000ms 4 5Running: keccak256Bench 6 go: 1,234 ns/op (810,372 ops/s) ± 2.1% 7 ts: 15,678 ns/op (63,784 ops/s) ± 3.4% 8 rust: 987 ns/op (1,013,171 ops/s) ± 1.8% 9 10Comparison (baseline: go): 11 rust: 1.25x faster 12 ts: 12.70x slower 13 14✓ Suite completed in 9.2s

$# Console output (default) $poly-bench run keccak.bench $# Markdown report $poly-bench run keccak.bench --report markdown --output results/ $# JSON for CI/automation $poly-bench run keccak.bench --report json --output results/ $# Generate SVG charts (via charting directives in .bench file) $poly-bench run keccak.bench --output results/

Option

Description

Default

iterations

Fixed iteration count (legacy mode)

warmup

Warmup iterations before timing

mode

"auto" (calibrate) or "fixed"

"fixed"

targetTime

Target time for auto mode

3000ms

minIterations

Minimum iterations (auto mode)

maxIterations

Maximum iterations (auto mode)

10000000

count

Runs per benchmark for statistics

baseline

Language for comparison ratios

compare

Enable comparison table

false

memory

Enable memory profiling

false