Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 629642 - Documenting all the eclasses and their respective inheritance
Summary: Documenting all the eclasses and their respective inheritance
Status: UNCONFIRMED
Alias: None
Product: Quality Assurance
Classification: Unclassified
Component: Disputes/raising issues (show other bugs)
Hardware: All Linux
: Normal normal
Assignee: Gentoo Quality Assurance Team
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2017-09-02 10:11 UTC by Petross404(Petros S)
Modified: 2021-07-21 01:11 UTC (History)
5 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Petross404(Petros S) 2017-09-02 10:11:30 UTC
For a newcomer developer to Gentoo, it is difficult to decide which eclass and functions will be used in an ebuild.

kde5.eclass let's say inherits cmake-utils.eclass and in kde releated packages cmake-utils isn't needed. But until I was told that at irc, I wrote the ebuilds in the wrong way.

It would be great if there was some kind of tree representation for the eclasses in a diagram or at least information that will make clear which eclass to use and when
Comment 1 Göktürk Yüksek archtester gentoo-dev 2017-09-08 20:05:26 UTC
(In reply to Petross404(Petros S) from comment #0)
> kde5.eclass let's say inherits cmake-utils.eclass and in kde releated
> packages cmake-utils isn't needed. But until I was told that at irc, I wrote
> the ebuilds in the wrong way.

I don't think explicitly inheriting the eclasses that you use in your ebuild is `the wrong way`. Eclasses have include guards anyway, so you don't lose much by stating them explicitly.

Adding QA to CC for their opinions on relying on implicit inherits in eclasses.
Comment 2 Michał Górny archtester Gentoo Infrastructure gentoo-dev Security 2017-09-08 20:19:15 UTC
Actually, I had eclassdoc patches to document which eclasses are included in the API of given eclass, i.e. which ones you shouldn't explicitly inherit. Except that I've lost interest in the topic as a result of the intensive 'I want you to rewrite everything because I like _ more than -' bikeshed.
Comment 3 Chris Reffett (RETIRED) gentoo-dev Security 2017-09-09 00:06:12 UTC
I think this has been discussed before, but implicit inherits are generally bad, if only for visibility reasons. Otherwise, changing eclass relationships can lead to ebuild breakage -- we saw this a lot, for example, when removing base.eclass, since a lot of ebuilds inherited eutils only through base.eclass and so they broke when we removed their base.eclass inherits.
Comment 4 Michael Palimaka (kensington) gentoo-dev 2017-09-09 02:05:49 UTC
In general of course one should inherit exactly what they use and not rely on transitive dependencies. There are some grey areas or exceptions of course.

Using the example of kde5.eclass from comment #0, cmake-utils is used so heavily that many of the functions it exports are essentially treated as part of kde5.eclass API too. I assume Petros was inherited cmake-utils as well as kde5 and was told not to bother (which is KDE team's preferred style), or didn't inherit it and was told it's necessary (which is often the case for other eclasses like versionator or multilib).

I think the solution is to clarify in the devmanual (if it's not already there) that implicit inherits are not to be relied upon unless explicitly documented in the eclass, then do that eclass documentation.
Comment 5 Petross404(Petros S) 2017-09-09 06:05:55 UTC
(In reply to Michael Palimaka (kensington) from comment #4)
> I assume Petros was inherited cmake-utils as
> well as kde5 and was told not to bother (which is KDE team's preferred
> style)

That is the case. My whole point is how to tell which eclass to use and where. 

How can we solve this in the documentation?
Comment 6 Michael Palimaka (kensington) gentoo-dev 2017-09-09 10:41:18 UTC
(In reply to Petross404(Petros S) from comment #5)
> How can we solve this in the documentation?

Each individual eclass doc would need to be updated. mgorny mentioned he has such patches but it's not clear if they will be shared or not.
Comment 7 Michał Górny archtester Gentoo Infrastructure gentoo-dev Security 2017-09-09 11:01:10 UTC
(In reply to Michael Palimaka (kensington) from comment #6)
> (In reply to Petross404(Petros S) from comment #5)
> > How can we solve this in the documentation?
> 
> Each individual eclass doc would need to be updated. mgorny mentioned he has
> such patches but it's not clear if they will be shared or not.

I meant only adding new @tag for it. And actually, I haven't actually gotten to implementing this one.
Comment 8 Larry the Git Cow gentoo-dev 2017-09-13 13:19:05 UTC
The bug has been referenced in the following commit(s):

https://gitweb.gentoo.org/proj/kde.git/commit/?id=3bcc9956ad8f2669d6e6b17f42c5ee541d6dfd34

commit 3bcc9956ad8f2669d6e6b17f42c5ee541d6dfd34
Author:     Michael Palimaka <kensington@gentoo.org>
AuthorDate: 2017-09-13 13:18:35 +0000
Commit:     Michael Palimaka <kensington@gentoo.org>
CommitDate: 2017-09-13 13:18:47 +0000

    kde5.eclass: improve documentation
    
    Bug: https://bugs.gentoo.org/629642

 eclass/kde5.eclass | 65 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 45 insertions(+), 20 deletions(-)}
Comment 9 Larry the Git Cow gentoo-dev 2017-10-26 08:24:16 UTC
The bug has been referenced in the following commit(s):

https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=c0a54c9fd461c839f2fe53dd8b5bbfe766e6b6d5

commit c0a54c9fd461c839f2fe53dd8b5bbfe766e6b6d5
Author:     Michael Palimaka <kensington@gentoo.org>
AuthorDate: 2017-09-13 13:18:35 +0000
Commit:     Andreas Sturmlechner <asturm@gentoo.org>
CommitDate: 2017-10-26 08:22:31 +0000

    kde5.eclass: improve documentation
    
    Bug: https://bugs.gentoo.org/629642

 eclass/kde5.eclass | 65 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 45 insertions(+), 20 deletions(-)}
Comment 10 Ulrich Müller gentoo-dev 2020-04-13 09:32:50 UTC
(In reply to Michael Palimaka (kensington) from comment #4)
> I think the solution is to clarify in the devmanual (if it's not already
> there) that implicit inherits are not to be relied upon unless explicitly
> documented in the eclass, then do that eclass documentation.

Could you provide a patch for the devmanual? The ebuild-writing/using-eclasses/ chapter might be a good place for it.