DevHeads.net

Naming scheme for Qt5/KF5-based libraries outside of KF5

Hi everyone,

We had a little discussion on how to name shared libraries in
kde-core-devel@ thread "Porting to frameworks 2: libkcompactdisc" [1],
but we did not come to consensus.

The question is, if you release a shared library with deps on Qt5
and/or KF5, but the lib is not part of KF5, how should the .so file be
named?

1. Many people prefer a "KF5" prefix, e.g. libKF5Screen.so).
2. Another way of naming is a -qt5 suffix, e.g. libmarblewidget-qt5.so.
3. (probably some others?)

Friedrikh said in [1] that using a KF5 prefix for all libraries will
"blur the hint by the name if something is part of KF5 or not".

Any thoughts? I believe we can have guidelines for library names.

And another question that developers might ask in the future: These
prefixes/suffixes are probably not necessary when the library is new,
i.e. did not have a Qt4 version under the same name (e.g. KDb) -
should such libraries still use a prefix/suffix?

[1] <a href="http://comments.gmane.org/gmane.comp.kde.devel.core/87533" title="http://comments.gmane.org/gmane.comp.kde.devel.core/87533">http://comments.gmane.org/gmane.comp.kde.devel.core/87533</a>

Comments

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Friedrich W. H.... at 09/27/2015 - 09:48

Hi Alexander & all,

thanks for pushing this further.

Am Samstag, 26. September 2015, 18:41:01 schrieb Alexander Potashev:
Yes, I still think so:
libQt* is left to Qt libs, and IMHO in the same way should libKF5* be only
used with real KF5 libs, if that prefix should have a consistent semantic,
i.e. should say they are part of the KDE Frameworks.

Another reason, though rather less likely:
Even more because someone might start a new lib KF5Foo which they think to be
become the killer lib for Foo purpose and one day to end up in the KDE
Frameworks, but then somebody else writes an even better one and that one than
becomes official KF5 lib for Foo. Would suck if someone occupied the name
KF5Foo already with an existing lib (as in: released and used by 1-2 apps
which are fine with the original lib and do not see a need to switch to the
KF5 one). Better safe than sorry.

WRT to your question on IRC, Alexander:
"
[Samstag, 26. September 2015] [17:32:04 CEST] <aspotashev_> frinring_: you are
saying "it will result in clashes", but that should not be a problem:
packagers can just forbid parallel installation of the standalone version and
the new version which is part of KF5
"
which refers to the thread "Porting to frameworks 2: libkcompactdisc" where I
wrote on 2015-09-04 11:59:57 GMT:
Forbidding parallel installation only works if the lib becomes a framework
without any changes.
Given the high standards and required ABI stability there is a good chance
that some API brush up (e.g. due to review feedback while proposed as KF5 lib)
is made before turning into a KF5 lib, as was already pointed out by Sune.
Having the same name would prevent that (for the usual problems with ABI
changes).

((I find the "-qt5" postfix sligthly ugly as well, and personally rather use
postfix integer counters to allow co-installability, but then my libs change
ABI more often, so just qt version does not work ;) Now, looking at "ls
/usr/lib64" things get relative, and with cmake config files the lib target
names used are usually more nice anyway, so "-qt5" should not be such a
bummer, and besides that this postfix seems to have become a pattern with some
libs already, so using them would add to consistency.))

My 2 cents.

Cheers
Friedrich

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Kevin Kofler at 09/27/2015 - 17:28

Friedrich W. H. Kossebau wrote:
Not if you ship your not-yet-in-KF5 library with a soversion (soname major
version) < 5. (I'd just pick 0.)

Kevin Kofler

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By =?utf-8?Q?Thoma... at 09/27/2015 - 09:56

+1

libKX5Foo - "kde eXperimental" or "kde eXtension" rather than "kde frameworks"?

Cheers,
Thomas

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Sune Vuorela at 09/26/2015 - 11:27

On 2015-09-26, Alexander Potashev < ... at gmail dot com> wrote:
I do think that having things named KF5 that aren't actual frameworks is
bad for several reasons.

1) It blurs what's a framework
2) We promise ABI and API compatibility for frameworks, but not for
other things
3) Moving something from "not a KDE Framework" to "KDE Framework" gives
a last chance for fixing up abi/api.

