| Summary: | sys-apps/portage: preserve-libs is not documented enough | ||
|---|---|---|---|
| Product: | Portage Development | Reporter: | Rebecca Menessec <rebecca.menessec> |
| Component: | Documentation | Assignee: | Portage team <dev-portage> |
| Status: | RESOLVED FIXED | ||
| Severity: | normal | CC: | gentoo-bugs |
| Priority: | High | ||
| Version: | unspecified | ||
| Hardware: | All | ||
| OS: | Linux | ||
| Whiteboard: | |||
| Package list: | Runtime testing required: | --- | |
| Bug Depends on: | |||
| Bug Blocks: | 240323 | ||
Preserved-libs is documented in "man make.conf" under FEATURES -> preserved-libs. (There are 3 man pages that contain most, if not all, the information end users ever need to know: "man emerge", "man portage" and "man make.conf") Since preserved-libs is manged using sets, it's mostly self documenting anyway. To retrieve a list of libraries with preserved-libs, see "emerge -p @preserved-rebuild". Users don't need to know implementation details such as where information is stored by the package manager. It's not something users should edit. If that is documented, it'll be in the core portage documentation somewhere. If you're hacking on portage, you probably want to be reading its source code and talking to #gentoo-portage anyway. Not everything should be documented in the user documentation. Attempting to document absolutely everything creates unnecessary maintainance and gives anyone reading the man pages an information overload. Your issue with jpeg-7 is seperate. I can assure you that I have never seen emerge not tell why a package is being pulled in as long as the "-ptv" options are specified. You may not understand what it's telling you, but this is a different matter. Flags such as --deep have nothing to do with verbosity. --deep tells portage to do deep dependency checking. It's possible that using --deep may make it clearer why a package is being pulled in due to a different path being shown in the -pt output, but this does not increase verbosity of the emerge output (there's more output because more packages are being checked/included). All the major features of portage 2.1.7 and 2.2 are already well documented. If you are having specific issues, then you should investigate these specific issues and, where appropriate, report specific pieces or missing documentation that is useful to end users. In my opinion, without information on exactly what problem you are/were trying to solve and, where known, the solution, it's impossible for the developers to improve the documentation to help you. It should also be noted that preserved-libs is a feature of the testing version of the portage package manager and is currently under development. This means that deep documentation does not make sense because things may change before the final release, causing extra development workload to keep the documentation that most users don't need in the first place up-to-date. To reiterate: Unfortunately I suspect this particular bug will go nowhere without further information on the exact problem faced (and if known, the solution which wasn't documented). Please feel free to submit patches / specific suggestions for documentation changes. All right, "verbosity" was the wrong word. "Flags that cause portage to try harder," possibly. At any rate, -ptv definitely does not flag the jpeg-7-r1 case in any clear way as being linked to the preserved libs (again, I'm forced to assume). I don't see any special symbols, or a @preserved-libs tag or... anything. Here it is: spatha ~ # nice -n 19 emerge --complete-graph=True --deep --newuse --pretend --tree --verbose --with-bdeps=y --update world These are the packages that would be merged, in reverse order: Calculating dependencies... done! [nomerge ] dev-java/icedtea6-bin-1.6.2-r1 USE="-X -alsa -doc -examples -nsplugin -source" [ebuild NS ] media-libs/jpeg-7-r1 [8] 4 kB There *are* preserved libs left over from upgrading to jpeg-8, thus icedtea6-bin doesn't *need* jpeg-7-r1, but emerge wants to go ahead and emerge the build anyhow. And, again, no mention of why jpeg-7-r1, other than icedtea6-bin "wants" it. I can also get this without --complete-graph and --with-bdeps, by the way. If the preserved-libs feature isn't going to be documented in a manpage just yet, say, other documentation elsewhere would be helpful. Out of the three sources you named, there's an entry for "preserved-libs" in the manpage for make.conf that's extremely terse and doesn't explain (for instance) what happens if you turn the feature off. (I assume Portage goes with the usual behaviour of refusing to remove the package in question during -c, but will remove during -C. No idea what happens during upgrade if the flag is off-- apparently, it's set on by default, to guess from the behaviour, although, again, it doesn't say.) At any rate, I'd love to get some more information on this particular feature, at minimum, because it's exposed to end users, and 2.2_rc builds have been in ~ for some time now. After using Gentoo for the last... seven? ...years, I'm learning that any number of incredibly useful or even crucial ebuilds stay marked ~ for an incredibly long time, or sometimes aren't even keyworded. I suspect I'm far from the only person who's been using portage-2.2* since the moment it made ~. If core docs aren't going to contain info on features in development (from inference, preserved-libs is one), a wiki or announce-only listserv or other would be extremely helpful in figuring out what's currently in play for unstable portage builds and-- I feel this is crucial --how to help test. As of now, I can't really file a bug against preserved-libs if I need to, because all the discussion appears to be taking place between sys-apps/portage devs and nowhere else. So, again, if there simply is no documentation on this feature as yet, and I can't give you examples of more features I feel are underdocumented because I don't know what they are or how to invoke them: please, more information on preserved-libs. How do I examine and handle preserved libraries? This is not encouraging to my sense of adventure: spatha ~ # file /var/lib/portage/preserved_libs_registry /var/lib/portage/preserved_libs_registry: 8086 relocatable (Microsoft) I've been wanting to file a bug titled "sys-apps/portage needs to use a less filesystem-punishing format; please convert to SQLite3" for a long time now, but I assume this is not a step toward sqlite storage nor any other format I can easily parse with a cmdline utility... The stuff that's in portage-2.2 isn't well supported and needs to evolve before it will ever be unmasked (see bug 253802). See issues with package sets (bug 144480) and preserve-libs (bug 253802). Anyway, patches are welcome. (In reply to comment #2) > spatha ~ # file /var/lib/portage/preserved_libs_registry > /var/lib/portage/preserved_libs_registry: 8086 relocatable (Microsoft) It's really a python pickle file. I'm planning to make it use a text file instead. Also, I want the preserved libs to be moved to a quarantine directory, as said in bug 286714. (In reply to comment #3) > 144480) and preserve-libs (bug 253802). Anyway, patches are welcome. For preserve-libs I meant bug 240323. The graph says icedtea6 is pulling in the package. A look at the deps on icedtea6 (via http://sources.gentoo.org/viewcvs.py/gentoo-x86/dev-java/icedtea6-bin/icedtea6-bin-1.6.2-r1.ebuild?view=markup ) says it depends on =jpeg-7* - that means it cannot use jpeg-8 (most likely because it's a binary package and there's uncompatible changes in jpeg-8 - not an uncommon scenario). The graph is correctly displaying the full information. Portage 2.2 has only 2 significant features not available in the 2.1.7 branch - sets and preserved-libs. preserved-libs is basically an (incomplete) replacement for what is currently done using revdep-rebuild (by another method). If you disable preserved-libs, you simply fall back to the old method of running revdep-rebuild instead to fix broken libraries. The most significant difference is that the preserved-libs way of doing things is less likely to stop packages working during the upgrade process (it preserves the libraries still in use until after the packages using them have been rebuilt, whereas the "revdep-rebuild method" breaks the packages until you fix them when you run revdep-rebuild) A news item about preserve-libs was sent out recently: http://sources.gentoo.org/gitweb/?p=proj/gentoo-news.git;a=commit;h=982f2f6e7142769a594c1be2f080b8b7c82a8214 It includes a link to this page which wiki users can add information to as necessary: http://wiki.gentoo.org/wiki/Preserve-libs |
Just as a simple example, Portage emits useful information such as "!!! existing preserved libs found", and may mention that "emerge @preserved-rebuild" will re-emerge dependent packages, but documentation ("emerge --help --verbose" and "man emerge") don't include this information, nor any supporting information (where this information is stored, how to clear it, how to list *what* libraries or what packages they belong[ed] to, and so forth). If this information is in separate utilities, the manpage and --help --verbose need to be loaded down with pointers to the other utilities. By the way: emerge --update world with enough "verbose" flags (--deep, etc.) *seems* to be a clue to what packages have preserved libraries hanging around, but this isn't necessarily clear, and adding -ptv doesn't actually say *why* emerge wants to pull in (in this instance) jpeg-7-r1. Reproducible: Always Steps to Reproduce: Actual Results: Spotty post-Portage 1.x documentation, no post-Portage 2.0 documentation. Expected Results: Post-Portage 1.x documentation through the most recent builds. While I could definitely use information on the preserved-lib handling (commands, options, etc.) now, I'm hoping someone will take the time to document *all* the things Portage 2.x emerge and other utils do. If I can't even find this information with Google and Bing (and I can't), I think there's a real problem.