Installation

compressionz can be added to any Zig project using the standard build system.

Requirements

• Zig 0.15.0 or later
• No additional system dependencies

Installation via build.zig.zon

Step 1: Add the Dependency

Add compressionz to your build.zig.zon:

build.zig.zon

.{
    .name = "my-project",
    .version = "0.1.0",
    .dependencies = .{
        .compressionz = .{
            .url = "https://github.com/NerdMeNot/compressionz/archive/refs/tags/v1.0.0-zig0.15.2.tar.gz",
            .hash = "1220...", // Zig will tell you this on first build
        },
    },
    .paths = .{"."},
}

For local development, use a path dependency:

build.zig.zon

.dependencies = .{
    .compressionz = .{
        .path = "../compressionz",
    },
},

Step 2: Configure build.zig

Add compressionz to your build configuration:

build.zig

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // Get compressionz dependency
    const compressionz = b.dependency("compressionz", .{
        .target = target,
        .optimize = optimize,
    });

    // Create your executable
    const exe = b.addExecutable(.{
        .name = "my-app",
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    });

    // Add compressionz module
    exe.root_module.addImport("compressionz", compressionz.module("compressionz"));

    b.installArtifact(exe);
}

Step 3: Import and Use

src/main.zig

const std = @import("std");
const cz = @import("compressionz");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    const data = "Hello, compressionz!";

    const compressed = try cz.compress(.zstd, data, allocator);
    defer allocator.free(compressed);

    std.debug.print("Compressed {} bytes to {} bytes\n", .{
        data.len,
        compressed.len,
    });
}

Step 4: Build

# Build your project
zig build

# Run your project
zig build run

Verifying Installation

Create a simple test file to verify everything works:

src/verify.zig

const std = @import("std");
const cz = @import("compressionz");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    const original = "The quick brown fox jumps over the lazy dog.";

    // Test each codec
    inline for ([_]cz.Codec{ .lz4, .snappy, .zstd, .gzip, .brotli }) |codec| {
        const compressed = try cz.compress(codec, original, allocator);
        defer allocator.free(compressed);

        const decompressed = try cz.decompress(codec, compressed, allocator);
        defer allocator.free(decompressed);

        std.debug.print("{s}: {d} -> {d} bytes ✓\n", .{
            codec.name(),
            original.len,
            compressed.len,
        });

        std.debug.assert(std.mem.eql(u8, original, decompressed));
    }

    std.debug.print("\nAll codecs working correctly!\n", .{});
}

Expected output:

LZ4: 44 -> 63 bytes ✓
Snappy: 44 -> 46 bytes ✓
Zstandard: 44 -> 53 bytes ✓
Gzip: 44 -> 64 bytes ✓
Brotli: 44 -> 48 bytes ✓

All codecs working correctly!

Build Optimization

For production builds, always use release optimizations:

# Development (debug)
zig build

# Production (optimized)
zig build -Doptimize=ReleaseFast

# Smaller binary
zig build -Doptimize=ReleaseSmall

# Safe release (keeps safety checks)
zig build -Doptimize=ReleaseSafe

Performance difference is significant:

Mode	LZ4 Compression	Zstd Compression
Debug	~500 MB/s	~200 MB/s
ReleaseFast	~36 GB/s	~12 GB/s

Troubleshooting

Hash Mismatch

If you see a hash mismatch error:

error: hash mismatch
expected: 1220abc...
found:    1220def...

Update your build.zig.zon with the correct hash shown in the error.

Missing Dependency

If the build can’t find compressionz:

error: unable to find dependency 'compressionz'

1. Check your build.zig.zon spelling
2. Ensure the URL or path is correct
3. Run zig build again to fetch dependencies

C Compilation Errors

compressionz vendors C libraries. If you see C compilation errors:

1. Ensure you’re using Zig 0.15.0+
2. Check your target is supported
3. File an issue with the full error output

Next Steps

Now that compressionz is installed:

1. Quick Start Guide — Learn basic usage
2. Choosing a Codec — Pick the right algorithm
3. API Reference — Full API documentation