Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hendriknielaender/zBench
📊 zig benchmark
https://github.com/hendriknielaender/zBench
benchmark performance testing zig ziglang
Last synced: about 1 month ago
JSON representation
📊 zig benchmark
- Host: GitHub
- URL: https://github.com/hendriknielaender/zBench
- Owner: hendriknielaender
- License: mit
- Created: 2023-05-25T13:57:54.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-18T09:52:34.000Z (about 1 month ago)
- Last Synced: 2024-05-18T10:48:48.565Z (about 1 month ago)
- Topics: benchmark, performance, testing, zig, ziglang
- Language: Zig
- Homepage: https://hendriknielaender.github.io/zBench/
- Size: 14 MB
- Stars: 35
- Watchers: 3
- Forks: 7
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Lists
- awesome-zig - hendriknielaender/zBench
README
# âš¡ zBench - A Simple Zig Benchmarking Library
[](https://github.com/hendriknielaender/zbench/blob/HEAD/LICENSE)
[](https://github.com/hendriknielaender/zbench/blob/HEAD/CONTRIBUTING.md)
zBench is a simple benchmarking library for the Zig programming language. It is designed to provide easy-to-use functionality to measure and compare the performance of your code.
## Install Option 1 (build.zig.zon)
1. Declare zBench as a dependency in `build.zig.zon`:
```diff
.{
.name = "my-project",
.version = "1.0.0",
.paths = .{""},
.dependencies = .{
+ .zbench = .{
+ .url = "https://github.com/hendriknielaender/zbench/archive/.tar.gz",
+ },
},
}
```
2. Add the module in `build.zig`:
```diff
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
+ const opts = .{ .target = target, .optimize = optimize };
+ const zbench_module = b.dependency("zbench", opts).module("zbench");
const exe = b.addExecutable(.{
.name = "test",
.root_source_file = .{ .path = "src/main.zig" },
.target = target,
.optimize = optimize,
});
+ exe.root_module.addImport("zbench", zbench_module);
exe.install();
...
}
```
3. Get the package hash:
```shell
$ zig build
my-project/build.zig.zon:6:20: error: url field is missing corresponding hash field
.url = "https://github.com/hendriknielaender/zbench/archive/.tar.gz",
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
note: expected .hash = "",
```
4. Update `build.zig.zon` package hash value:
```diff
.{
.name = "my-project",
.version = "1.0.0",
.paths = .{""},
.dependencies = .{
.zbench = .{
.url = "https://github.com/hendriknielaender/zbench/archive/.tar.gz",
+ .hash = "",
},
},
}
```
## Install Option 2 (git submodule)
On your project root directory make a directory name libs.
- Run `git submodule add https://github.com/hendriknielaender/zBench libs/zbench`
- Then add the module into your `build.zig`
```zig
exe.addAnonymousModule("zbench", .{
.source_file = .{ .path = "libs/zbench/zbench.zig" },
});
```
Now you can import like this:
```zig
const zbench = @import("zbench");
```
## Usage
Create a new benchmark function in your Zig code. This function should take a single argument of type `std.mem.Allocator`. The function would run the code you wish to benchmark.
```zig
fn benchmarkMyFunction(allocator: std.mem.Allocator) void {
// Code to benchmark here
}
```
You can then run your benchmarks in a test:
```zig
test "bench test" {
var bench = zbench.Benchmark.init(std.testing.allocator, .{});
defer bench.deinit();
try bench.add("My Benchmark", myBenchmark, .{});
try bench.run(std.io.getStdOut().writer());
}
```
## Configuration
To customize your benchmark runs, zBench provides a `Config` struct that allows you to specify several options:
```zig
pub const Config = struct {
iterations: u16 = 0,
max_iterations: u16 = 16384,
time_budget_ns: u64 = 2e9, // 2 seconds
hooks: Hooks = .{},
};
```
- `iterations`: The number of iterations the benchmark has been run. This field is usually managed by zBench itself.
- `max_iterations`: Set the maximum number of iterations for a benchmark. Useful for controlling long-running benchmarks.
- `time_budget_ns`: Define a time budget for the benchmark in nanoseconds. Helps in limiting the total execution time of the benchmark.
- `hooks`: Set `before_all`, `after_all`, `before_each`, and `after_each` hooks to function pointers.
### Compatibility Notes
Zig is in active development and the APIs can change frequently, making it challenging to support every dev build. This project currently aims to be compatible with stable, non-development builds to provide a consistent experience for the users.
**_Supported Version_**: As of now, zBench is tested and supported on Zig version **_0.12.0_**.
### Benchmark Functions
Benchmark functions have the following signature:
```zig
fn(allocator: std.mem.Allocator) void
```
The function body contains the code you wish to benchmark.
### Reporting Benchmarks
zBench provides a comprehensive report for each benchmark run. It includes the total operations performed, the average, min, and max durations of operations, and the percentile distribution (p75, p99, p995) of operation durations.
```shell
benchmark runs time (avg ± σ) (min ... max) p75 p99 p995
---------------------------------------------------------------------------------------------------------------
benchmarkMyFunction 1000 1200ms ± 10ms (100ms ... 2000ms) 1100ms 1900ms 1950ms
```
This example report indicates that the benchmark "benchmarkMyFunction" ran with an average of 1200 ms per execution and a standard deviation of 10 ms.
The minimum and maximum execution times were 100 ms and 2000 ms, respectively. The 75th, 99th and 99.5th percentiles of execution times were 1100 ms, 1900 ms, and 1950 ms, respectively.
### Running zBench Examples
You can run all example tests with the following command:
```shell
zig build test_examples
```
### Troubleshooting
- If Zig doesn't detect changes in a dependency, clear the project's `zig-cache` folder and `~/.cache/zig`.
- [Non-ASCII characters not printed correctly on Windows](docs/advanced.md)
## Contributing
The main purpose of this repository is to continue to evolve zBench, making it faster and more efficient. We are grateful to the community for contributing bugfixes and improvements. Read below to learn how you help improve zBench.
### Contributing Guide
Read our [contributing guide](CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to zBench.
### License
zBench is [MIT licensed](./LICENSE).