Skip to content

rust: implement vlcrs-plugin and vlcrs-macros to define module manifests

This MR reuses the work done from @loic in !2738 to expose the module!{} macro as a way to define the module manifest in rust plugins. There's still no buildsystem integration for creating modules though, and it will be merged in a follow-up MR.

Bindgen is not used for the vlcrs-plugin crate, which exposes the minimal interface for the module!{} macro to start becoming useful and testable. In particular, the parameter handling has been removed after @loic's patches since vlcrs-variables is not merged yet.

vlcrs-macros exists as a proc-macro crate to define module!{}, while using vlcrs-plugin to generate the correct opcodes for the vlc_entry generated symbols. It is exposed with multiple tests executable. Indeed, even though it's possible to move the vlc_entry symbol exposure into a Rust module, it's not possible to declare the symbol multiple times since there's no symbol name mangling for it, so the different test cases for the macro needs to be written in different linker units.

Some changes have been made compared to the original implementation. The previous implementation from Loïc Branstett was using public activation and deactivation functions that would be fetched from the capability name. But it meant that capabilities could not have spaces in them, removing the possibility to use "video filter" or requiring to patch the name beforehand, and it was fit to a model with a single crate so as to know where to find the activation functions.

Since the introduction of the binding generator in commit bd1aaaf4, our crates are separated and sorted to match each include file from vlccore.

In addition, it meant that it would not have been possible to write out-of-tree capabilities while enjoying the type-safe features brought by the bindings, as opposed to the current C API, for the same reasons the multiple crates are not compatible with the previous model.

Finally, it was also not compatible with custom loading function type even though it is being generalized through the codebase, which would trigger issues for porting more module capabilities in the future.

This MR brings a new indirection by allowing capability traits to define Loader, Activate and Deactivate types in their definitions, in an effort to keep a type-safe interface when writing modules, as well as being able to easily describe new module interfaces without compromising on the current features of the module infrastructure.

   Module Implementor                      Core support

- Implement capability              - Provides capability traits
  traits                            - Provides module loader
                                      functions

The types Activate and Deactivate would allow to define custom activation function type, such as those we find when using vlc_module_load or manually probing using vlc_module_match, as opposed to the common vlc_object_t-based module_need() activation function.

The type Loader allows to define a default associated type that would provide the activation functions to the module manifest writer, so that the correct interface is used. It effectively allows capability traits to define custom activation function types, without having the module implementor explicitely provide those functions. The module implementor is still able to provide their own activation functions by providing their own loader.

Commits have been heavily described and documentation updated to integrate this new feature.

Merge request reports