Portfile guidelines (was [26328] trunk/dports/gnustep/Etoile/Portfile)

[Juan Manuel Palacios]

On Jun 20, 2007, at 11:29 AM, Yves de Champlain wrote:

>>
>>
>> 	I see... it did not seem to me like you were building a different  
>> version of the package, indeed, but your commit log did raise my  
>> eyebrows ;-) So if you're still working with the same source tree,  
>> maybe we could think up some different names for your variants?  
>> (Yes, in this case two different ports would not be the best  
>> approach, most definitely). I was thinking, if possible with your  
>> source tree, maybe you could split the full build and the debug  
>> functionality in two different logical blocks? Thus your port  
>> would have something like +full (or whatever other name is more  
>> appropriate for the full build) and +debug (which would enable  
>> building with debug symbols). Based on that, full + debug == your  
>> current 'devel' variant. That's just a suggestion that I'm hoping  
>> is not too outlandish with respect to Etoile, of which I know  
>> nothing about.
>>
>> 	I know we don't have a written on stone mandate for variant  
>> naming, and maybe we should actually have it, but for the time  
>> being I believe working with the jurisprudence set by previously  
>> accepted practices is a fairly reasonable thing to do. In this  
>> case, said jurisprudence suggests a +devel variant is something to  
>> avoid in favor of *-devel ports. I know this is not your  
>> particular case with Etoile (you're not changing version number),  
>> as you made clear, but then I'd say "lets avoid the confusion  
>> too" ;-)
>
> This seems like a very good solution to me.  I am definitly in  
> favor of coherent naming schemes and guidelines.


	Totally for a variant naming guideline doc! But on that topic, read  
my recent message (cc'ing this list) to Maun Suang on the MacPorts  
guide, this type of document should most definitely be part of the  
"official" guide. Would you care to write a first draft and  
coordinate with Maun Suang its inclusion in the guide?

>
> While being there, an update to the newmaintainer wiki page would  
> be nice :
>
> 1- because it suggests that svn commit access needs ssh which turns  
> out to be quite unstable.


	"svn switch --relocate" to http://svn.macports.org/repository/ 
macports, MacOSForge uses http digest auth, no need for ssh/ssl.

>
> 2- to include some variants naming guidelines like
>
> - devel is not a variant name, it is reserved for different ports  
> that install different version of a single package (quite a few  
> ports have a devel variant actually)


	Agreed on the first count. On the second one, maintainers of those  
ports should be ping'd to correct that, 'devel' should be reserved  
for a foo-devel port.

>
> - don't use "+" or "-" in variants names because they are "reserved  
> words" of the variant mechanism (many ports still use "-" which  
> just does not work).


	Agreed too, replace all instances of - (as a word separation  
character, I'm assuming) with _, and + I just don't know what it's  
used for, but it definitely does not belong there! (use _ too?)

>
> - a port's default variant (including no variant) should usually  
> install the full features (except if it looks like madness)


	This is a hotly debated topic: should ports be minimalists,  
deferring all non-default/basic extensions/functionality to variants?  
Or should they instead be all encompassing, providing everything the  
package has to offer out of the box? Somewhere in between, per  
maintainers' better judgement? I would support the latter, but I am  
more than aware that's a very grey area to be in, so I'll let others  
with stronger positions venture their opinions.


>
> - variants should have a description


	We should make this a must!

>
> - platform variants are named "platform" instead of "variant" (many  
> ports again)


	Agreed too, common mistake that should be corrected.

>
> - typical names : no_* x11 gtk2 aqua debug server ipv6


	Aha, I like common names and people standardizing on them by sheer  
practice and/or jurisprudence (gotta love that word!), among other  
things that buys us the assurance that "variant cascading" will work  
seamlessly (port foo depending on port bar builds with variant baz,  
MacPorts will try to build bar with variant baz too if it provides it  
-- that fails if foo and bar name the variants differently, a total  
waste!). But I fail to understand what you tried to say with your  
sentence above...?

	In any case, common names should be documented in the guide and  
anywhere between encouraged and enforced ;-) A settlement on them  
also sorta implies an answer to my question above: should ports be  
minimalist or fully featured? If 'no_ipv6' becomes a standard  
variant, then they are minimalist; if instead 'ipv6' becomes the  
standard, then they are fully featured. The middle ground I'd like to  
advocate means having, for example, 'ipv6' as a standard and 'no_x11'  
as another one.


>
> - more obscure names should either have a good description or a  
> clearer name like with_* / without_* / enable_* / disable_* to at  
> least give a clue if we are triggering a dependency or an inner  
> mechanism.  A good example : disable_utf8mac,  
> disable_extra_encodings, enable_cp932fix (libiconv).


	Seconding Ryan in his reply to you, I favor simpler and shorter  
variant names. In all cases, variant descriptions should do a good  
job at explaining what they are about and what they imply with  
respect to the build and deps... that is, at explaining them ;-)

>
> yves



	Regards,...


-jmpp