so. foo-qt5 is fine for a qt5 version of foo.

/Sune

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Albert Astals Cid at 09/26/2015 - 17:06

El Dissabte, 26 de setembre de 2015, a les 16:27:22, Sune Vuorela va escriure:
I agree, the problem is that there's few exceptions to copy from, so that's
the exact reason libkdegames has that KF5 thing in the name, the guy that did
the port just copied what the frmeworks do.

So anyone up for write what "a library that is not frameworks should do to be
nice in the KDE land"?

Cheers,
Albert

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Boudhayan Gupta at 09/26/2015 - 17:31

On 27 September 2015 at 03:36, Albert Astals Cid < ... at kde dot org> wrote:
We could kill two birds with one stone here, creating a new KDE module
just for libraries (say, KDE Companion Libraries or something) and put
everything in the KC5 (or whatever we decide) namespace.

I'm all for just putting everything in KDE Support, using the KS5
namespace and removing the tier0 restriction from Support.

-- Boudhayan

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Albert Astals Cid at 09/26/2015 - 17:39

El Diumenge, 27 de setembre de 2015, a les 04:01:26, Boudhayan Gupta va
escriure:
I don't see which birds it kills, as far as I see it it only gives you the
problem of having yet another product to release.

Cheers,
Albert

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Alexander Potashev at 09/26/2015 - 23:59

2015-09-27 1:39 GMT+03:00 Albert Astals Cid < ... at kde dot org>:
Sune, Boudhayan, Albert,

Thanks for your feedback! I think we already have consensus on the
"-qt5" suffix. I'll go rename the shared libraries in a few repos...
:)

Albert, do you mean you want a Techbase page with guidelines for libraries?

Regarding the library product, Boudhayan almost repeated my proposal
[1]. But using a namespace (e.g. KC5::) would not be a good idea
because this product may contain completely disconnected libraries.
"-qt5" suffixes should be enough. For KF5 the namespace makes sense
because the frameworks have numerous dependencies between one another,
thus KF5 feels and is promoted as an all-in-one product.

[1] <a href="https://mail.kde.org/pipermail/release-team/2015-June/008628.html" title="https://mail.kde.org/pipermail/release-team/2015-June/008628.html">https://mail.kde.org/pipermail/release-team/2015-June/008628.html</a>

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Boudhayan Gupta at 09/27/2015 - 04:42

On 27 September 2015 at 10:29, Alexander Potashev < ... at gmail dot com> wrote:
Putting hyphens in library names is just ugly, when the rest of the
product name is neat and tidy CamelCase with an initial uppercase
letter.

I'm still in favour of a new product, or reusing KDESupport, or even
Extragear libs. If you must use a suffix though, please consider using
Qt5, not -qt5, so that the lib becomes libSomeThingQt5, not
libSomeThing-qt5.

-- Boudhayan

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Alexander Potashev at 09/27/2015 - 05:00

2015-09-27 12:42 GMT+03:00 Boudhayan Gupta < ... at kde dot org>:
Boudhayan,

Camel case naming rule applies only to the frameworks already in KF5.
If your library is not part of KF5, then you can name it in lowercase:
libkcompactdisc-qt5, and the dash doesn't look ugly here IMO.

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Boudhayan Gupta at 09/26/2015 - 19:14

On 27 September 2015 at 04:09, Albert Astals Cid < ... at kde dot org> wrote:
Release it with the Applications release-unit, since the users of the
libraries are applications.

-- Boudhayan

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Friedrich W. H.... at 09/27/2015 - 10:25

Hi Boudhayan,

Am Sonntag, 27. September 2015, 04:01:26 schrieb Boudhayan Gupta:
Some bummer here:
a) not all libraries are in repositories of their own
b) not all libraries are released on the same cycle

