libh2o for zig

This is libh2o, packaged for Zig with cross-compilation support for Linux and macos.

• all dependencies are statically linked into the output
• output is a static library (.a) for embedding into other projects

The intended usage is for building language bindings and FFI wrappers that need to expose all h2o and SSL symbols in a final shared library.

Included features:

• http 1
• http 2
• quic + http3
• brotli
• zstd

h2o features explicitly excluded:

• mruby
• memcached integration
• redis integration
• libuv

Supported targets

• linux x86_64
• linux aarch64
• macos x86_64
• macos aarch64

Quick start

1. Install zig
2. zig build

Prerequisites

You need the following installed:

• Zig 0.15.2
• Perl (for an h2o build step)

If you have nix you can use the dev shell provided by the flake in this repo.

Use as a dependency

First, update your build.zig.zon:

zig init # if you don't have a build.zig already
zig fetch --save git+https://github.com/outskirtslabs/h2o-zig.git

You can then import h2o in your build.zig with:

const h2o_dependency = b.dependency("h2o", .{
    .target = target,
    .optimize = optimize,
});
your_exe.linkLibrary(h2o_dependency.artifact("h2o-evloop"));

Build Options

The following build-time flags are available:

• -Duse-boringssl=<bool> - Use BoringSSL instead of OpenSSL (default: true)
• -Duse-external-brotli=<bool> - Use external brotli dependency instead of vendored sources (default: true). The vendored one is from upstream h2o and is a much older version than the external one.

Example usage:

const h2o_dependency = b.dependency("h2o", .{
    .target = target,
    .optimize = optimize,
    .@"use-boringssl" = true, // default
});
your_exe.linkLibrary(h2o_dependency.artifact("h2o-evloop"));

Or via command line when building:

zig build -Duse-boringssl=true

Cross-Compilation to macOS

When cross-compiling from Linux to macOS targets (x86_64-macos or aarch64-macos), the build requires the APPLE_SDK_PATH environment variable to be set. This points to the macOS SDK that provides system headers and libraries.

Using Nix (Recommended)

The provided nix flake automatically sets up APPLE_SDK_PATH when you enter the development shell:

nix develop
zig build -Dtarget=aarch64-macos
zig build -Dtarget=x86_64-macos

Manual Setup

If not using nix, you'll need to obtain a macOS SDK and set the environment variable:

export APPLE_SDK_PATH=/path/to/MacOSX.sdk
zig build -Dtarget=x86_64-macos

The SDK must contain usr/include with macOS system headers. Without this, cross-compilation to macOS will fail with an error about the missing APPLE_SDK_PATH environment variable.

Note: Cross-compilation to macOS from macOS does not require APPLE_SDK_PATH as the system SDK is used automatically.

Hacking on H2O

This project also serves as a reproducible dev environment for h2o thanks to the nix flake

Simply activate the nix devshell then:

git clone https://github.com/h2o/h2o.git h2o
cd h2o
cmake -B build -S .  -DDISABLE_LIBUV=ON -DWITH_MRUBY=OFF
cmake --build build -j$(nproc)
cmake --build build --target check

License: MIT License

h2o-zig is distributed under the MIT.

Copyright © 2025 Casey Link [email protected]

Binary distributions (JAR files on Clojars and GitHub releases) may bundle the following third-party projects:

• h2o is licensed under the MIT License and copyright DeNA Co., Ltd., Kazuho Oku, and contributors.

• brotli is licensed under the MIT License and copyright (c) 2009, 2010, 2013-2016 by the Brotli Authors.

• zstd is licensed under the BSD License and copyright (c) Meta Platforms, Inc.

• OpenSSL is licensed under the Apache 2.0 License and copyright (c) 1998-2025 The OpenSSL Project Authors, and copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson.

• BoringSSL is licensed under the Apache 2.0 License and copyright a bunch of folks