updater.zig

A production-ready Zig library for automatic update checking with multi-provider support.

📚 Documentation | API Reference | Quick Start | Contributing

A production-ready, developer-friendly update checker library for Zig applications. Check for updates from GitHub, GitLab, Codeberg, or custom providers with comprehensive version comparison and auto-update capabilities.

⭐️ If you find updater.zig useful, please give it a star! ⭐️

✨ Features of updater.zig (click to expand)

Feature	Description
🔄 Update Checking	Check for updates from multiple Git hosting providers
🌐 Multi-Provider Support	GitHub, GitLab, Codeberg, and custom providers
📊 Version Comparison	SemVer, CalVer, numeric, custom formats with suffix support
🔧 Auto-Update	Download, install, backup, and rollback functionality
💬 Custom Messages	Fully customizable update notifications and prompts
🔒 Checksum Verification	SHA256 verification for secure downloads
🏗️ Build-Time Checks	Optional update checks during build process
⏰ Background Checking	Non-blocking periodic update checks
🛡️ CI-Aware	Auto-disables in CI environments
📝 Detailed Error Messages	Human-readable errors with suggestions
🖥️ Cross-Platform	Windows, Linux, macOS (32-bit and 64-bit)
📦 Zero Dependencies	Built entirely on the Zig standard library
⚡ High Performance	Efficient HTTP requests with configurable timeouts
🔑 Auth Token Support	Private repository access via auth tokens

📌 Prerequisites & Supported Platforms (click to expand)

Prerequisites

Requirement	Version	Notes
Zig	0.15.0+	Download from ziglang.org
Operating System	Windows 10+, Linux, macOS	Cross-platform support

Supported Platforms

Platform	32-bit	64-bit	ARM	Status
Windows	✅ x86	✅ x86_64	-	Full support
Linux	✅ x86	✅ x86_64	✅ aarch64	Full support
macOS	✅ x86	✅ x86_64	✅ aarch64 (Apple Silicon)	Full support
Freestanding	✅ x86	✅ x86_64	✅ aarch64, arm, riscv64	Full support

🌐 Supported Providers (click to expand)

Provider	API	Auth Support	Rate Limits
GitHub	REST API v3	✅ Token	60/hr (5000/hr with auth)
GitLab	REST API v4	✅ Token	Varies by instance
Codeberg	Gitea API v1	✅ Token	Varies
Self-Hosted Gitea	Gitea API v1	✅ Token	Custom
Self-Hosted GitLab	REST API v4	✅ Token	Custom
Custom	User-defined	✅ Custom	Custom

Installation

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

Or for nightly installation:

zig fetch --save git+https://github.com/muhammad-fiaz/updater.zig.git

Then in your build.zig:

const updater_dep = b.dependency("updater", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("updater", updater_dep.module("updater"));

Quick Start

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

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

    // Simple GitHub update check
    const result = try updater.checkGitHub(
        allocator,
        "muhammad-fiaz",    // owner
        "updater.zig",      // repo
        "0.0.1",            // current version
    );

    if (result.has_update) {
        std.debug.print("Update available: {s}\n", .{result.latest_version.?});
        std.debug.print("Download: {s}\n", .{result.release_url.?});
    } else {
        std.debug.print("You're running the latest version!\n", .{});
    }
}

Version Comparison

updater.zig supports multiple version formats:

const updater = @import("updater");

// Semantic Versioning (default)
// 1.0.0, v1.2.3, 1.0.0-alpha, 1.0.0-beta+build
.comparator = updater.version.semantic,

// Custom Format (e.g., 0.01.1-release)
// Supports suffix ranking: release > stable > rc > beta > alpha > dev
.comparator = updater.version.custom_format,

// Numeric (e.g., 1.2, 1.10)
// Handles multi-digit components: 1.10 > 1.9
.comparator = updater.version.numeric,

// Date-Based (CalVer)
// 2024.01.15, 2024.12.31, 20240115
.comparator = updater.version.date_based,

// Lexical (string comparison)
.comparator = updater.version.lexical,

Suffix Priority

For custom versions with suffixes:

Suffix	Priority
`release`	100
`stable`	99
`final`	98
`rc`	50
`beta`	30
`alpha`	20
`dev`	10
`nightly`	5

Auto-Update

const updater = @import("updater");

var auto_updater = updater.AutoUpdater.init(allocator, .{
    .provider = updater.providers.github,
    .owner = "muhammad-fiaz",
    .repo = "updater.zig",
    .current_version = "0.0.1",
    .auto_update = .{
        .enabled = true,
        .auto_download = true,
        .auto_install = false,
        .prompt_before_update = true,
        .backup_current = true,
        .verify_checksum = true,
        .install_command = "zig build install",
        .pre_update_command = "echo Backing up...",
        .post_update_command = "echo Done!",
    },
});
defer auto_updater.deinit();

const result = try auto_updater.checkAndUpdate();

AutoUpdater Methods

Method	Description
`checkAndUpdate()`	Check and optionally update
`download()`	Download update file
`install()`	Install downloaded update
`backupCurrent()`	Backup current executable
`rollback()`	Restore from backup
`cleanup()`	Remove temporary files

Custom Providers

const updater = @import("updater");

// Self-hosted Gitea
const gitea = updater.providers.gitea("https://git.mycompany.com");

// Self-hosted GitLab
const gitlab = updater.providers.selfHostedGitlab("https://gitlab.internal.com");

const result = try updater.checkForUpdates(allocator, .{
    .provider = gitea,
    .owner = "team",
    .repo = "myproject",
    .current_version = "1.0.0",
});

Configuration

Full Configuration Options

