In order to stabilize qt-4.4.x split ebuilds, we need a migration guide, because the upgrade is non-trivial, and has a few pitfalls.
Created attachment 172800 [details]
Here's a rough draft which outlines the issues. I could use some help with fleshing it out and XMLifying it. ;-)
Okay, draft is now available:
Be sure to examine the source; it contains a TODO chunk that I'd like you to review:
AFAIK the blocker is here only because of file collision handling. Could we instead wait for Portage that resolves this kind of collisions instead of offloading useless, tedious and dangerous  work to users?
 When one removes the old Qt, all Qt pacakges become, of course, useless.
Please s/qt-core/qt-gui/ in migration guide.
(In reply to comment #4)
> Please s/qt-core/qt-gui/ in migration guide.
Done. Does the user really need to worry about merging qt-gui:4? There's only one package, so does merging by SLOT really matter?
In typical scenario (without dependency issues) user don't need to worry about anything as proper packages are pulled by dependencies.
In fact qt-gui pulls - depending on USE flags - qt-core, qt-script, qt-qt3support, qt-dbus, qt-sql - that's nearly everything that typical Qt user wants (there are qt-opengl and qt-svg that are pulled by KDE4).
The politics to rely on split Qt components (like qt-core, qt-gui, qt-opengl) is already applied AFAIK in packages or is being applied (see bug #217161), so user shouldn't need to emerge anything explicitely to make things work. I guess giving x11-libs/qt-gui as a 'replacement' for x11-libs/qt (meta/mono) is just a precaution (like for the one who use some 3rd party overlays or just non-portage stuff) - it may not be necessary - you're right - maybe the solution is just to drop x11-libs/qt.
The problem is only with packages that explicitely rely on old monolithic Qt versions (like PyQt4, in fact it may be the only blocker - resolved by removing with old Qt and revdumping new PyQt4 as stable). It's not surprise that many Qt4 bugzilla bugs are PyQt4 related.
(In reply to comment #6)
Actually, my question was more about "Is the :4 on the end strictly necessary, given that there's only one SLOT."
But your reply does illuminate a few more things. :)
> In typical scenario (without dependency issues) user don't need to worry about
> anything as proper packages are pulled by dependencies.
And this is definitely the better way to go. Users don't have to clutter up their world file with support packages -- normally you shouldn't need to add GUI toolkit components to world. I wonder if --oneshot would be a good option for the merge instructions?
(In reply to comment #5)
> (In reply to comment #4)
> > Please s/qt-core/qt-gui/ in migration guide.
Please undo. I specified qt-core because it is the bare minimum that will be needed. Other split Qt packages will be pulled in by ebuilds as deps. (Not that this is a major issue, as most people will want/need qt-gui, but it is possible to use Qt without gui.)
> Does the user really need to worry about merging qt-gui:4? There's only
> one package, so does merging by SLOT really matter?
Seeing as having x11-libs/qt in world file with unspecified slot is part of the problem, I thought it would be wise to specify the slot here. (Yes, I know qt:5 is far away, but still, it doesn't hurt to be prepared.)
(In reply to comment #7)
> I wonder if --oneshot would be a good option for the merge instructions?
Yes, I think so. Using oneshot also means we don't need to specify the slot here. So let the code listing say instead:
# emerge -av1 qt-core
Maybe we should also add a warning that people should review the USE flags for the split qt packages. And also that qt-qt3support does not replace the need for qt:3 (it only makes porting an application for qt3 to qt4 easier for the developer).
(In reply to comment #2)
> Be sure to examine the source; it contains a TODO chunk that I'd like you to
I'm not sure this is needed for all packages. That's why I would like to see some testing for this procedure.
Revdep-rebuilds might help, but it might also just try to pull qt-4.3* back in. To get a list of packages depending on qt-4, I would suggest:
# equery d qt:4
equery is part of app-portage/gentoolkit
yngwin, you haven't adressed comment #3 yet.
(In reply to comment #3)
> AFAIK the blocker is here only because of file collision handling. Could we
> instead wait for Portage that resolves this kind of collisions instead of
> offloading useless, tedious and dangerous  work to users?
Does portage-2.1.6 make this upgrade painless and easy? I don't think so, and in that case my answer would be no. But if it is the case then it might be worth waiting a bit. Can anyone test?
Most things should solve automatically with portage-2.1.6. The things that might cause problems are || deps, which case currently installed packages to be preferred and might lead to wrong choices in building the dependency graph (variant of bug 1343). If a problem like that occurs, it's still possible for emerge to perform the upgrade "automatically", but only if you mask the older versions that are unwanted, in order to eliminate them from the choices when building the dependency graph.
The upgrade should be smooth as long as you mask qt-4.3* at the same time as you stable the qt-4.4 split ebuilds. Here's some sample output of emerge solving the blocker automatically:
[ebuild N ] x11-libs/qt-core-4.4.2
[ebuild N ] x11-libs/qt-sql-4.4.2
[ebuild N ] x11-libs/qt-dbus-4.4.2
[ebuild N ] x11-libs/qt-script-4.4.2
[ebuild N ] x11-libs/qt-xmlpatterns-4.4.2
[ebuild N ] x11-libs/qt-test-4.4.2
[ebuild N ] x11-libs/qt-gui-4.4.2
[ebuild N ] x11-libs/qt-qt3support-4.4.2
[ebuild N ] x11-libs/qt-webkit-4.4.2
[ebuild N ] x11-libs/qt-opengl-4.4.2
[ebuild N ] x11-libs/qt-svg-4.4.2
[ebuild N ] x11-libs/qt-assistant-4.4.2
[ebuild U ] x11-libs/qt-4.4.2 [4.3.3]
[blocks b ] x11-libs/qt-core ("x11-libs/qt-core" is blocking x11-libs/qt-4.3.3)
[blocks b ] <=x11-libs/qt-4.4.0_alpha:4 ("<=x11-libs/qt-4.4.0_alpha:4" is blocking x11-libs/qt-qt3support-4.4.2, x11-libs/qt-script-4.4.2, x11-libs/qt-dbus-4.4.2, x11-libs/qt-assistant-4.4.2, x11-libs/qt-xmlpatterns-4.4.2, x11-libs/qt-sql-4.4.2, x11-libs/qt-gui-4.4.2, x11-libs/qt-svg-4.4.2, x11-libs/qt-test-4.4.2, x11-libs/qt-core-4.4.2, x11-libs/qt-webkit-4.4.2, x11-libs/qt-opengl-4.4.2)
No need for a migration document, then -> GDP out.
The problem is that we cannot mask 4.3 until 4.4 is stable, otherwise stable would be left without qt-4 at all, until arches see fit to stabilize the 4.4 split ebuilds. So there will be a period in which some arches have 4.4.2 stable and others not, so we would need to leave 4.3 unmasked for those.
My conclusion is that we do need a migration document. But it may be as simple as telling users to mask qt-4.3*, upgrade portage to >=2.1.6_rc1, and then they should be able to upgrade smoothly.
(In reply to comment #15)
> The problem is that we cannot mask 4.3 until 4.4 is stable, otherwise stable
> would be left without qt-4 at all, until arches see fit to stabilize the 4.4
> split ebuilds. So there will be a period in which some arches have 4.4.2 stable
> and others not, so we would need to leave 4.3 unmasked for those.
Then tell arches to mask old and stable new at the same time. We do have per-arch masking...
OK, I fleshed it out, finally. I put the guide up at
and committed it to CVS for the KDE project space. It should show up there once the web mirror is synced. The location will be:
Could GDP also list it at http://www.gentoo.org/doc/en/list.xml please?
Ben, can you please clarify why this can't be nadled by Portage alone, without *any* user action?
In contrast to what you suggest in the guide, there's (according to Zac) no need to unmerge old version of Qt. All what is needed is to depend on recent Portage and to ask arches to mark 4.4 stable while masking 4.3 at the same time.
Please, don't produce a migration document just for the sake of documenting obvious things.
You are right. I set up a stable chroot for testing, and found that the upgrade path is indeed without problem, provided that:
- portage is version >=2.1.6
- qt split ebuilds are keyworded
- PyQt4 and dependencies (sip, qscintilla, qscintilla-python) are keyworded
- =qt-4.3* is masked
So with clear instructions to the arches doing the stabling, we should be fine.