https://github.com/muhammad-fiaz/archive.zig

All-in-One archive and compression library for Zig, supporting multiple compression algorithms and archive formats with a clean, intuitive API.
https://github.com/muhammad-fiaz/archive.zig
compression-zig-library decompress-zig zig zig-compress zig-compression zig-compression-lib zig-lang zig-language zig-lib zig-library zig-package
Last synced: about 19 hours ago
JSON representation
All-in-One archive and compression library for Zig, supporting multiple compression algorithms and archive formats with a clean, intuitive API.
Host: GitHub
URL: https://github.com/muhammad-fiaz/archive.zig
Owner: muhammad-fiaz
License: mit
Created: 2026-01-25T12:34:54.000Z (5 months ago)
Default Branch: main
Last Pushed: 2026-01-29T21:28:34.000Z (5 months ago)
Last Synced: 2026-04-22T15:40:31.809Z (about 2 months ago)
Topics: compression-zig-library, decompress-zig, zig, zig-compress, zig-compression, zig-compression-lib, zig-lang, zig-language, zig-lib, zig-library, zig-package
Language: Zig
Homepage: https://muhammad-fiaz.github.io/archive.zig/
Size: 213 KB
Stars: 5
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yaml
- License: LICENSE
Awesome Lists containing this project

README

          


   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](#prerequisites)

- [Supported Platforms](#supported-platforms)

- [Supported Algorithms](#supported-algorithms)

- [Installation](#installation)

  - [Method 1: Zig Fetch (Recommended)](#method-1-zig-fetch-recommended)

  - [Method 2: Manual Configuration](#method-2-manual-configuration)

  - [Method 3: Building from Source](#method-3-building-from-source)

- [Quick Start](#quick-start)

- [Usage Examples](#usage-examples)

  - [Basic Compression](#basic-compression)

  - [Configuration Presets](#configuration-presets)

  - [Builder Pattern](#builder-pattern)

  - [Auto-Detection](#auto-detection)

  - [File Operations](#file-operations)

  - [Streaming Interface](#streaming-interface)

- [Configuration](#configuration)

- [API Reference](#api-reference)

- [Building](#building)

- [Documentation](#documentation)

- [Contributing](#contributing)

- [License](#license)

- [Links](#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](https://muhammad-fiaz.github.io/archive.zig/guide/algorithms) |

| **Simple & Clean API** | User-friendly compression interface (`archive.compress()`, `archive.decompress()`, etc.) | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/getting-started) |

| **Configuration Presets** | Pre-configured settings for fast, balanced, best compression, and production use | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/configuration) |

| **Builder Pattern** | Fluent API for configuring compression with method chaining | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/builder) |

| **Auto-Detection** | Automatic algorithm detection from compressed data headers | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/auto-detection) |

| **Streaming Interface** | Memory-efficient streaming compression and decompression | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/streaming) |

| **File Operations** | Direct file compression and decompression with proper error handling | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/file-operations) |

| **Cross-Platform** | Works on Windows, Linux, macOS, and bare metal targets | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/platforms) |

| **Thread-Safe** | Safe concurrent compression from multiple threads | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/threading) |

| **Memory Efficient** | Optimized memory usage with configurable buffer sizes | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/memory) |

| **Error Handling** | Comprehensive error types and proper error propagation | [Docs](https://muhammad-fiaz.github.io/archive.zig/guide/errors) |

| **Utility Functions** | Helper functions for size formatting, CRC calculation, and more | [Docs](https://muhammad-fiaz.github.io/archive.zig/api/utils) |

---

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](https://ziglang.org/download/) |

| **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:

```bash

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`:

```zig

.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`:

```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:

```bash

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

cd archive.zig

zig build

```

## Quick Start

```zig

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

```zig

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

```zig

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

```zig

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

```zig

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

```zig

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

```zig

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

```zig

// 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

```zig

// 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

```zig

pub const Algorithm = enum {

    gzip,

    zlib,

    deflate,

    zstd,

    lz4,

    lzma,

    xz,

    tar_gz,

    zip,

    

    pub fn extension(self: Algorithm) []const u8

};

```

### Configuration

```zig

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

```bash

# 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:

```bash

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](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
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/muhammad-fiaz/archive.zig

Awesome Lists containing this project

README

Archive.zig