E.g. a) happens because the libs could be shared libs for sharing between
multiple executables/plugins developed in a single repo. Or they are only
slowly established as shared code and still developed strongly coupled with
their main user executable/plugin and for that live in the same repo.
And b) is because there are a few libs in extragear or playground repos, so
not covered by the "KDE Applications" release cycle or forced to follow.

So while I agree that having all libs nicely separated would be good to have,
if only for discoverability, doing that with a single module at least
currently would not work.

((Long-term we should perhaps look into that, because right now the layout of
our repository structure does not make a difference between repos with
executables, plugins and libraries (and mixed ones).
And IMHO if we have libs, thus code intended to be shared between other
software, it would be great if it would be easy to developers to simply browse
all of the libs to find something perhaps matching. If that list would be a
virtual one, fine as well, but having the real repositories ordering also
follow that grouping helps shaping minds and reduces complexicity needed due
to the mapping.
(Would also make it simpler to know which libs there are that should be also
noted at inqlude.org)

But different topic, with quite some details and strings attached, worth at
least a different thread (and someone who can and would drive any planning for
that for some time, not me).))

Cheers
Friedrich

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Boudhayan Gupta at 09/27/2015 - 12:07

Hi Friedrich,

On 27 September 2015 at 20:55, Friedrich W. H. Kossebau
< ... at kde dot org> wrote:
So let's clean this mess up.

For applications, Extragear seems to be the place to live in if you
manage your own release cycles. I see no reason libraries should also
be treated the same way.

What I propose is that all libraries which want to manage their own
release cycles and their own namespaces, be moved to Extragear Libs
and release from there. All the libraries which can stick to the
Applications release-unit, move to Support or a new module and be
released with them.

This has the advantage of Application libs not having to maintain
API/ABI stability, since the Applications from one release will depend
on the libs from the same release. Extragear Libs devs, who want to
manage their own cycles etc, will however have to make API/ABI
guarantees.

Also, I get the feeling that Extragear is treated as a second-class
citizen. It doesn't have to be. Apps and libs in Extragear should be
held to the same standards as the rest of the KDE modules. The only
difference ever should be the release cycles.

Can you elaborate on why a single module would not work?

+1

Side note here - I'm very interested in getting Vlc-Qt under the KDE
umbrella, if the maintainers of Vlc-Qt and KDE are in support. A
dedicated library module would be a great place for it.

I'd love to help. I love organization ;-)

Cheers,
Boudhayan.

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Sune Vuorela at 09/27/2015 - 12:21

On 2015-09-27, Boudhayan Gupta < ... at kde dot org> wrote:
What happens if an Applications application uses an extragear lib? or an
extragear application uses an application lib?

Yes. this will happen.

And then you have a abi/api unstable library out of sync with the
application it uses. And that's highly annoying.

Seen before with e.g. Digikam/Gwenview/KPhotoAlbum and
libkipi/libkexiv2/...

I don't see why we need a extra organizational level to house something
we should try to avoid to have in the fist place.

Let's get all good libraries made frameworks.

/Sune

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Alexander Neundorf at 09/27/2015 - 15:35

On Sunday, September 27, 2015 17:21:04 Sune Vuorela wrote:

+1

Alex

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Boudhayan Gupta at 09/27/2015 - 12:57

On 27 September 2015 at 22:51, Sune Vuorela < ... at vuorela dot dk> wrote:
"Seen before" is no reason to not move forward if we can actually fix
this. As I said, Extragear library developers will *have* to provide
API/ABI guarantees.

That's the ideal scenario, but isn't becoming a framework... hard?

Cheers,
Boudhayan

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Sune Vuorela at 09/27/2015 - 13:05

On 2015-09-27, Boudhayan Gupta < ... at kde dot org> wrote:
Good luck with that.

No. Once you have something useful, reviewed and wants to commit to
abi/api stability it is just a bit of paperwork.

/Sune

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Alexander Potashev at 09/27/2015 - 17:43

2015-09-27 21:05 GMT+03:00 Sune Vuorela < ... at vuorela dot dk>:
Sune,

