Publishing libgpiod-sys and libgpiod to crates.io

Hi all,

After merging of [1] only some cosmetics should be missing from being able to publish to crates.io.

First, we would need to agree on a version number (or rather a release management process). Rust is suggesting people to follow a SemVer approach [2] and I would strongly suggest to stick to that recommendation. We _could_ just start releasing with the next libgpiod release and have the Rust bindings follow the libgpiod releases. While this may seem intuitive to users (they can just spell libgpiod = 2.0.1 and reason easily about which libgpiod version is in use), it would come with a couple of implications:

1. Users would likely expect new features of a C lib release to also be usable from the Rust crate if it uses the same versioning scheme. So this would also tie the necessary effort to expose those features from the Rust bindings to the release process.
2. Supporting multiple versions of the C lib with the Rust bindings would be no problem in general, but would become awkward when trying to replicate the version numbers of the C lib.
3. Changes to the Rust bindings would always require an overall version bump.
4. There may be a conflict between SemVer bumps for the whole of libgpiod vs a bump that would be required for the Rust bindings only.

This all seems pretty restrictive and undesirable to me... So I would recommend to manage the version numbers of libgpiod and the Rust crates libgpiod-sys and libgpiod all separately. It may help to think of the versions of the Rust crates as ABI versions (the C lib has its own ABI version too!). This way we could :just get started with the version numbers starting at 0.1.0 and start bumping them as needed for both libgpiod and libgpiod-sys independently. Also, this means that uploading to crates.io would not be strictly coupled to the release process of the C lib and other bindings. That may allow to spread the load a little.

This may be slightly confusing to the user, but I hope it is less confusing than the mess of what I listed above? Any opinions?

After agreeing on a versioning strategy, actually publishing to crates.io should only require to add version number restrictions to the libgpiod->libgpiod-sys dependency. It will then use that version for installs from crates.io and use the path when building locally.

Once that small change is also done, I think we are ready for publishing.

@Bart: How would you prefer to handle the upload of new versions? Or would you prefer to be the one doing it or prefer if someone from the community handles it? I can offer to help with documentation and setup if needed :).

[1] https://lore.kernel.org/r/[email protected]/
[2] https://doc.rust-lang.org/cargo/reference/semver.html

- Erik

Breaking changes are inevitable. The libc crate follows a nonsemver scheme (0.2.144 and bump the patch number by one for every release) which breaks stuff all the time, or at least it used to when it was at its early stages. There are ways to get around breakages in case of a crate lib being a transitive dependency but has different versions:

https://github.com/dtolnay/semver-trick

I believe following libgpiod's version scheme directly is what would be best and intuitive. -sys crates are not usual crates and users know this. It'd be cool to not have to bump the bindings crate version but I don't think it's a problem. This is how openssl{,-sys} works, if I am not mistaken.

All in all, in crates.io follow its conventions unless there's no way to do so.

Manos

How would you deal with the libgpiod (Rust) -> libgpiod (C) dependency here? Should we request an exact match via pkg-config (or at least a lower floor that would equal the version of the C lib?).

I think that there would be no good reason not to support older versions of the C lib (at least as long as sensible!). But it may be a bit weird if the Rust crate has a matching version scheme but then automatically disables features when building against an older system library... A separate version scheme might make that a little more explicit. But I got no particularly strong feelings about this.

openssl does not seem to follow this for neither -sys, nor the main package. It would also probably be a weird thing to do since it supports other backends like boringssl.

I think all of the options that I listed in my initial mail would follow the crates.io conventions and I strongly agree that we should follow the existing conventions. What to pick seems to mostly depend on how we want the release process to look like.

- Erik

For versioning: I'm all for decoupling libgpiod API version from rust bindings version. I did that for python bindings starting at 2.0 (since they've been published separately on pypi).

For uploading rust crates: I'd love if someone else could do this. I don't care enough for rust to do a good job at it. :)

Bart

Please go ahead :)

viresh