Archive.zig

A comprehensive, high-performance archive and compression library for Zig.

Documentation | API Reference | Quick Start | Contributing

All-in-One archive and compression library for Zig, supporting multiple compression algorithms and archive formats with a clean, intuitive API.

⭐️ If you love archive.zig, make sure to give it a star! ⭐️

---

Table of Contents (click to expand)

• Prerequisites
• Supported Platforms
• Supported Algorithms
• Installation
  • Method 1: Zig Fetch (Recommended)
  • Method 2: Manual Configuration
  • Method 3: Building from Source
• Quick Start
• Usage Examples
  • Basic Compression
  • Configuration Presets
  • Builder Pattern
  • Auto-Detection
  • File Operations
  • Streaming Interface
• Configuration
• API Reference
• Building
• Documentation
• Contributing
• License
• Links

---

Features of Archive.zig (click to expand)

Feature	Description	Documentation
Multiple Algorithms	Support for 9 compression algorithms: gzip, zlib, deflate, zstd, lz4, lzma, xz, tar.gz, zip	Docs
Simple & Clean API	User-friendly compression interface (archive.compress(), archive.decompress(), etc.)	Docs
Configuration Presets	Pre-configured settings for fast, balanced, best compression, and production use	Docs
Builder Pattern	Fluent API for configuring compression with method chaining	Docs
Auto-Detection	Automatic algorithm detection from compressed data headers	Docs
Streaming Interface	Memory-efficient streaming compression and decompression	Docs
File Operations	Direct file compression and decompression with proper error handling	Docs
Cross-Platform	Works on Windows, Linux, macOS, and bare metal targets	Docs
Thread-Safe	Safe concurrent compression from multiple threads	Docs
Memory Efficient	Optimized memory usage with configurable buffer sizes	Docs
Error Handling	Comprehensive error types and proper error propagation	Docs
Utility Functions	Helper functions for size formatting, CRC calculation, and more	Docs

---

Prerequisites & Supported Platforms (click to expand)

Prerequisites

Before installing Archive.zig, ensure you have the following:

Requirement	Version	Notes
Zig	0.15.0+	Download from ziglang.org
Operating System	Windows 10+, Linux, macOS	Cross-platform support
Memory	64MB+ available	For compression operations

Verify your Zig installation by running zig version in your terminal.

---

Supported Platforms

Archive.zig supports a wide range of platforms and architectures:

Platform	Architectures	Status
Windows	x86_64, x86	Full support
Linux	x86_64, x86, aarch64	Full support
macOS	x86_64, aarch64 (Apple Silicon)	Full support
Bare Metal / Freestanding	x86_64, aarch64, arm, riscv64	Full support

---

Supported Algorithms

Algorithm	Extension	Description	Performance
gzip	.gz	GNU zip compression with CRC32	Fast
zlib	.zlib	Deflate with Adler32 checksum	Fast
deflate	.deflate	Raw deflate compression	Fastest
zstd	.zst	Zstandard - modern, fast compression	Very Fast
lz4	.lz4	Ultra-fast compression	Fastest
lzma	.lzma	High compression ratio	Slow
xz	.xz	LZMA2-based compression	Slow
tar.gz	.tar.gz	TAR archive with gzip compression	Fast
zip	.zip	ZIP archive format	Fast

---

Installation

Method 1: Zig Fetch (Recommended)

The easiest way to add Archive.zig to your project:

zig fetch --save https://github.com/muhammad-fiaz/archive.zig/archive/refs/tags/0.0.1.tar.gz

This automatically adds the dependency with the correct hash to your build.zig.zon.

Method 2: Manual Configuration

Add to your build.zig.zon:

.dependencies = .{
    .archive = .{
        .url = "https://github.com/muhammad-fiaz/archive.zig/archive/refs/tags/0.0.1.tar.gz",
        .hash = "...", // Run zig fetch to get the hash
    },
},

Then in your build.zig:

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

exe.root_module.addImport("archive", archive.module("archive"));

Method 3: Building from Source

Clone the repository and build Archive.zig:

