Chilkat for Zig — the chilkat package

Add to your project

zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz

This downloads the package, computes its hash, and adds it to your build.zig.zon:

.dependencies = .{
    .chilkat = .{
        .url = "https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz",
        .hash = "chilkat-11.6.1-meH2h_cVRQBe0HsdEAtbobAqUxn2iUOQ0mPseXeWLfOM",
    },
},

Then import the module in build.zig:

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

zig build now links Chilkat. The package declares one lazy dependency per supported target (chilkat-zig-<triple>.tar.gz, a prebuilt static libchilkat.a), so only the archive for the target you are building is ever downloaded, and the Zig package manager checks it against the hash recorded in the package. Cross-compiling is zig build -Dtarget=aarch64-linux-musl — nothing else changes.

Quick start

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

pub fn main(init: std.process.Init) !void {
    const alloc = init.gpa;

    // Any non-empty string unlocks the fully functional 30-day trial.
    try chilkat.unlockBundle("Anything for 30-day trial");

    const http = try chilkat.Http.init();
    defer http.deinit();
    http.setConnectTimeout(30);

    const body = http.quickGetStr(alloc, "https://example.com/") catch |err| {
        const text = try http.getLastErrorText(alloc);   // why it failed
        defer alloc.free(text);
        std.debug.print("{s}\n", .{text});
        return err;
    };
    defer alloc.free(body);   // string results are yours to free

    std.debug.print("HTTP {d}, {d} bytes\n", .{ http.getLastStatus(), body.len });
}

Methods that can fail return an error union (error.ChilkatFailed); the object's getLastErrorText explains the failure and the object stays usable. String results are owned copies made with the allocator you pass, and objects returned by a method are owned by you (defer x.deinit()).

Supported targets

A prebuilt Chilkat static library, compiled with zig c++, is published for each of these targets with every Chilkat release. The archive name is chilkat-zig-<triple>.tar.gz.

The archive is chosen from the build target, not the host. A target not in this table fails the build with a message naming it; chilkat-lib-dir lets you link a library you built yourself, and Chilkat support can tell you about other targets.

Offline builds, vendoring, and your own Chilkat library

To build without downloading the native library, pass a directory containing libchilkat.a for the target as the chilkat-lib-dir option of the dependency:

const chilkat = b.dependency("chilkat", .{
    .target = target,
    .optimize = optimize,
    .@"chilkat-lib-dir" = @as([]const u8, "/opt/chilkat/zig/x86_64-linux-gnu"),
});

With the option set, no native archive is fetched. To populate the directory, download the archive for your target once from a connected machine and unpack it:

https://chilkatdownload.com/<version>/chilkat-zig-<triple>.tar.gz

# for example, for Chilkat 11.6.1 on 64-bit Linux (glibc):
https://chilkatdownload.com/11.6.1/chilkat-zig-x86_64-linux-gnu.tar.gz

Each archive contains libchilkat.a, license.pdf, a software bill of materials and a VERSION file. Alternatively, let a connected machine run the build once and copy the Zig package cache: fetched packages are stored by hash and reused without network access, and the package archive itself can be fetched from a local path or an internal mirror (zig fetch --save /path/to/chilkat-zig-11.6.1.tar.gz) — the hash is the same wherever it comes from.

How the Chilkat API maps to Zig

The reference documentation shows the exact Zig signature of every member; the same text is in the package as doc comments (zig build docs).

Events and threads

The event-capable classes (Http, Ftp2, SFtp, Zip, Bz2, MailMan, …) take any struct that declares one or more of abortCheck, percentDone and progressInfo. The callbacks run on the calling thread, inside the method call; return true to abort.

const Progress = struct {
    pub fn percentDone(_: *Progress, pct: i32) bool {
        std.debug.print("{d}%\n", .{pct});
        return false;   // true aborts the method in progress
    }
};

var progress = Progress{};
zip.setEventHandler(&progress);   // progress must outlive the installation
defer zip.clearEventHandler();

A Chilkat object may be used by one thread at a time and may be handed from one thread to another. To cancel from another thread, have abortCheck read a std.atomic.Value(bool).

Licensing

This is the full-version Chilkat product. Chilkat libraries are fully functional for a 30-day evaluation; passing any non-empty string to chilkat.unlockBundle starts the trial, and a purchased unlock code removes the time limit. The license terms are in the LICENSE file of the package (and license.pdf in every native archive). For questions, see the reference documentation or contact Chilkat support.