Best way to release packages for libraries?

Explain
2

Technically it already can be used like it is, by adding fluent as a dependency to your application project (via zig fetch --save=fluent archive.tar.gz details below) and then using something like this:

const mod_fluent = b.addModule("fluent", .{
    .root_source_file = b.dependency("fluent", .{}).path("fluent.zig"),
});
exe.root_module.addImport("fluent", mod_fluent);

However I think the nicer way (for more complex libraries) may be to provide a build.zig that declares a module, steps below.

Library

I think using zig init and removing the application specific parts, then adding the fluent.zig file as a module in the build.zig via:

_ = b.addModule("fluent", .{
    .root_source_file = .{ .path = "fluent.zig" },
});

User application

Then the user can use zig init to initialize a application project, use

zig fetch --save=fluent <commit-specific-archive-download-link>.tar.gz

to add the dependency.

And add

exe.root_module.addImport("fluent", b.dependency("fluent", .{}).module("fluent"));

to the build.zig after the exe declaration to make the module importable in the application.

Commit specific archive download link

To get the <commit-specific-archive-download-link> click on Commits on github, then Browse repository at this point, then Code and copy the Download ZIP link, then change the ending from .zip to .tar.gz

Screenshot_2024-04-17_11-21-37
Screenshot_2024-04-17_11-21-371341×257 25.9 KB

Screenshot_2024-04-17_11-23-25
Screenshot_2024-04-17_11-23-25439×667 52.6 KB

Why commit specific?

If you use an url for a branch the url+hash pair that is stored in the build.zig.zon gets broken as soon as a new commit gets pushed to the library repo, this is bad because then you are forced to update your dependency when ever the library author pushes a new change.

So with the status-quo build system, branch urls are undesireable, because their content isn’t stable and only the latest commit works, if you use it anyway, you might be forced to update the hash of the dependency, in the middle of fixing some other bug in your application.

When you use a commit specific url for the archive download, you avoid that problem, because the commit never changes, the content never changes, which means that the hash will continue to match the content, thus the library author can push new commits without users being affected.

They can update when they want to, instead of one day getting an error that the hash doesn’t match anymore.

This is only based on my current knowledge, there may be ways to make this even simpler / better.

Here is a fluentdirect-example repository that uses the fluent repo without any changes to it, the commits are separated into simple logical steps.

5 Likes