git clone https://github.com/muhammad-fiaz/archive.zig.git
cd archive.zig
zig build

Quick Start

const std = @import("std");
const archive = @import("archive");

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

    // Basic compression
    const input = "Hello, World! This is a test of the archive library.";
    
    // Compress with different algorithms
    const gzip_compressed = try archive.compress(allocator, input, .gzip);
    defer allocator.free(gzip_compressed);
    
    const zstd_compressed = try archive.compress(allocator, input, .zstd);
    defer allocator.free(zstd_compressed);
    
    // Decompress
    const decompressed = try archive.decompress(allocator, gzip_compressed, .gzip);
    defer allocator.free(decompressed);
    
    std.debug.print("Original: {s}\n", .{input});
    std.debug.print("Decompressed: {s}\n", .{decompressed});
    std.debug.print("Compression ratio: {d:.1}%\n", .{
        @as(f64, @floatFromInt(gzip_compressed.len)) / @as(f64, @floatFromInt(input.len)) * 100
    });
}

Usage Examples

Basic Compression

const std = @import("std");
const archive = @import("archive");

pub fn basicCompression(allocator: std.mem.Allocator) !void {
    const input = "Hello, World! This is a test of compression.";
    
    // Try different algorithms
    const algorithms = [_]archive.Algorithm{
        .gzip, .zlib, .deflate, .zstd, .lz4, .lzma, .xz, .tar_gz, .zip
    };
    
    for (algorithms) |algo| {
        const compressed = try archive.compress(allocator, input, algo);
        defer allocator.free(compressed);
        
        const decompressed = try archive.decompress(allocator, compressed, algo);
        defer allocator.free(decompressed);
        
        const ratio = @as(f64, @floatFromInt(compressed.len)) / @as(f64, @floatFromInt(input.len)) * 100;
        std.debug.print("{s}: {d} bytes ({d:.1}%)\n", .{ @tagName(algo), compressed.len, ratio });
    }
}

Configuration Presets

pub fn configurationPresets(allocator: std.mem.Allocator) !void {
    const input = "Configuration preset test data for compression.";
    
    // Use different presets
    const presets = [_]archive.CompressionConfig{
        archive.CompressionConfig.fast(),
        archive.CompressionConfig.balanced(),
        archive.CompressionConfig.best(),
        archive.CompressionConfig.zstd(),
        archive.CompressionConfig.production(),
    };
    
    for (presets) |preset| {
        const compressed = try archive.compressWithConfig(allocator, input, preset);
        defer allocator.free(compressed);
        
        std.debug.print("Preset: {d} bytes\n", .{compressed.len});
    }
}

Builder Pattern

pub fn builderPattern(allocator: std.mem.Allocator) !void {
    const input = "Builder pattern example data.";
    
    // Configure compression with builder pattern
    const compressor = archive.Compressor.init(allocator, .gzip)
        .withLevel(6)
        .withChecksum();
    
    const compressed = try compressor.compress_data(input);
    defer allocator.free(compressed);
    
    const decompressed = try compressor.decompress_data(compressed);
    defer allocator.free(decompressed);
    
    std.debug.print("Builder pattern: {d} bytes\n", .{compressed.len});
}

Auto-Detection

pub fn autoDetection(allocator: std.mem.Allocator) !void {
    const input = "Auto-detection test data.";
    
    // Compress with gzip
    const compressed = try archive.compress(allocator, input, .gzip);
    defer allocator.free(compressed);
    
    // Auto-detect algorithm and decompress
    const detected = archive.detectAlgorithm(compressed);
    const auto_decomp = try archive.autoDecompress(allocator, compressed);
    defer allocator.free(auto_decomp);
    
    std.debug.print("Detected algorithm: {?}\n", .{detected});
    std.debug.print("Auto-decompressed: {s}\n", .{auto_decomp});
}

File Operations

