From b022104a25d939d37df2450a00aace0572126a24 Mon Sep 17 00:00:00 2001 From: hndrk <51416554+hendriknielaender@users.noreply.github.com> Date: Sat, 25 May 2024 23:26:27 +0200 Subject: [PATCH 1/4] chore: add TOC --- README.md | 102 +++++++++--------------------------------------------- 1 file changed, 16 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index fe50109..26e87a2 100644 --- a/README.md +++ b/README.md @@ -7,92 +7,22 @@ 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"); -``` +## Content + * [Installation](docs/install.md) + * [Usage](#usage) + * [Configuration](#configuration) + + [Compatibility Notes](#compatibility-notes) + + [Benchmark Functions](#benchmark-functions) + + [Reporting Benchmarks](#reporting-benchmarks) + + [Running zBench Examples](#running-zbench-examples) + + [Troubleshooting](#troubleshooting) + * [Contributing](#contributing) + + [Contributing Guide](#contributing-guide) + + [License](#license) + +## Installation + +For installation instructions, please refer to the [documentation](docs/install.md). ## Usage From a7506a1c290d36597ad11bc70872bf607a11d5cf Mon Sep 17 00:00:00 2001 From: hndrk <51416554+hendriknielaender@users.noreply.github.com> Date: Sat, 25 May 2024 23:38:28 +0200 Subject: [PATCH 2/4] docs: create install.md --- docs/install.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/install.md diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..575dacb --- /dev/null +++ b/docs/install.md @@ -0,0 +1,96 @@ +## Install + +You can use `zig fetch` to conveniently set the hash in the `build.zig.zon` file and update an existing dependency. + +Run the following command to fetch the zBench package: +```shell +zig fetch https://github.com/hendriknielaender/zbench/archive/.tar.gz --save +``` +Using `zig fetch` simplifies managing dependencies by automatically handling the package hash, ensuring your `build.zig.zon` file is up to date. + +### 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 = "", + }, + }, + } + ``` + +### 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"); +``` From df5f455cb1c6a1a0c3a847c58cf239a1b1f921da Mon Sep 17 00:00:00 2001 From: hndrk <51416554+hendriknielaender@users.noreply.github.com> Date: Sun, 26 May 2024 00:09:55 +0200 Subject: [PATCH 3/4] chore: use b.path --- docs/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install.md b/docs/install.md index 575dacb..9569c71 100644 --- a/docs/install.md +++ b/docs/install.md @@ -39,7 +39,7 @@ Using `zig fetch` simplifies managing dependencies by automatically handling the const exe = b.addExecutable(.{ .name = "test", - .root_source_file = .{ .path = "src/main.zig" }, + .root_source_file = b.path("src/main.zig"), .target = target, .optimize = optimize, }); From a0a3714d4aa84b6318c13bdd96ef778e624919fe Mon Sep 17 00:00:00 2001 From: hndrk <51416554+hendriknielaender@users.noreply.github.com> Date: Sun, 26 May 2024 00:13:59 +0200 Subject: [PATCH 4/4] chore: add further reading in install.md --- docs/install.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/install.md b/docs/install.md index 9569c71..9c3b011 100644 --- a/docs/install.md +++ b/docs/install.md @@ -94,3 +94,10 @@ Now you can import like this: ```zig const zbench = @import("zbench"); ``` + +## Further Reading + +For more information on the Zig build system and useful tricks, check out these resources: + +- [Zig Build System](https://ziglang.org/learn/build-system/) +- [Build System Tricks](https://ziggit.dev/t/build-system-tricks/)