Configuration

Complete reference for all configuration options in updater.zig.

Build Options

Configure via zig build command line or as dependency options.

Option	Type	Default	Description
enable_update_checker	bool	true	Master switch for all update checking
allow_build_time_check	bool	true	Allow build-time update checks
allow_runtime_check	bool	true	Allow runtime update checks
default_timeout_ms	u64	10000	Default HTTP timeout (milliseconds)
default_interval_seconds	u64	86400	Default background check interval

Command Line Usage

zig build \
    -Denable_update_checker=true \
    -Dallow_build_time_check=true \
    -Dallow_runtime_check=true \
    -Ddefault_timeout_ms=5000 \
    -Ddefault_interval_seconds=3600

Dependency Usage

const updater_dep = b.dependency("updater", .{
    .target = target,
    .optimize = optimize,
    .enable_update_checker = true,
    .default_timeout_ms = 5000,
});

UpdateConfig

Runtime configuration for update checking.

pub const UpdateConfig = struct {
    /// Enable/disable update checking
    enabled: bool = true,

    /// Run checks in background thread
    background: bool = false,

    /// Check interval for background mode (seconds)
    interval_seconds: u64 = 86400,

    /// HTTP request timeout (milliseconds)
    timeout_ms: u64 = 10000,

    /// Git provider to use
    provider: GitProvider,

    /// Repository owner/organization
    owner: []const u8,

    /// Repository name
    repo: []const u8,

    /// Current version of the application
    current_version: []const u8,

    /// Version comparator (default: semantic)
    comparator: ?VersionComparator = null,

    /// Callback for background mode
    on_update: ?*const fn (UpdateResult) void = null,

    /// Include prerelease versions
    include_prereleases: bool = false,

    /// Custom User-Agent string
    user_agent: ?[]const u8 = null,
};

Example

const config = updater.UpdateConfig{
    .enabled = true,
    .background = false,
    .timeout_ms = 5000,
    .provider = updater.providers.github,
    .owner = "username",
    .repo = "project",
    .current_version = "1.0.0",
    .comparator = updater.version.semantic,
    .include_prereleases = false,
};

BuildConfig

Configuration for build-time update checking.

pub const BuildConfig = struct {
    /// Repository owner (required)
    owner: []const u8,

    /// Repository name (required)
    repo: []const u8,

    /// Current version (required)
    current_version: []const u8,

    /// Provider to use
    provider: Provider = .github,

    /// Show warnings
    show_warnings: bool = true,

    pub const Provider = enum {
        github,
        gitlab,
        codeberg,
    };
};

Example

updater.build_integration.addUpdateCheck(b, .{
    .owner = "username",
    .repo = "project",
    .current_version = "1.0.0",
    .provider = .github,
    .show_warnings = true,
});

Environment Variables

Variable	Effect
ZIG_UPDATE_CHECK_DISABLE	Disable all update checking globally
CI	Auto-detect CI environment
GITHUB_ACTIONS	Detect GitHub Actions
GITLAB_CI	Detect GitLab CI
CIRCLECI	Detect CircleCI
TRAVIS	Detect Travis CI
JENKINS_URL	Detect Jenkins
BUILDKITE	Detect Buildkite
DRONE	Detect Drone
AZURE_PIPELINES	Detect Azure Pipelines

Provider Configuration

Built-in Providers

// GitHub
.provider = updater.providers.github,

// GitLab
.provider = updater.providers.gitlab,

// Codeberg
.provider = updater.providers.codeberg,

Self-hosted Providers

// Gitea/Forgejo
.provider = updater.providers.gitea("https://git.example.com"),

// GitLab
.provider = updater.providers.selfHostedGitlab("https://gitlab.example.com"),

Custom Providers

.provider = updater.providers.custom(
    "name",
    buildUrlFn,
    parseFn,
    &headers,
),

Version Comparators

// Semantic versioning (X.Y.Z)
.comparator = updater.version.semantic,

// Numeric (any number of parts)
.comparator = updater.version.numeric,

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

// Date-based (YYYY.MM.DD)
.comparator = updater.version.date_based,

// Custom
.comparator = myCustomComparator,

Timeout Recommendations

Scenario	Recommended Timeout
Fast networks	3000ms
Normal networks	5000-10000ms
Slow/unreliable	15000-30000ms
Build-time	10000ms (default)

Interval Recommendations

Scenario	Recommended Interval
Frequent updates	3600s (1 hour)
Normal	86400s (24 hours)
Infrequent	604800s (1 week)

Next Steps

• Getting Started - Introduction
• API Reference - Complete API documentation