[libcamera-devel] Rustlang bindings

[Kieran Bingham]

Quoting Jurgis Balciunas (2022-11-21 17:05:06)
> Hi Kieran,
> 
> On Mon, 21 Nov 2022 at 17:58, Kieran Bingham <
> kieran.bingham at ideasonboard.com> wrote:
> >
> > Hi Jurgis,
> >
> > Quoting Jurgis Balciunas via libcamera-devel (2022-11-21 15:27:14)
> > > Hello everyone,
> >
> > Welcome to libcamera. And thanks for diving in!
> 
> Thanks!
> 
> > > I'm not used to mailing lists and patchwork process so pardon me if I'm
> > > writing this at the wrong place.
> >
> > Entirely correct, don't worry.
> >
> > > I've been working on Rust bindings for the libcamera and wanted to let
> > > everyone know in case someone would be interested. So far I've gotten as
> > > far as capturing JPEG image from webcam entirely in safe Rust and I
> think
> > > this already covers ~70% of libcamera API. The wrapper library is
> currently
> >
> >  \o/
> >
> > > published at https://github.com/lit-robotics/libcamera-rs. It consists
> of 2
> > > main parts: libcamera-sys, which contains raw unsafe bindings to
> libcamera
> > > and libcamera-rs, which implements a higher-level memory-safe API on
> top of
> > > libcamera-sys.
> > >
> > > The most difficult part was C++ not being FFI friendly and most of the
> > > automatic binding generation tools break with complex C++ codebases,
> > > especially when templates are used. So instead I've written a thin C
> > > wrapper around libcamera (under libcamera-sys/c_api
> > > <
> https://github.com/lit-robotics/libcamera-rs/tree/main/libcamera-sys/c_api
> >),
> > > which was used to autogenerate libcamera-sys. We had a discussion in
> > > https://github.com/kbingham/libcamera/issues/58 that this C wrapper
> could
> > > be useful not only for Rust bindings, but I'm personally not sure about
> any
> > > uses outside FFI? If it were a part of libcamera, the difficult part
> would
> >
> > C-bindings will be useful else where indeed. Either for other language
> > bindings, (Anyone going to work on Go next ?) or just to expose a direct
> > C api.
> >
> > > be maintaining documentation as the C API does not map 1:1 with C++,
> > > especially anything related to STL containers.
> >
> > Yes, we'll have to figure out how to document the C API potentially
> > alongside the C++ API.
> >
> > Ideally, we'd continue our doxygen integration there.
> >
> >
> > > Anyway, there is quite a lot to these bindings (~5k LoC excluding the
> > > auto-generated stuff) and too many design decisions to explain in this
> > > introductory email. I'm happy to answer any questions instead.
> >
> > Well the next questions will be - what should our next steps be to
> > getting your work integrated.
> >
> > Ideally, we would like contributors to have read:
> >  - https://libcamera.org/contributing.html
> >  - https://libcamera.org/coding-style.html#coding-style-guidelines
> >
> > and have the checkstyle hooks added to their repository:
> >  cp utils/hooks/post-commit .git/hooks/post-commit
> >
> > And have clean commits that we can review on list. I anticipate getting
> > the full c-bindings merged may be a fair bit of work - so do let us know
> > if there's anything that we can do to help or support you.
> 
> I'm not sure what the best way to move c-bindings forward would be. I don't
> have much experience with either Go or "idiomatic" C to judge if an API is

No 'Go' required here ;-) That was just speculation on another language
binding that could potentially use a c-binding.

> well-written. Ideally, I would have someone else interested in this matter
> to take on the C bindings, while I would mostly focus on Rust.

I would say it's important to develop them both together as updates and
changes to the c-bindings will directly impact the rust bindings.
 
> Since it's still very early in the inception and there is a lot of trial
> and error involved, I don't think that patch process would work now. It
> needs to reach an MVP stage first. Maybe a separate repository or a branch
> would be appropriate for this?

Separate repository to start is ok. Patches can be squashed down for
submission later.

But I think it sounds like you've already hit MVP. You can successfully
capture an image through those bindings!

How we package and build the c-bindings, and where the headers live, and
how they are referenced will be the interesting discussions.

If we were building libcamera C++ bindings we'd have libcamera++ but
does adding C bindings to a C++ library mean we need libcamera-- ? :-)

> > I would anticpate that the rust bindings would live in the libcamera
> > repostiory as well as the c-bindings. Is that how other rust projects
> > work?
> >
> > Are you happy for this work to live in the libcamera upstream
> > repositories? If it's upstream we can expect to maintain it and validate
> > it against any ABI/API changes. I might need some help setting up extra
> > automation and testing to make sure the rust bindings are functional...
> > (I've got extremely little rust experience).
> 
> I think this might be a problem, because rust has no mechanism to discover
> locally available packages. The official way is to publish on crates.io
> package repository and match the bindings semver to the target library
> semver. This is unfortunate for libraries that don't have a stable semver
> yet, like libcamera. Since rust is mostly statically linked, a lot of

We now have incrementing semver tags, and I'm tracking against ABI
compatibility so I don't see this as an issue.


> projects have a build script which pulls in the library source and builds
> it. This works for simple libraries with few dependencies, but I don't
> think it would work with libcamera, which requires multiple libraries and
> build tools. Until libcamera has a stable semver release, I think the only
> way is to use git dependencies with the matching libcamera revision hash.

Do you mean building the rust bindings has to also build a full
libcamera installation? or that it links against an existing one?

> I have no issue with moving this to the upstream repositories. Although I'm
> not sure if it should be included in the main repository, since it can't be
> distributed together with libcamera. From what I observed, most of the Rust
> bindings usually live in a separate official repository (i.e.
> https://gitlab.freedesktop.org/gstreamer/gstreamer-rs)

I would be interested to hear 'why' these need to be separate. But
separate shouldn't be a problem.

--
Kieran


> 
> >
> > --
> > Kieran
> >
> >
> > >
> > > Regards,
> > > Jurgis