[gentoo-dev] Guidelines for using slot and sub-slot dependencies

[Michał Górny]

Hello, all.

Considering the past experiences wrt slot, sub-slot and slot operator
dependencies, I'd like to write some kind of guidelines for using them.
I'd like to know your opinion on my 'draft' and possibly someone more
fluent in English to put them somewhere on the Wiki.


First of all, please remember that slots and sub-slots are just generic
tools. How they end up being used is up to the maintainer's discretion.
Therefore, always check how the package is slotted and sub-slotted
before depending on it. If it doesn't use sub-slots yet, use your
common sense or -- when in doubt -- ask the maintainer.

The goal of slot (and rarely sub-slot) dependencies is to limit
the number of package versions that can satisfy a dependency. The goal
of slot operator is to bind the package to the currently installed
version of a dependency and rebuild it when uninstalling that version.

So, the following questions need to be answered:

1. can any (current or possibly future) version of the package satisfy
your dependency?

2. does your package need to rebuilt when slot/sub-slot changes?

Of course, the answers depend on what exact purpose slots
and sub-slots serve on a package.


1. You almost always want to depend on a specific slot of a library.

This came up during the multilib work. If we are to support prebuilt
binary software, we need to be able to install the specific versions of
dependent libraries. As a result, so-called binary-only (runtime,
compat) slots are introduced.

An example of this is media-video/ffmpeg. It has a :0 slot that
corresponds to a complete ffmpeg install, and a :0.10 slot that
installs the libraries only. So every package that is being built
against ffmpeg, need to depend on slot :0.

It is likely that many more packages will grow binary-only slots
in the future. Therefore, it seems reasonable to depend on slot :0
(or a similar single slot) already.

Please specifically note that this not only applies to linking to
a library but also to using the tools provided by it during run-time.
So if your package uses 'ffmpeg' command-line tool, and depends on
'media-video/ffmpeg', portage will be able to uninstall the 'ffmpeg'
executable and leave your package silently broken.


2. You most often want := deps when linking to libraries.

Just check first how the library is sub-slotted. The commonly repeated
example, app-text/poppler, uses sub-slot for its low-level library
only. The high-level libraries that most programs use have stable APIs
and aren't supposed to have := deps.

If a particular package does not use sub-slots yet, use your common
sense. If it installs a single library only, you can use := dep. If it
installs libraries that changes their ABIs in approximately same
intervals, you can use the := dep.

Please remember to combine this with (1), so you'll often have :0=
as the actual dep.


3. You *can* depend on a specific sub-slot.

Most people seem not to know that but you can depend on sub-slots
the same way you depend on slots. This makes it possible to have
sub-slot versioned virtuals.

For example, virtual/udev-206-r3 (sub-slot 0) depends on:

  || ( ...
    >=sys-apps/systemd-206:0/1[...]
    >=sys-apps/systemd-206:0/0[...]
  )

which means that systemd sub-slots 1 & 0 have the same ABI of libudev.
Packages can depend on virtual/udev:= and expect the rebuild to be
propagated.


4. You *can not* trust portage's --dynamic-deps anymore.

This one is fairly important. In the past, we often assumed that
portage will 'update' deps from ebuilds automatically. This is no
longer correct if sub-slots are used -- since portage simply can't know
which sub-slot of the dependency was used to build the package.

This makes the point (1) above pretty important (see: the python-exec:2
issues). Since we don't have any proper tools to update dependencies of
installed packages (there's a future-eapi bug for that [1]), we need to
try harder to get them right.

[1]:https://bugs.gentoo.org/show_bug.cgi?id=486778

-- 
Best regards,
Michał Górny