One does not simply commit to ABI/API stability. Look at kmime, kmbox,
etc: KDE PIM team was about to submit these libraries into KF5, but
now they have to bump SOVERSIONs [1] because of breaking ABI.

And you can also look at the numbers: KF5 grows at the rate of less
than one framework per month. We probably don't have enough manpower
to review dozens/hundreds of libraries in a short period of time.

[1] <a href="https://git.reviewboard.kde.org/r/125285/" title="https://git.reviewboard.kde.org/r/125285/">https://git.reviewboard.kde.org/r/125285/</a>

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By David Faure at 09/28/2015 - 15:21

On Monday 28 September 2015 01:43:59 Alexander Potashev wrote:
So you would rather aim for releasing crap ASAP than for quality? ;)

On Sunday 27 September 2015 04:01:26 Boudhayan Gupta wrote:
It seems to me that you're reinventing KF5.

Either a lib is meant to be used by both apps and workspace (and possibly
external apps) (see below for details),

Or a lib is only meant to share code between apps (e.g. libkdegames) and it
should be released as part of the apps. We can invent a new prefix or suffix for
these (K5A?) but the main thing is that there is no need for a new product,
for libs that are only used by the Applications product.

If a lib is to be used by both apps and workspace, then I see two cases
1) the lib has stable API/ABI, then it's easy (name it -qt5 if you release
it separately, like e.g. QCA, or make it a framework and it'll be released
automatically)

2) the lib cannot promise ABI stability yet. In that case we can introduce another
type of framework, let's say experimental to reuse an old kdelibs concept.
[I suggested something like that in the "Baloo Framework - License Exception"
thread 8 months ago, but that was not a solution back then (the license problem
was too big). It would be one here, though, IMHO.]

