Ticket #155 (new enhancement)

Opened 3 years ago

Last modified 2 years ago

Version independant plugins

Reported by: dionoea Assigned to:
Priority: normal Milestone: Features paradize
Component: LibVLC Version: master
Severity: normal Keywords:
Cc: vlc-devel@videolan.org Platform(s): all
Difficulty: hard Work status: Not started

Description (Last modified by courmisch)

Make the vlc API more stable so binary modules can be distributed separately. We need to have an API version tracking system with :

  • an API version number
  • a API version backwards compatibility number

That mainly concerns the module header (all these macros that generate the vlc_entry* function and its code).

We should also :

  • refrain from modifying existing API in a non-backward compatible way (adding const or changing signedness is OK),
  • clean up headers file so they don't provide definition for structures that should not be used by plugins directly,
  • don't modify public structure declaration (it's VERY tricky to avoid breaking binary compatibility with these),

That way we could distribute plugins for ffmpeg that people using some distros might want to download ...

OPEN ISSUE : how do we determine the minimum version number a plugin needs ? scan API used (very complex, and not sufficient because of the possible structure layout change) ?

See also #171.

Change History

31/05/05 13:15:58 changed by courmisch

  • owner set to courmisch.
  • difficulty changed from unknown to hard.

Two files are involved in the API : * include/vlc_symbols.h defines a big structure with function pointers to every VLC API. * src/misc/modules_plugin.h defines a big macro to initialize said structure automatically.

Both files are auto-generated by vlc-config which greps for VLC_EXPORT in include/*. To make the API backward compatible, we musth either : * add new APIs manually, * or make sure new APIs are added at the end of the structure.

The case for obsololete/removed APIs is more tricky.

02/06/05 11:14:18 changed by courmisch

  • status changed from new to assigned.
  • summary changed from making independent plugin distribution easier to Version independant plugins.
  • description changed.
  • severity changed from normal to enhancement.

Split ticket.

02/06/05 11:20:18 changed by courmisch

  • cc set to vlc-devel@videolan.org.

I have a Perl script that can update the API properly, that is to say keep functions pointers at the same offset in the big API structure module_symbols_t. New APIs are added at the end of the structure. Removed APIs are replaced with dummy pointers for to preserve padding/offsets.

Of course, it won't solve the issue with modified API. Version detection is not implemented (there is no perfect solution to this).

Besides, there's big chance that SVN will often conflict when one has uncommited API changes in its development trunk working copy.

The dependency on Perl for the build should be ok since Automake depends on Perl already. It means developers have Perl already. I'll try to not mandate Perl for package maintainers that don't run Automake and don't modify the API.

02/06/05 14:47:31 changed by courmisch

  • status changed from assigned to closed.
  • resolution set to fixed.

(In [11250]) Complete rewrite of vlc_symbols.h generation (closes #155)

New VLC_EXPORTs are now added at the end of module_symbols_t so that offsets of other function pointers are preserved.

Deleted VLC_EXPORTs are replaced with dummy pointers for padding.

Of course, it doesn't solve the problem with changing shared structures format :/ and it may cause SVN conflicts when multiple people changes VLC_EXPORT. I doubt it can be avoided though.

02/06/05 15:34:28 changed by zorglub

  • status changed from closed to reopened.
  • resolution deleted.

I wouldn't consider this bug as FIXED.

Even if [11250] is a step forward to its resolution by allowing to change the API without breaking binary compatibility with older plugins, we still need API versioning to prevent modules that use newer API to try running on an older VLC.

Besides, this only fixes function calls, not structures handling.

02/06/05 15:39:26 changed by zorglub

Obviously, this can't be fully automated. The only difference is that we don't bind the API version number to VLC version number but only bump

  • API "forward" version number when non-forward-compatible-changes are made:
    • Modification of structures (changes memory layout)
    • Furthermore, we might want from time to time to clean up the module_symbols mess (manually remove all _deprecated symbols). This obviously breaks binary compatibility (in both cases, a simple recompilation should be enough to fix the problem)
  • API "backward" version when new structures or function calls are created, so that newer modules don't try to run on older VLC

03/06/05 10:05:47 changed by courmisch

Bumping API forward will break compatiblity at every release. We can't do that. There'll always be a change in one of access/demux/codec/etc that breaks binary compatibility with a specific class of modules.

The only way around that would be to version known VLC object types' interfaces - if that is possible at all.

03/06/05 13:37:29 changed by zorglub

API forward is not bumped up at each release. Only in two cases:

  • Layout or size changes of existing structures. This _should_ not happen often after 1.0.0 (all this stuff is definitely not for pre-1.0 versions anyway, imo)
  • Ocasionnal clean up of the API (major version changes)

What will be bumped up more often is the API backward version.

If we can't keep the API forward stable enough, then we need to provide versioning per module type. But this is quite complex: the dependencies between structures are quite numerous and complex.

Anyway, all this stuff really can't be done with quite stable APIs, so not with what is happening now.

25/06/05 18:17:52 changed by zorglub

  • wip set to Not started.
  • milestone changed from 0.8.3 feature freeze to 0.8.4 (provisional).

01/07/05 17:27:40 changed by courmisch

(In [11625]) Freeze module entry name (refs #155)

04/07/05 00:00:42 changed by zorglub

A good reference to follow might be libtool's versioning system

05/08/05 21:13:18 changed by courmisch

  • description changed.
  • milestone deleted.

28/10/05 15:23:58 changed by zorglub

  • milestone set to 0.8.5.

28/11/05 21:43:13 changed by courmisch

  • milestone changed from 0.8.5 feature freeze to Features paradize.

12/12/05 18:40:38 changed by courmisch

  • component set to Build system.

12/12/05 18:40:54 changed by courmisch

  • status changed from reopened to new.

12/12/05 18:41:03 changed by courmisch

  • status changed from new to assigned.

25/04/06 12:31:57 changed by courmisch

  • due_assign changed.
  • include_gantt changed.
  • dependencies changed.
  • component changed from Build system to LibVLC.
  • due_close changed.

Even if we ever reached 1.0.0, it is foolish to believe we wouldn't want to change the API at every release. The only proper way to obtain version independance would be to only use API, and to not have any kind of public structs, so that we are sure that they can be changed transparently (as most other libraries do).

But I can hardly imagine people willing to do that. Every plugin would have to register its callbacks through a dedicated plugin-type-specific API, so that only the core would have to know about the structs internal.

12/09/06 16:18:31 changed by courmisch

  • status changed from assigned to new.
  • owner deleted.