pub fn fileOperations(allocator: std.mem.Allocator) !void {
    const test_data = "This is test data for file operations.";
    
    // Write test file
    try std.fs.cwd().writeFile(.{ .sub_path = "test.txt", .data = test_data });
    
    // Compress to file
    const compressed = try archive.compress(allocator, test_data, .gzip);
    defer allocator.free(compressed);
    
    try std.fs.cwd().writeFile(.{ .sub_path = "test.gz", .data = compressed });
    
    // Read and decompress
    const read_compressed = try std.fs.cwd().readFileAlloc(allocator, "test.gz", 1024 * 1024);
    defer allocator.free(read_compressed);
    
    const decompressed = try archive.decompress(allocator, read_compressed, .gzip);
    defer allocator.free(decompressed);
    
    std.debug.print("File operations successful: {}\n", .{std.mem.eql(u8, test_data, decompressed)});
    
    // Cleanup
    std.fs.cwd().deleteFile("test.txt") catch {};
    std.fs.cwd().deleteFile("test.gz") catch {};
}

Streaming Interface

pub fn streamingInterface(allocator: std.mem.Allocator) !void {
    const input = "Large data for streaming compression...";
    
    // Create streaming compressor
    var compressor = try archive.StreamingCompressor.init(allocator, .gzip);
    defer compressor.deinit();
    
    // Compress in chunks
    try compressor.write(input[0..10]);
    try compressor.write(input[10..]);
    const compressed = try compressor.finish();
    defer allocator.free(compressed);
    
    // Create streaming decompressor
    var decompressor = try archive.StreamingDecompressor.init(allocator, .gzip);
    defer decompressor.deinit();
    
    const decompressed = try decompressor.decompress(compressed);
    defer allocator.free(decompressed);
    
    std.debug.print("Streaming: {s}\n", .{decompressed});
}

Configuration

// Basic configuration
var config = archive.CompressionConfig.default();
config.level = 6;
config.checksum = true;

// Use configuration
const compressed = try archive.compressWithConfig(allocator, data, config);

// Preset configurations
const fast_config = archive.CompressionConfig.fast();
const best_config = archive.CompressionConfig.best();
const production_config = archive.CompressionConfig.production();

// Algorithm-specific configurations
const zstd_config = archive.CompressionConfig.zstdWithLevel(15);
const lz4_config = archive.CompressionConfig.lz4Fast();

API Reference

Core Functions

// Basic compression/decompression
pub fn compress(allocator: Allocator, data: []const u8, algorithm: Algorithm) ![]u8
pub fn decompress(allocator: Allocator, data: []const u8, algorithm: Algorithm) ![]u8

// With configuration
pub fn compressWithConfig(allocator: Allocator, data: []const u8, config: CompressionConfig) ![]u8

// Auto-detection
pub fn detectAlgorithm(data: []const u8) ?Algorithm
pub fn autoDecompress(allocator: Allocator, data: []const u8) ![]u8

Algorithms

pub const Algorithm = enum {
    gzip,
    zlib,
    deflate,
    zstd,
    lz4,
    lzma,
    xz,
    tar_gz,
    zip,
    
    pub fn extension(self: Algorithm) []const u8
};

Configuration

pub const CompressionConfig = struct {
    algorithm: Algorithm,
    level: ?u8,
    checksum: bool,
    include_patterns: []const []const u8,
    exclude_patterns: []const []const u8,
    
    pub fn fast() CompressionConfig
    pub fn balanced() CompressionConfig
    pub fn best() CompressionConfig
    pub fn zstd() CompressionConfig
    pub fn production() CompressionConfig
};

Building

# Run tests
zig build test

# Build library
zig build

# Run examples
zig build run

# Build documentation
zig build docs

Documentation

Online Documentation

Full documentation is available at: https://muhammad-fiaz.github.io/archive.zig

Generating Local Documentation

To generate documentation locally:

zig build docs

This will generate HTML documentation in the zig-out/docs/ directory.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Links

• Documentation: https://muhammad-fiaz.github.io/archive.zig
• Repository: https://github.com/muhammad-fiaz/archive.zig
• Issues: https://github.com/muhammad-fiaz/archive.zig/issues
• Releases: https://github.com/muhammad-fiaz/archive.zig/releases