In a lively discussion on gentoo-dev@ [1], Jakub Moc has pointed a dev handbook chunk [2] which seems a bit weird to me. It is about favouring a USE flag over another incompatible one. It would probably be offtopic to comment about that in this ML thread, but still, i don't agree the example, and think it would at least be worth some clarification: Because GnuTLS is more featureful than OpenSSL, it is favoured: [...] if use ssl && use gnutls ; then myconf="${myconf} --enable-ssl --with-ssl=gnutls" elif use ssl && ! use gnutls ; then myconf="${myconf} --enable-ssl --with-ssl=openssl" else myconf="${myconf} --disable-ssl" fi How does the quoted ebuild code favour GnuTLS over OpenSSL? If i read it correctly, users who don't have a clue about gnutls/openssl differences but just want some kind of SSL support (and thus only have USE="ssl", but no other library-specific flags, just like it is in profiles) will get msmtp compiled for OpenSSL, and not for GnuTLS. Isn't this behavior the exact opposite of "favouring GnuTLS"? Maybe i'm wrong, but for me a better example would have been something like: IUSE="ssl gnutls openssl" [...] if use ssl && use openssl && ! use gnutls ; then myconf="${myconf} --enable-ssl --with-ssl=openssl" elif use ssl ; then myconf="${myconf} --enable-ssl --with-ssl=gnutls" else myconf="${myconf} --disable-ssl" fi This way, you really get it compiled for OpenSSL when explicitly required by the user's flags (USE="ssl openssl -gnutls"), and get the favoured one (GnuTLS) as default SSL library. Sure, the drawback is that it makes the conditionnal DEPENDs a bit more complex. Also, an other example of favouring a USE flag, which is simpler because there is no "feature" flag (like "ssl" above) involved, is the choice of an optionnal Gecko backend in net-news/liferea. Choice is beetween none, mozilla, and firefox, with firefox prefered if USE="mozilla firefox": DEPEND="[...] firefox? ( www-client/mozilla-firefox ) !firefox? ( mozilla? ( www-client/mozilla ) )" [...] if use firefox ; then G2CONF="${G2CONF} --enable-gecko=firefox" elif use mozilla ; then G2CONF="${G2CONF} --enable-gecko=mozilla" else G2CONF="${G2CONF} --disable-gecko" fi It sounds less subject to misinterpretation to me, so maybe it would make a better example? Oh, and in case it's just me who misunderstood this part of the HB or some policy (i know it happens), well, apologizes... [1]http://article.gmane.org/gmane.linux.gentoo.devel/36297 [2]http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/devrel/handbook/hb-guide-ebuild.xml?r1=1.25&r2=1.26&root=gentoo
The "use ssl" in the first part and then the "&& ! use gnutls" in there was redundant and confusing -- should be clearer now. I think the problem really was in the English and not in the ebuild code -- what that implies is if GnuTLS is specifically enabled by the user then it will take precendence over OpenSSL. Otherwise, OpenSSL is chosen. Not "choose GnuTLS by default against OpenSSL". So the code does this: |+gnutls|-gnutls| +ssl: |GnuTLS |OpenSSL| -ssl: ---- No SSL ---- Now, you might have an "openSSL" flag as well. However, that won't help anything if you have +gnutls and +openssl at the same time -- your ebuild will still have to end up favouring something. And if you choose OpenSSL to be favoured by default then having an explicit OpenSSL flag is redundant (you could just do -gnutls).
(In reply to comment #1) > I think the problem really was in the English and not in the ebuild code That's a matter of point of view :) But, be it wrong code or wrong english, i think the mismatch is still there despite your change: the description for the "ssl" flag is "Adds support for Secure Socket Layer connections", but here "adding SSL support" is using OpenSSL, despite the example description saying that GnuTLS is more featureful and thus favoured. Either the description or the code should change its logic imho: - you can say: "OpenSSL is the favoured SSL implementation because it's less featureful, but user can override it with the "gnutls" flag." - or you can change the code. A simpler way to do it would be to drop the "gnutls" flag, and replace it with "openssl" ("mail-mta/msmtp:openssl - Prefer OpenSSL over GnuTLS for SSL support"): IUSE="ssl openssl" ... if use ssl && use openssl ; then myconf="${myconf} --enable-ssl --with-ssl=openssl" elif use ssl ; then myconf="${myconf} --enable-ssl --with-ssl=gnutls" else myconf="${myconf} --disable-ssl" fi > Now, you might have an "openSSL" flag as well. Yup, there should be one, at least for GnuTLS to really be the default (see either the above code or the one from my previous comment), and, at your option, so that there is really a flag-conflict to fix in the example (see explanation just below). > However, that won't help anything if you have +gnutls and +openssl at > the same time It helps the purpose of the example, which was supposed to be about conflicting flags. Point is that, in their semantics, there is absolutly no conflict beetween "ssl" and "gnutls" flags. This flags are just: - "feature" (which has a prefered implementation) for the former - "particular-implementation-of-feature" for the later It's just what "gtk" / "gtk2" used to be, or alike. Or, if there is a conflict like the HB paragraph suggests, it's because of an additional assumption ("SSL defaults to OpenSSL"), which is not stated in use.desc, and is in contradiction with the example description. That's what makes it so confusing i think. Using both "gnutls" and "openssl" is the only way i can think of to introduce a real conflict here, with there meanings being, respectively: - "prefer GnuTLS for SSL implementation" - "prefer OpenSSL for SSL implementation" Then it makes sense to speak about favouring one flag over the other. As for keeping "ssl" instead of just using the gnutls+openssl, it was for still getting SSL support with the default flags from profiles. It keeps it's use.desc meaning ("enable SSL support"), and defaults to the best implementation for users who don't have a clue. > -- your ebuild will still have to end up favouring something. Agreed. > And if you choose OpenSSL to be favoured by default then having an explicit > OpenSSL flag is redundant (you could just do -gnutls). If OpenSSL is really meant to be favored by default, then the description really should be changed to something like i've proposed above. Ok, i will stop there, but just for completeness while i'm here, here is another attempt of a better example. The flags are really in conflict, and, unlike the SSL thing or the Gecko backend in Liferea, the feature it is about is not optional (which makes it more clear i think, more targeted on the conflict issue). It is from "media-tv/xdtv": This ebuilds needs a Xaw-compatible library for its GUI. The default is to use the standard one, x11-libs/libXaw, but x11-libs/neXtaw and x11-libs/Xaw3d can be choosed as replacement through USE flags. In case both are asked for, neXt is prefered over Xaw3d: IUSE="neXt Xaw3d" ... if use neXt ; then use Xaw3d && ewarn "Both \"neXt\" and \"Xaw3d\" found in USE. Will use neXtaw widgets." xawconf="${xawconf} --enable-nextaw --disable-xaw3d" elif use Xaw3d ; then xawconf="${xawconf} --disable-nextaw --enable-xaw3d" else xawconf="${xawconf} --disable-nextaw --disable-xaw3d" ewarn "If you want a better GUI toolkit, enable either \"neXt\" or \"Xaw3d\" USE flags." fi Ok, that's it. Sorry if i did sound a bit heavy for a bug which i agree is rather minor. I swear i won't reopen a 2nd time :)
> - you can say: "OpenSSL is the favoured SSL implementation because it's less > featureful, but user can override it with the "gnutls" flag." this description is wrong as that isnt what the code is doing ... the current text describes the situation just fine: Because GnuTLS is more featureful than OpenSSL, it is favoured. > - or you can change the code. A simpler way to do it would be to drop the > "gnutls" flag, and replace it with "openssl" ("mail-mta/msmtp:openssl - Prefer > OpenSSL over GnuTLS for SSL support"): no > It helps the purpose of the example, which was supposed to be about > conflicting flags. it's more about conflicting functionality ... in this case, openssl and gnutls cannot be used at the sametime if we rewrite the paragraph to read: Occasionally, ebuilds will have conflicting optional features. Checking for these conflicts and returning an error is <e>not</e> a viable solution. Instead, you must favor one of the features over the others. As to which, consult upstream (what they use as typical default), or consider which option provides more common functionality, or just flip a coin. there shouldnt be any confusion
(In reply to comment #3) > the current text describes the situation just fine: > > Because GnuTLS is more featureful than OpenSSL, it is favoured. I understand that, out of any interpretation, writing "if use foo ; ... elif ..." favours "foo" over whatever comes next. But USE flags also have some semantics (use.desc), and in this particular case, i think taking it into account shows the code mismatches the stated intent: users who simply ask for "SSL support" (USE="ssl", like in profiles) will get the sub-optimal implementation (OpenSSL), which is the opposite favouring GnuTLS. At the contrary, I would see this sentence as perfectly accurate if the two flags involved were "gnutls" and "openssl" (with thus the following semantics for the whole thing: turn on at least one to get some SSL support, and if both are, then GnuTLS is favoured). But oh well, this really seems to be a matter of interpretation, and i think i now understand yours too. Works for me if you keep the example as-is. > > drop the "gnutls" flag, and replace it with "openssl" > > ("mail-mta/msmtp:openssl - Prefer OpenSSL over GnuTLS for SSL support"): > > no That, i would be interested to learn why if you have a moment to explain. To me, since a flag must be used anyway, it's better to put it on the 2nd choice implementation, because it will be off by default. This way, users who don't have a clue (profile USE flags) get the optimal implementation. Or is it just because you prefer to use an existing global flag rather than adding a local one? > Occasionally, ebuilds will have conflicting optional features. Checking for > these conflicts and returning an error is <e>not</e> a viable solution. > Instead, > you must favor one of the features over the others. As to which, consult > upstream (what they use as typical default), or consider which option provides > more common functionality, or just flip a coin. Yes, it's better this way. Thanks to both of you for the clarifications.
added suggestion wording to cvs then