In practice my suggestion is:
* just like we have "portingAids: true" in framework YAML files, we can have
"experimental: true".
* the tarballs for experimental frameworks go into a separate subdir (just like portingAids)
* there would be no api docs on api.kde.org for these frameworks (otherwise
external application developers would think they promise BIC just like proper KF5 does)
* the .so number still has to go up every month where a BIC happens (that's the rule)
* SIC should not happen. Since KF5, apps and workspace are not released together,
a SIC would mean that upgrading one would break the other. One would have
to make sure to keep deprecated stuff around, and to preserve behaviour.
This is the price to pay for sharing between apps and workspace.

Naming: "experimental" sounds like "it will be a framework at some point, when it
stabilizes". Maybe we should say "internal" either, i.e. used internally by apps
and workspace, don't use outside of that. Which still doesn't prevent a framework
tagged "internal" from turning a proper public framework later.

Maybe the "experimental" or "internal" should even be part of the tarball name
and distro package names, to make really sure app developers see that.

Again, none of this is needed for libs that are only for apps, or only for workspace.

In summary, I see 6 types of libs:
* public, separate (qca, poppler, libkolab, etc.) (external, or at least separately released)
* public, part of KF5 (that's KF5 as you know it)
* internal, part of KF5 (doesn't exist yet, but I'm open to the idea, see above)
* internal, part of apps (e.g. libkdegames)
* internal, part of workspace (e.g. libksysguard)
* private to one app (e.g. libkonqueror_private, that's just for unittests)

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Alexander Potashev at 10/17/2015 - 09:53

Hi David,

2015-09-28 23:21 GMT+03:00 David Faure < ... at kde dot org>:
Sounds good, I'm only worried about users/developers disregarding
these libraries because they have "experimental" in their names, even
though they may have been around and work OK for 5+ years already.

We still need some distinct naming scheme/namespace for kf5-experimental, right?

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By David Faure at 10/19/2015 - 01:56

On Saturday 17 October 2015 17:53:25 Alexander Potashev wrote:
Wait, if they have been around and work OK for 5+ years, isn't it time to stabilize
and guarantee API and ABI?

The whole point of "experimental" is to convey the message that the API isn't stable
yet, so yes, the point *is* that developers should disregard such libraries if they
need a stable API and ABI.

If the point isn't that it will stabilize at some point (and become a real framework)
then you want "internal" instead, as I said in the quoted text above.

Actually I don't think so. "experimental" becomes stable at some point, and at that
point we don't want to have to port all users of the code.

On the other hand, "internal" probably stays "internal" for ever, so for these it would
make sense to have that in the library name maybe? Or just no KF5 in the name.

Let me expand my summary a little bit, because I'm not sure which type of lib you're
asking about exactly.

I see 7 types of libs:
* public, separate (qca, poppler, libkolab, etc.) (external, or at least separately released; no KF5 in the name)
* public, part of KF5 (that's KF5 as you know it; API/ABI is guaranteed)
* public but "experimental", released with KF5 (i.e. a framework that will stabilize and become part of the above)
These mean "you can start using them now but ABI will break, or you can wait and you'll get stable ABI".
kdelibs/kactivities was experimental like that AFAIK.
* internal, part of KF5 (i.e. a lib meant to be used by apps and workspace, but not outside of that)
To the outside world this says "do not use, ever" (or convince us to make it KF5 proper).
* apps-internal (e.g. libkdegames; no KF5 in the name; cannot use in worskpace)
* workspace-internal (e.g. libksysguard; no KF5 in the name; cannot use in apps)
* private to one app (e.g. libkonqueror_private, that's just for unittests)

Again, note that SIC are not possible anyway, for experimental or internal-in-KF5 libraries.
So e.g. one can add virtual methods (and bump the so version), but not remove/rename anything,
because of the separate release schedule for frameworks, apps and workspace. So is this
really worth the separate categorization? If libs that are meant to be shared between
apps and workspace need stable API anyway then they might as well become proper
KF5 libs, being able to make BICs but not SICs is only a tiny gain IMHO.
I suppose version-number-ifdefs in apps allow to make a few SICs too, but this is
not trivial to do right (when apps code is already released and must keep compiling).

Before going further about naming, please tell me which type of lib you're thinking about,
and consider whether there is that much to be gained by using the "experimental" or "internal"
concept for it.

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Sune Vuorela at 09/27/2015 - 04:59

On 2015-09-26, Boudhayan Gupta < ... at kde dot org> wrote:
By doing this, we kind of make it a thing to .. become. I do think that
shared cross-repository libraries that aren't frameworks should be
avoided as much as possible, and for the few ones where it isn't
possible for specific functionality we should still try to limit it.

It is libraries that might change abi and api, and that's generally a
mess, especially if the users have different release schedules. And
people will use an available shared library.

KDE Support is our 'low level' libraries, but many of them has become
frameworks, which I think should also be the road ahead.

/Sune

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Boudhayan Gupta at 09/27/2015 - 05:46

On 27 September 2015 at 15:29, Sune Vuorela < ... at vuorela dot dk> wrote:
What exactly is wrong with shared cross-repo libraries? Take
libPurpose for example. It's a great little utility that many apps can
use, but it's certainly not mature enough to be a framework. I'd want
it in a place where many people can use it.

What's wrong with people using a shared library? That's what they're for.

A new component must be aligned with the Applications release-unit,
and since Applications are primary (only?) users of the libraries, and
API/ABI break shouldn't cause any problems at all, given that apps in
the (eg) 15.12 release will only depend on the 15.12 version of the
library.

Also, why are we assuming API/ABI will be broken? Can't developers be
trusted to be strict with their APIs?

Again, if it can become a framework, make it a framework. If it can't,
put it in Support and release it with Applications.

Cheers,
Boudhayan

Re: Naming scheme for Qt5/KF5-based libraries outside of KF5

By Kevin Kofler at 09/27/2015 - 04:30

Sune Vuorela wrote:
That's more a political distinction than a technical one. For all practical
purposes, the application using the library doesn't care whether it is a
"Framework" or not.

But it means you will gratuitously break both source (!) and binary
compatibility for all users of the library when the library actually becomes
a Framework.

If you need to fix the ABI, you should just bump the soname major version.

I'd just use libKF5*.so.0 (instead of the normal .5) for libraries that are
not yet Frameworks.

Kevin Kofler