Skip to content

feat(build): use blst packaged for zig using zig build system #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 26, 2025
Merged

feat(build): use blst packaged for zig using zig build system #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bd52509
feat(build): use `blst` packaged for zig using zig build system
spiral-ladder Sep 26, 2025
1ad6b3e
update naming for lib for upload-artifact step
spiral-ladder Sep 26, 2025
c08b69e
update name: blst.zig -> blst
spiral-ladder Sep 26, 2025
32ece46
update package.json
spiral-ladder Sep 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/CI.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ jobs:
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.settings.bun-target }}
path: 'zig-out/lib/*blst_min_pk.*'
path: 'zig-out/lib/*eth_blst.*'
Copy link
Contributor Author

@spiral-ladder spiral-ladder Sep 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Had to update this name to match the output in build.zig.

if-no-files-found: error

bun-benchmark:
Expand Down Expand Up @@ -278,4 +278,4 @@ jobs:
run: bun run publish
working-directory: ./bun
env:
NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
204 changes: 26 additions & 178 deletions build.zig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,114 +3,42 @@ const Compile = std.Build.Step.Compile;
const ResolvedTarget = std.Build.ResolvedTarget;
const OptimizeMode = std.builtin.OptimizeMode;

// Although this function looks imperative, note that its job is to
// declaratively construct a build graph that will be executed by an external
// runner.
pub fn build(b: *std.Build) !void {
// Standard target options allows the person running `zig build` to choose
// what target to build for. Here we do not override the defaults, which
// means any target is allowed, and the default is native. Other options
// for restricting supported target set are available.
const target = b.standardTargetOptions(.{});

// Standard optimization options allow the person running `zig build` to select
// between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
// set a preferred release mode, allowing the user to decide how to optimize.
const optimize = b.standardOptimizeOption(.{});

const blst_dep = b.dependency("blst", .{ .target = target, .optimize = optimize });

// passed by "zig build -Dportable=true"
const portable = b.option(bool, "portable", "Enable portable implementation") orelse false;
// passed by "zig build -Dforce-adx=true"
const force_adx = b.option(bool, "force-adx", "Enable ADX optimizations") orelse false;

// build blst-z static library
const staticLib = b.addStaticLibrary(.{
.name = "blst-z",
// In this case the main source file is merely a path, however, in more
// complicated build scripts, this could be a generated file.
.root_source_file = b.path("src/root.zig"),
.target = target,
.optimize = optimize,
});

const module_blst_min_pk = b.createModule(.{
.root_source_file = b.path("src/root_min_pk.zig"),
.target = target,
.optimize = optimize,
const blst_c = b.dependency("blst", .{
.portable = b.option(bool, "portable", "turn on portable mode") orelse false,
});
try withBlst(blst_dep, module_blst_min_pk, target, false, portable, force_adx);

b.modules.put(b.dupe("blst_min_pk"), module_blst_min_pk) catch @panic("OOM");

const module_blst_min_sig = b.createModule(.{
.root_source_file = b.path("src/root_min_sig.zig"),
const lib_blst_c = blst_c.artifact("blst");
// blst module (for downstream zig consumers)
const blst_mod = b.addModule("blst", .{
.root_source_file = b.path("src/root.zig"),
.target = target,
.optimize = optimize,
});
try withBlst(blst_dep, module_blst_min_sig, target, false, portable, force_adx);
b.modules.put(b.dupe("blst_min_sig"), module_blst_min_sig) catch @panic("OOM");

// blst does not need libc, however we need to link it to enable threading
// see https://github.com/ChainSafe/blst-bun/issues/4
staticLib.linkLibC();
// the folder where blst.h is located
try withBlst(blst_dep, staticLib.root_module, target, false, portable, force_adx);

// This declares intent for the library to be installed into the standard
// location when the user invokes the "install" step (the default step when
// running `zig build`).
b.installArtifact(staticLib);

// build blst-z shared library
const sharedLib = b.addSharedLibrary(.{
.name = "blst_min_pk",
.root_source_file = b.path("src/root_c_abi_min_pk.zig"),
.target = target,
.optimize = optimize,
blst_mod.linkLibrary(lib_blst_c);
blst_mod.addIncludePath(blst_c.path("include"));

// blst dynamic library (for bun consumers)
const blst_dylib = b.addLibrary(.{
.root_module = b.createModule(.{
.root_source_file = b.path("src/root_c_abi_min_pk.zig"),
.target = target,
.optimize = optimize,
// blst does not need libc, however we need to link it to enable threading
// see https://github.com/ChainSafe/blst-bun/issues/4
.link_libc = true,
.pic = true,
}),
.name = "eth_blst",
.linkage = .dynamic,
});
blst_dylib.linkLibrary(lib_blst_c);

// blst does not need libc, however we need to link it to enable threading
// see https://github.com/ChainSafe/blst-bun/issues/4
sharedLib.linkLibC();
try withBlst(blst_dep, sharedLib.root_module, target, true, portable, force_adx);
b.installArtifact(sharedLib);

const exe = b.addExecutable(.{
.name = "blst-z",
.root_source_file = b.path("src/main.zig"),
.target = target,
.optimize = optimize,
});

// This declares intent for the executable to be installed into the
// standard location when the user invokes the "install" step (the default
// step when running `zig build`).
b.installArtifact(exe);

// This *creates* a Run step in the build graph, to be executed when another
// step is evaluated that depends on it. The next line below will establish
// such a dependency.
const run_cmd = b.addRunArtifact(exe);

// By making the run step depend on the install step, it will be run from the
// installation directory rather than directly from within the cache directory.
// This is not necessary, however, if the application depends on other installed
// files, this ensures they will be present and in the expected location.
run_cmd.step.dependOn(b.getInstallStep());

// This allows the user to pass arguments to the application in the build
// command itself, like this: `zig build run -- arg1 arg2 etc`
if (b.args) |args| {
run_cmd.addArgs(args);
}

// This creates a build step. It will be visible in the `zig build --help` menu,
// and can be selected like this: `zig build run`
// This will evaluate the `run` step rather than the default, which is "install".
const run_step = b.step("run", "Run the app");
run_step.dependOn(&run_cmd.step);
b.installArtifact(blst_dylib);

// Creates a step for unit testing. This only builds the test executable
// but does not run it.
Expand All @@ -120,8 +48,7 @@ pub fn build(b: *std.Build) !void {
.optimize = optimize,
});

try withBlst(blst_dep, lib_unit_tests.root_module, target, true, portable, force_adx);

lib_unit_tests.linkLibrary(lib_blst_c);
const run_lib_unit_tests = b.addRunArtifact(lib_unit_tests);

const exe_unit_tests = b.addTest(.{
Expand All @@ -130,89 +57,10 @@ pub fn build(b: *std.Build) !void {
.optimize = optimize,
});

exe_unit_tests.linkLibrary(lib_blst_c);
const run_exe_unit_tests = b.addRunArtifact(exe_unit_tests);

// Similar to creating the run step earlier, this exposes a `test` step to
// the `zig build --help` menu, providing a way for the user to request
// running the unit tests.
const test_step = b.step("test", "Run unit tests");
test_step.dependOn(&run_lib_unit_tests.step);
test_step.dependOn(&run_exe_unit_tests.step);
}

/// instead of treating blst as a dependency lib, build and link it, we add its resource to our libs
/// and zig will handle a mixture of C, assembly and Zig code
/// reference to https://github.com/supranational/blst/blob/v0.3.13/bindings/rust/build.rs
/// TODO: port all missing flows from the Rust build script
fn withBlst(blst_dep: *std.Build.Dependency, module: *std.Build.Module, target: ResolvedTarget, is_shared_lib: bool, portable: bool, force_adx: bool) !void {
module.addIncludePath(blst_dep.path("bindings"));
// add later, once we have cflags
const arch = target.result.cpu.arch;

// TODO: how to get target_env?
// TODO: may have a separate build version for adx
// then at Bun side, it has to detect if the target is x86_64 and has adx or not
if (portable == true and force_adx == false) {
// TODO: panic if target_env is sgx
// use this instead
module.addCMacro("__BLST_PORTABLE__", "");
} else if (portable == false and force_adx == true) {
if (arch == .x86_64) {
module.addCMacro("__ADX__", "");
} else {
std.debug.print("`force-adx` is ignored for non-x86_64 targets \n", .{});
}
} else if (portable == false and force_adx == false) {
// TODO: how to detect adx like this Rust call
// if std::is_x86_feature_detected!("adx") {
if (arch == .x86_64) {
std.debug.print("ADX is turned on by default for x86_64 targets \n", .{});
module.addCMacro("__ADX__", "");
}
// otherwise get: "undefined symbol redcx_mont_256" when run tests in Linux
} else {
// both are true
@panic("Cannot set both `portable` and `force-adx` to true");
}

var gpa = std.heap.GeneralPurposeAllocator(.{}){};
const allocator = gpa.allocator();

defer _ = gpa.deinit();

var cflags = std.ArrayList([]const u8).init(allocator);
defer cflags.deinit();

// get this error in Mac arm: unsupported option '-mno-avx' for target 'aarch64-unknown-macosx15.1.0-unknown'
if (arch == .x86_64) {
try cflags.append("-mno-avx"); // avoid costly transitions
}
// the no_builtin should help, set here just to make sure
try cflags.append("-fno-builtin");
try cflags.append("-Wno-unused-function");
try cflags.append("-Wno-unused-command-line-argument");

if (is_shared_lib) {
try cflags.append("-fPIC");
}

module.addCSourceFile(.{ .file = blst_dep.path("src/server.c"), .flags = cflags.items });
module.addCSourceFile(.{ .file = blst_dep.path("build/assembly.S"), .flags = cflags.items });

// TODO: we may not need this since we linkLibC() above
const os = target.result.os;
// fix this error on Linux: 'stdlib.h' file not found
// otherwise blst-bun cannot load the shared library on Linux
// with error "Failed to open library. This is usually caused by a missing library or an invalid library path"
if (os.tag == .linux) {
// since "zig cc" works fine, we just follow it
// zig cc -E -Wp,-v -
module.addIncludePath(.{ .cwd_relative = "/usr/local/include" });
module.addIncludePath(.{ .cwd_relative = "/usr/include" });
if (arch == .x86_64) {
module.addIncludePath(.{ .cwd_relative = "/usr/include/x86_64-linux-gnu" });
} else if (arch == .aarch64) {
module.addIncludePath(.{ .cwd_relative = "/usr/include/aarch64-linux-gnu" });
}
}
}
74 changes: 2 additions & 72 deletions build.zig.zon
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,91 +1,21 @@
.{
// This is the default name used by packages depending on this one. For
// example, when a user runs `zig fetch --save <url>`, this field is used
// as the key in the `dependencies` table. Although the user can choose a
// different name, most users will stick with this provided value.
//
// It is redundant to include "zig" in this name because it is already
// within the Zig package namespace.
.name = .blst_z,

// This is a [Semantic Version](https://semver.org/).
// In a future version of Zig it will be used for package deduplication.
.version = "0.0.0",

// Together with name, this represents a globally unique package
// identifier. This field is generated by the Zig toolchain when the
// package is first created, and then *never changes*. This allows
// unambiguous detection of one package being an updated version of
// another.
//
// When forking a Zig project, this id should be regenerated (delete the
// field and run `zig build`) if the upstream project is still maintained.
// Otherwise, the fork is *hostile*, attempting to take control over the
// original project's identity. Thus it is recommended to leave the comment
// on the following line intact, so that it shows up in code reviews that
// modify the field.
.fingerprint = 0xfbd83f934c5ddb5, // Changing this has security and trust implications.

// Tracks the earliest Zig version that the package considers to be a
// supported use case.
.minimum_zig_version = "0.14.0",

// This field is optional.
// Each dependency must either provide a `url` and `hash`, or a `path`.
// `zig build --fetch` can be used to fetch all dependencies of a package, recursively.
// Once all dependencies are fetched, `zig build` no longer requires
// internet connectivity.
.dependencies = .{
// See `zig fetch --save <url>` for a command-line interface for adding dependencies.
//.example = .{
// // When updating this field to a new URL, be sure to delete the corresponding
// // `hash`, otherwise you are communicating that you expect to find the old hash at
// // the new URL. If the contents of a URL change this will result in a hash mismatch
// // which will prevent zig from using it.
// .url = "https://example.com/foo.tar.gz",
//
// // This is computed from the file contents of the directory of files that is
// // obtained after fetching `url` and applying the inclusion rules given by
// // `paths`.
// //
// // This field is the source of truth; packages do not come from a `url`; they
// // come from a `hash`. `url` is just one of many possible mirrors for how to
// // obtain a package matching this `hash`.
// //
// // Uses the [multihash](https://multiformats.io/multihash/) format.
// .hash = "...",
//
// // When this is provided, the package is found in a directory relative to the
// // build root. In this case the package's hash is irrelevant and therefore not
// // computed. This field and `url` are mutually exclusive.
// .path = "foo",
//
// // When this is set to `true`, a package is declared to be lazily
// // fetched. This makes the dependency only get fetched if it is
// // actually used.
// .lazy = false,
//},
// zig fetch https://github.com/supranational/blst/archive/refs/tags/v0.3.13.tar.gz
.blst = .{
.url = "https://github.com/supranational/blst/archive/refs/tags/v0.3.13.tar.gz",
.hash = "N-V-__8AAHB4OgByNs3JJNXs9f2gxmbJBYqM7HBRHfmwZa-e",
.url = "git+https://github.com/ChainSafe/blst.git#4d5bbcc0dd06f80b76fb124420c899570a4dd1e4",
.hash = "blst_zig-0.0.0-cnAxzogIAAB8nH6TSAGbUtZ6scv2F64aVlcuJabg5HWi",
},
},

// Specifies the set of files and directories that are included in this package.
// Only files and directories listed here are included in the `hash` that
// is computed for this package. Only files listed here will remain on disk
// when using the zig package manager. As a rule of thumb, one should list
// files required for compilation plus any license(s).
// Paths are relative to the build root. Use the empty string (`""`) to refer to
// the build root itself.
// A directory listed here means that all files within, recursively, are included.
.paths = .{
"build.zig",
"build.zig.zon",
"src",
// For example...
//"LICENSE",
//"README.md",
},
}
2 changes: 1 addition & 1 deletion bun/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
"benchmark:files": "bun ./node_modules/.bin/benchmark --config .benchrc.yaml --defaultBranch main"
},
"bun-ffi-z": {
"name": "blst_min_pk",
"name": "eth_blst",
"targets": [
"linux-x64-gnu",
"linux-arm64-gnu",
Expand Down
Loading