Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

general-concepts/slotting: New 'Considerations for slotting' section #363

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

general-concepts/slotting: New 'Considerations for slotting' section #363

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
483f359
general-concepts/slotting: New 'Considerations for slotting' section
thesamesam Dec 16, 2024
cfd6270
general-concepts/slotting: mention "fake slotting"
thesamesam Dec 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions general-concepts/slotting/text.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,13 @@ in the ebuilds. This is purely a convention; the package manager does not treat
<c>0</c> any different from other slot values.
</p>

<p>
"Fake slotting" where multiple SLOTs exist for the same package but they
are mutually exclusive (i.e. block each other) are strongly discouraged, given
that the existence of multiple SLOTs implies to users that parallel installation
is possible.
</p>

<note>
<c>SLOT</c> is a mandatory variable and must not be empty.
</note>
Expand Down Expand Up @@ -45,6 +52,102 @@ To <c>DEPEND</c> upon a package in a specific slot, refer to
</p>
</body>

<section>
<title>Considerations for slotting</title>
<body>

<p>
Slotting is a powerful tool and as such, is easily abused. It's critical
that when slotting, package maintainers carefully consider the impact
on <e>reverse dependencies</e>.
</p>

<p>
Do not be fooled by the ease in adapting the package itself to slotting:
slotting the package itself is always the easiest part.
Comment on lines +66 to +67
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "always" is too strong here. How about

Suggested change
Do not be fooled by the ease in adapting the package itself to slotting:
slotting the package itself is always the easiest part.
Do not be fooled by the ease in adapting the package itself to slotting:
slotting the package itself is often the easiest part.

or

Suggested change
Do not be fooled by the ease in adapting the package itself to slotting:
slotting the package itself is always the easiest part.
Do not be fooled by the ease in adapting the package itself to slotting:
slotting the package itself may well be the easiest part.

?

</p>

<p>
Before proceeding at all, consider the impact on the wider ecosystem
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: you're repeating "consider the impact".

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really dislike that "ecosystem" metaphor in computing (especially in free-software) context. It is a fuzzy and ambiguous term.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you suggest an alternative? In this case, I really want people to think "how is this going to affect other people", and "is there a thing this is going to break far beyond Gentoo"?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Before proceeding, consider the wider implications beyond Gentoo."

beyond Gentoo. Especially examine other distributions and their handling
of the problem in question. Gentoo cannot unilaterally move software to
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, technically speaking it can. I think the point's more like "it's not always a good idea".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Of course, that just rather weakens the rhetoric. Can you suggest some alternative phrasing that retains some punch?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Unilaterally moving software can have devastating consequences for …" (users? other developers?)

a non-standard location.
</p>

<p>
Even if every possible consumer of a slotted package has been adapted in
Gentoo, remember that people may develop or test software on Gentoo systems:
they both want to be able to build that software without having to adapt
to Gentooisms, and they also don't want to unintentionally write their
software such that it relies on Gentooisms.
</p>

<p>
Ecosystems that lend themselves to slotting, such as Guile or Lua, cannot
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Ecosystems that lend themselves to slotting, such as Guile or Lua, cannot
Systems that lend themselves to slotting, such as Guile or Lua, cannot

be naively slotted by just adapting the package itself. Other packages
must be primed to handle a slotted world: an eclass mechanism usually needs
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"World" has a specific meaning in Gentoo context, maybe better avoid?

to exist for packages to declare which versions they support, as well as
force building against the version currently depended on to avoid automaigc
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo:

Suggested change
force building against the version currently depended on to avoid automaigc
force building against the version currently depended on to avoid automagic

dependencies.
</p>

<p>
All reverse dependencies of a package should be tested and examined when
considering any slotting approach, in particular asking the following:
</p>

<ul>
<li>how does this software use this package;</li>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Software" and "package" here can be ambiguous.

<li>how the build system should locate the (right) version of this package;</li>
<li>how the package (and the right version of it) should be located at runtime,
if required.</li>
</ul>

</body>

<subsection>
<title>Libraries</title>
<body>

<p>
As a rule of thumb, libraries should not be slotted unless upstream
explicitly intend (major) versions to be installable in parallel. The
presumption should be that a library cannot be slotted until proven otherwise.
</p>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is dev-java/bcprov regarded a library? If so, what' should have been the alternative to slotting in commit 901da76177 followed-up by commit 154e9224cf, all was done according to this wiki article?

Copy link
Member

@Flowdalic Flowdalic Dec 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd say (pure) Java libraries are by construction intended to be installable in parallel (they are usually not meant to be consumed in parallel, but that is unrelated to slotting).

<p>
If a library is to be slotted, please consult with upstream wherever possible:
ask them to begin installing pkgconfig files to aid porting build systems
to detecting the library portably.
</p>

<p>
ABI should also be considered with slotted libraries: if a consumer of the
library (in)directly links against another version of the library, loading
two ABI-incompatible versions of the library in the same process, unpredictable
runtime behaviour may occur (including crashes, or worse).
</p>
</body>
</subsection>

<subsection>
<title>Executables</title>
<body>
<p>
Comment on lines +135 to +136
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blank line before <p> please.

For utilities / executables, slotting may be acceptable as long as an
unversioned, generic symlink or wrapper is made available for the benefit
of user scripts or tools, and build systems which expect the generic name
to be available.
</p>

<p>
An <c>eselect</c> module is often made available for these cases, though
ebuilds normally shouldn't depend its use.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the word "on" missing here?

</p>
</body>
</subsection>
</section>

<section>
<title>Sub-slots</title>

Expand Down
Loading