const config = updater.UpdateConfig{
    // Core settings
    .enabled = true,
    .provider = updater.providers.github,
    .owner = "username",
    .repo = "myproject",
    .current_version = "1.0.0",
    .auth_token = null,             // For private repos
    .timeout_ms = 10000,            // 10 seconds
    .comparator = updater.version.semantic,
    .include_prereleases = false,

    // Message customization
    .messages = .{
        .show_update_available = true,
        .show_up_to_date = true,
        .show_skipped = false,
        .show_errors = true,
        .silent = false,
        .update_available_message = "New version!",
        .up_to_date_message = "Latest version.",
        .message_prefix = "[MyApp]",
        .custom_download_url = "https://example.com/download",
        .update_command = "zig fetch --save <url>",
    },

    // Auto-update settings
    .auto_update = .{
        .enabled = false,
        .auto_download = false,
        .auto_install = false,
        .prompt_before_update = true,
        .backup_current = true,
        .verify_checksum = true,
        .install_command = "zig build install",
    },
};

Config Builder (Fluent API)

var builder = updater.configBuilder();
const config = try builder
    .provider(updater.providers.github)
    .owner("muhammad-fiaz")
    .repo("updater.zig")
    .currentVersion("0.0.1")
    .customMessage("Update available!")
    .enableAutoUpdate()
    .silentMode()
    .build();

Error Handling

updater.zig provides detailed error information:

const result = updater.checkForUpdates(allocator, config) catch |err| {
    const info = updater.core.getUpdateErrorInfo(err);
    std.debug.print("Error: {s}\n", .{info.message});
    std.debug.print("Details: {s}\n", .{info.details.?});
    std.debug.print("Suggestion: {s}\n", .{info.suggestion.?});
    return;
};

Error Types

Error	Description	Suggestion
`ConnectionFailed`	Network connection failed	Check internet connection
`HttpNotFound`	Repository or release not found (404)	Verify owner/repo and release exists
`HttpUnauthorized`	Authentication required (401)	Provide valid auth_token
`HttpForbidden`	Access denied (403)	Check repo visibility or token scopes
`HttpRateLimited`	Too many requests (429)	Wait or use auth_token
`InvalidJson`	Invalid API response	API may have changed
`MissingField`	Required field missing	Ensure release has proper metadata
`ChecksumMismatch`	Download verification failed	Re-download the file

Build-Time Integration

Add update checking to your build process:

const updater = @import("updater");

pub fn build(b: *std.Build) void {
    // ... your build setup ...

    updater.build_integration.addUpdateCheck(b, .{
        .owner = "muhammad-fiaz",
        .repo = "updater.zig",
        .current_version = "0.1.0",
        .provider = .github,
    });
}

Environment Variables

Variable	Effect
`ZIG_UPDATE_CHECK_DISABLE`	Disables all update checks
`CI`	Auto-disables checks in CI
`GITHUB_ACTIONS`	Auto-disables checks in GitHub CI
`GITLAB_CI`	Auto-disables checks in GitLab CI

API Reference

Module Functions

Function	Description
`checkForUpdates(allocator, config)`	Perform update check with config
`checkGitHub(allocator, owner, repo, version)`	Quick GitHub check
`checkGitLab(allocator, owner, repo, version)`	Quick GitLab check
`checkCodeberg(allocator, owner, repo, version)`	Quick Codeberg check
`checkAndUpdate(allocator, config)`	Check and auto-update
`formatUpdateMessage(allocator, result, config)`	Format result message
`printUpdateMessage(result, config)`	Print formatted message
`isGloballyDisabled()`	Check if updates are disabled
`isCI()`	Check if running in CI
`configBuilder()`	Create fluent config builder

Providers

Provider	Description
`providers.github`	GitHub API provider
`providers.gitlab`	GitLab API provider
`providers.codeberg`	Codeberg (Gitea) API provider
`providers.gitea(base_url)`	Self-hosted Gitea provider
`providers.selfHostedGitlab(url)`	Self-hosted GitLab provider
`providers.custom(...)`	Fully custom provider

Version Comparators

Comparator	Description
`version.semantic`	SemVer (1.2.3, v1.2.3-alpha)
`version.custom_format`	Custom with suffix (0.01.1-release)
`version.numeric`	Numeric (1.2, 1.10)
`version.date_based`	CalVer (2024.01.15)
`version.lexical`	String comparison

Examples Directory

The examples/ directory contains comprehensive examples:

basic.zig - Core operations and getting started
custom_provider.zig - Self-hosted and custom providers
runtime_check.zig - Runtime checking and auto-update
version_compare.zig - Version comparison strategies
all_features.zig - Complete feature demonstration

Building

# Run tests
zig build test --summary all

# Build library
zig build

# Run basic example
zig build example

# Run all examples
zig build examples

# Run specific example
zig build run-basic
zig build run-version_compare
zig build run-all_features

# Format code
zig fmt src/ examples/

Documentation

Full documentation: https://muhammad-fiaz.github.io/updater.zig/

Contributing

Contributions are welcome! Please read CONTRIBUTING.md.

License

MIT License - see LICENSE.

Links

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

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.github		.github
docs		docs
examples		examples
src		src
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
build.zig		build.zig
build.zig.zon		build.zig.zon

Uh oh!

License

muhammad-fiaz/updater.zig

Folders and files

Latest commit

History

Repository files navigation

updater.zig

Prerequisites

Supported Platforms

Installation

Quick Start

Version Comparison

Suffix Priority

Auto-Update

AutoUpdater Methods

Custom Providers

Configuration

Full Configuration Options

Config Builder (Fluent API)

Error Handling

Error Types

Build-Time Integration

Environment Variables

API Reference

Module Functions

Providers

Version Comparators

Examples Directory

Building

Documentation

Contributing

License

Links

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 1

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Languages

Packages