velopack-zig

Shared build glue for using Velopack from Zig projects. It wraps the Velopack runtime C API and build toolset, and builds dependencies with zig where possible.

Velopack's CLI is a .NET tool, so the .NET SDK must be installed to package.

WARNING: this project has been generally reviewed but outside of the README, small pieces of code and many large comments are AI generated and have not been rewritten yet so may be useless to read.

Add this package to your zig project

zig fetch --save "git+https://github.com/graphl-tech/velopack-zig#main"

Zig version

main targets Zig 0.17.0 (build.zig.zon minimum_zig_version).

Usage

const std = @import("std");
const velopack = @import("velopack_zig");

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

    // Gate the one thing that reaches out to the network on demand. Recommended
    // over hardcoding `true`, so a plain `zig build` is never surprising.
    const install_vpk = b.option(bool, "install-vpk", "Opt-in to installing Velopack dotnet CLI") orelse false;

    const exe = b.addExecutable(.{
        .name = "myapp",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });
    exe.linkLibC();

    velopack.linkVelopack(b, exe, .{ .target = target, .optimize = optimize });

    const staging = b.addWriteFiles();
    _ = staging.addCopyFile(exe.getEmittedBin(), if (target.result.os.tag == .windows) "myapp.exe" else "myapp");

    const packaged = velopack.addVelopackedAppDir(b, .{
        .install_dir = .prefix,
        .install_subdir = "desktop",
        .pack_opts = .{
            .name = "myapp",
            .version = "1.0.0",
            .target = target,
            .source_dir = staging.getDirectory(),
            .icon = b.path("art/icon.png"),
            .install_vpk = install_vpk,
        },
    });

    b.step("package", "Build the release bundle").dependOn(&packaged.step);
}

zig build package -Dinstall-vpk=true writes setup executables, the .nupkg and the RELEASES feed to zig-out/desktop/.

Windows ABI note

Velopack's Windows prebuilt is MSVC. Use x86_64-windows-msvc or aarch64-windows-msvc (not *-windows-gnu).

Customizing the vpk command

addVelopackedAppDir takes the vpk pack options as pack_opts, which models common flags directly: name (--packId), version, main_exe, title, authors, icon, channel, delta. Everything else goes through:

• extra_vpk_args: []const []const u8: appended verbatim, e.g. &.{ "--exclude", ".*\\.pdb", "--noPortable" }.
• extra_vpk_path_args: []const VpkPathArg: same, but the value is a path this build produces, e.g. &.{ .{ .prefix = "--releaseNotes", .path = notes } }. The pack step waits on whatever generates it.
• vpk_argv: ?[]const []const u8: run something other than the managed vpk, e.g. &.{ "dotnet", "vpk" } for a repo-local .config/dotnet-tools.json (pair it with addDotnetToolRestoreStep).

addVelopackStep returns the *std.Build.Step.Run itself if you would rather add arguments to it directly; outputDir(run) gives you the release directory.

Velopack documentation

• Docs home C / C++ quick start the C ABI these bindings link against C API reference
• vpk CLI reference: Windows, Linux, macOS,
• Packaging overview, Code signing, Release channels, Delta updates, Cross compiling
• Distributing releases, Deployment CLI