I was just reviewing the Gentoo Developer Handbook, looking for some answers, learning new things, and have some notes which I think may help to improve the handbook. I wasn't sure whether submitting 24 separate bug reports (labeled 0 to L) was appropriate, so I've rolled them all into one big list: 0 The Developer Handbook does not specify the inheritance/incremental/ accumulative behavior of eclass/ebuild variables, i.e. HOMEPAGE, SRC_URI, KEYWORDS, IUSE, LICENSE, DEPEND, RDEPEND, PDEPEND, etc. Exactly which variables are inherited from parent ebuilds? Are they all exported? Do the settings in ebuilds replace or add to the current settings? (Depending on how the eclass/ebuild is sourced, either of these is technically possible.) 1 Should the flags in IUSE be a comprehensive list? 2 Regarding KEYWORDS, "this variable specifies what architecture the ebuild is meant for". Should this be an exhaustive list which specifies each architecture as one of ARCH/~ARCH/-ARCH? Does having "-ARCH" in KEYWORDS mean the same as if ARCH is missing from KEYWORDS? What does "-*" do at the beginning of KEYWORDS? At the end? In the middle? (Some ebuilds do these things!) 3 Should state that ebuilds MUST be fully automated and that user interaction MUST NOT be required. 4 Doesn't indicate when HOMEPAGE undergoes variable substitution (i.e., ${PN}) when a generic HOMEPAGE (cf. sourceforge example) setting is inherited from other eclasses. 5 It doesn't mention or describe the function of the PDEPEND variable. 6 Doesn't state whether or not to list only direct dependencies in DEPEND. If: foo directly depends on libfoo and bar directly depends on both foo and libfoo, does DEPEND="foo" or DEPEND="foo libbar"? I've seen comments in ebuilds to the effect that some dependency libfoo isn't necessary because it's pulled in by dependence on foo... which strikes me as a dangerous game. If the dependencies for foo ever change, or foo's dependence upon libfoo becomes conditional on USE flags, this could break the bar ebuild, which directly depends on that libfoo.... 7 It doesn't say *when* the dependencies in REDEPEND and PDEPEND are built. Are they all (DEPEND+RDEPEND+PDEPEND) merged *before* the dependent package is built? Immediately after it's merged? Or maybe just added to the end of the merge queue? 8 "Generally, emerge blows ebuild out of the water"... statements like this should be accompanied by a BIG BRIGHT CAVEAT that, in some circumstances, portage does not order ebuilds correctly. To omit this is to (even if only implicitly) over-represent what portage is technically capable of. While blanket praise for portage may be good propaganda for inclusion in the Gentoo Handbook (user guide), developers should be told the whole truth. :) 9 Doesn't state whether DEPEND/RDEPEND/PDEPEND variables are ever eval'd or if functions like built_with_use can be used inside of them. A Policy concerning circular dependencies. B There's no documentation on the built_with_use function. C Description of best_version function does not state whether the returned name includes any {_suf{#}}{-r#} suffixes. D The ebuilds should make clear whether the package being distributed is in source, binary, or hybrid source/binary form. It should make clear if a binary/hybrid package is a compiled version of sources currently available in the portage tree (typically by using a -bin suffix) or if the sources for it are otherwise available (i.e., the sources are on an FTP site but have not yet been bundled into an ebuild). Simply seeing an "emake" or the like in the ebuild is not sufficient to ascertain this, because some binary/binary-source hybrid packages contain makefiles for auxiliary utilities, generating documentation, etc. E It should also be made explicit that bytecodes (such as Java bytecode, emacs lisp bytecode, etc.), binary codecs, and firmwares are binary formats. F License filenames should not contain the substring "free-" or "-free" unless the licenses really are FOSS, nor contain the string "GPL" unless really GPL or LGPL. For example, the license name "SIL-freeware" (a non-free license) is misleading due to this fact. A binary-only license named "ZGPL" would similarly be misleading. G "Your package, when complete and unmasked, is supposed to "just work" for the end-user." Should state that running rc-update from an ebuild by default is a big no-no. State that having to run /etc/init.d/initscript start and/or rc-update is okay, but that running pkg_config should not be necessary. H The doc does not provide any policy or guidelines for things like adding users or groups, the allocation of UID/GIDs, installation of setuid executables, or other kinds of system munging. I Should contain brief guidance on how to "roll your own merge"... that is, how to resolve and order package dependencies on your own/manually/without the aid of emerge. 1. Get an ebuild's package name, 2. use best_version on it 3. use depend and fetch (how to pretend an ebuild fetch?) J The handbook could use a section at or near the end with a BIG FAT HEADING saying where to go for information not presented in the Developer Handbook: (1) If you want information on using catalyst or making your own stage tarballs, go to... (where is that info, anyway?) This is a kind of developer-ish topic which people might look at the Developer Handbook to find out... but it's not in here. If use of catalyst is beyond the scope of the Developer Handbook, it should gently direct the mistaken reader to a more appropriate source. (2) If this is all too complicated and you need more basic information on Gentoo: Gentoo Handbook Gentoo Homepage Gentoo Documentation Project K No Linux documentation can be complete without containing at least one nerdy joke. L The Developer Handbook doesn't say whether it's preferred to submit a separate bug report for each of many bugs found at once, or to bundle them all together and treat them as one, big, composite bug. (like this one!)
0. Looking at ebuild.sh it inherits whatever the last sourced eclass set, i.e. they get replaced. The exceptions to this are IUSE, DEPEND, RDEPEND and PDEPEND which are always concatenated along with the inheritance tree. 1. Yes, IUSE must list *all* USE flags used by your ebuild except arch flags which are special. 2. Order doesn't matter at parsing stage unless things negate each other... and what happens then depends on the Portage code. -ARCH specified and ARCH missing imply different things. One implies the package has not been tested on ARCH (if missing), -ARCH specifically implies that it has been tested, fails to work, and kills bunny rabbits. 4. Normal bash rules apply for substitution if HOMEPAGE is used inside the ebuild. As for whether Portage and external apps that parse ebuilds honor this is another matter. Variable inheritance for HOMEPAGE is no different to that of any other "normal" variable as answered in #0. 6. Yeah, if libxbuttons needs libdrawpretty but your app only needs libxbuttons then you only need to depend on libxbuttons... for all you know the next libxbuttons might need libdrawsuperpretty and your libdrawpretty DEPEND is redundant. 7. RDEPEND is dependant on Portage. It can be before, it can be after. Your app doesn't care so why should you. PDEPEND is explicitly after (man 5 ebuild). 8. emerge is the yin and ebuild is the yang :) 9. Oh dear. No, they must be USE atoms... Otherwise Portage barfs and just generally laughs at you very very hard. USE-based dependencies will eventually be implemented some time, I hope. B. That's an eutils.eclass feature. Check out portage-manpages. C. Should do, built_with_use internally runs portageq for its voodoo which should spit out the direct version. D. And how do you plan on solving this? F. Is this in policy anywhere? If not it needs to be agreed upon. G. Hm, that's nasty and more like a QA violation. H. That's also an eutils.eclass feature. I. Uhm, why do you want to do that? J. (1) gentoo-catalyst mailing list Yes, it's outside the scope and I'm not sure how catalyst needs to be mentioned in there... (2) Isn't that implied by the pretty headings to the left of the rendered HTML page. Or things on the front page? K. Um, yes, our appointed jester kinda ran off when we asked him to start doing proper work. L. And that's outside of the scope of the Developer Handbook :) 3., 5., A., E., G., could do with fixing :)
This is a 6 years old bug and rather obsolete. Patches are always welcomed
