Added compatibility with multiple libcamera versions

dbartussek commented 2 weeks ago

This is now the result of the discussion on issue https://github.com/lit-robotics/libcamera-rs/issues/31 in two clean commits:

The first (https://github.com/lit-robotics/libcamera-rs/commit/62ad9bdc20a397bd6301d9fcf45ad064e50f8e4f) is the rework of the binding generation code.

generate_rust.rs has been changed to generate_from_git.rs and no longer generates a single binding from included yaml files. It now instead clones/fetches the libcamera repo from https://git.libcamera.org/libcamera/libcamera.git/, iterates over the version tags and generates a binding from each versions control_id and property_id yamls. Additionally, it parses the vendor of each control/property (currently "draft" or "rpi") and feature gates them with "vendor_draft" as a default feature for convenience and backward compatibility.

The generate_c.rs file has been completely removed and instead replaced with a second bindgen invocation in libcamera-sys/build.rs to generate bindings for control/property id enums directly from the system C++ library.

The system libcamera version is now also part of the generated bindings and is used by libcamera/build.rs to include the correct bindings version by linking libcamera-sys as both a normal and a build dependency. A side effect of this version selection is that this is a breaking change, though only if one cross compiles from a platform without/with a different version of libcamera. In all other cases this PR is completely source compatible.

The second (https://github.com/lit-robotics/libcamera-rs/commit/2fb8283bd1011657ff6c1b296b77387b2e3e366d) adds some flexibility to which binding version is chosen through semver.

Before this, any update to the system libcamera would result in the build failing because bindings for eg v0.3.3 are not yet available. With this commit and the libcamera_semver_versioning default feature enabled libcamera-rs will fall back on the v0.3.2 bindings as the most recent compatible ones. libcamera itself has expressed commitment to semver compatibility (https://github.com/libcamera-org/libcamera/issues/1#issuecomment-992620449), so this should be a safe assumption.

For the future

The main issue with this current implementation is that the bindings have to be manually generated and a new version uploaded to crates.io at least whenever libcamera releases a new semver breaking version, and preferably every time any new version is released. I see two possible solutions to bridge this problem:

Automatically watching the libcamera git repo by eg running a cron task every day (maybe every hour) that rebuilds the bindings if a new version is found, creates a commit and potentially publishes a new version to crates.io
Adding a "build from upstream" feature to libcamera-rs that essentially runs generate_from_git during the build.

dbartussek commented 2 weeks ago

And a third commit now to fix the clippy lints. I really love those checks, I forget clippy too often otherwise!

chemicstry commented 1 week ago

Looks good! Thank you very much for the PR and in depth writeup!

lit-robotics / libcamera-rs