Why so many Weston APIs were moved to libweston-internal.h

[Pekka Paalanen]

On Mon, 19 Aug 2019 11:45:38 +0300
Marius Vlad <marius.vlad at collabora.com> wrote:

> Hi Xichen,
> 
> The main reason for doing this move/split is because, over the years, a
> lot of helper API has crawled into libweston, making it quite in large
> size and hard to reason about the symbols usefulness. That header was/is
> a catch-all for ``where do I put this symbol declaration?''.
> 
> The split is an attempt to re-organize a bit the front-facing API which
> users can directly use (Weston is a user of libweston -- but others
> might also be) and internal API (which is used only internally by
> libweston itself).
> 
> There's still a bit of work like trying to make some of the symbols
> opaque, or have some kind of categorization by class/functionality.
> There's also an orthogonal reason behind this as this split/movement of
> API is related to the documentation process of the library itself.
> 
> Please see the discussion/comments over
> https://gitlab.freedesktop.org/wayland/weston/merge_requests/227. It
> should provide some insight on matter as well.

Hi,

yes, the above is all true.

I'd also add that this movement has been pending ever since
libweston.so became a thing, but now people actually found some time to
work on it. Before, the split between public and private API was
basically non-existant. We need to make that split clear to have a hope
of stabilizing libweston for its intended external consumers.

For example, external backends and renderers have never been intended
to be supported. They might become some day in the future, but probably
not before the frontend ABI has been properly extracted and stabilized.

> On 8/16/19 8:15 PM, Sichem Zhou wrote:
> > Hi weston developers,
> > 
> > I noticed the new weston(since version 6.0.91), it introduced a new
> > internal header `libweston-internel.h`. Many useful APIs for compositor
> > writers were moved here.
> > 
> > For example, personally I heavily use temporary binding thus I use
> > `weston_binding_destroy` to remove those bindings once their jobs are done.  
> 
> I myself found that I've migrated a symbol which I needed exposed for
> Weston so I had to put back in to the public API.
> 
> > 
> > Right now I can still declare those functions but once those API are
> > internal, they are subjected to changes or removal thus breaks the linkage
> > for compositor writers. I am wondering Is it possible to move those
> > functions back to public?  
> 
> Yes, of course, if that's the case, please submit a MR for those symbols
> which you think are useful.

Indeed. We are making private all API that was not intended to be
public or was not designed to be public. In the process we very likely
hide or remove API that was actually useful for external consumers.
External projects should propose to re-publish the API they found
useful, but it might take a bit of re-design to expose an API we are
comfortable supporting going forward.

I expect there will be back and forth for a long time while the APIs
and ABIs are rehashed to become usable, documented, understandable, and
maintainable.


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20190830/966a7043/attachment.sig>