New Port Options

[Eitan Adler]

On 6 October 2012 01:01, Doug Hardie <bc979 at lafn.org> wrote:
> I just converted a port over to the new options structure and have a few observations.  I have not been involved in any of the discussions about the structure as I didn't have the time to get involved.  However, a couple things came to mind during the process:

Thank you very much for this mail. Since the people writing the
documentation are often the people "very involved" it can be hard to
understand what may confuse someone that isn't insane^W^W doesn't work
on ports all the time.

> 1.  The Port handbook is actually quite good in the information it provides.  However, it does presume that you know a few things about the port structure that are probably common knowledge to anyone involved with it, but not to those of us who just "use" it.  The first update I made to the Makefile cause a slew of make errors that were pretty much useless.  They meant nothing to me.  My first thought was that somehow I had munged one of the includes and managed to include some random file rather than the right one.

make(1) errors can be pretty obtuse at times. It is hard to account
for all the errors here, but is there something specific that would
have helped you?

> My second idea was that I had typed the option names wrong, but that didn't seem to fit with the error messages either.  After quite a while of reading the handbook, I noticed that in the PORT_OPTIONS clause you have to precede the option name with a M.  That is not at all obvious and is easily missed. Why an M is also baffling.  I am sure there is a reason other then it just won't work otherwise.

make(1) allows processing on variable contents.  In particular the 'M' option:

     :Mpattern   Select only those words that match the rest of the modifier.
                 The standard shell wildcard characters (`*', `?', and `[]')
                 may be used.  The wildcard characters may be escaped with a
                 backslash (`\').


This should be made more clear in the handbook.

> 2.  The syntax for a conditional expression for an option that is selected is completely different from that for an option that is not selected.  That is just weird.  The use of {} for one and () for the other again must have some reason other than it just won't work otherwise.  No clue is given in the handbook.

See bapt@'s comments. That said, it should be made more clear ;)

> 3.  The examples are a bit difficult to distinguish between {} and ().  I had to look quite a few times before I figured that out.

Was this a font issue? Is there something we could do to help? Perhaps
add more spacing?

> 4.  The handbook shows for submitting a change to a port the use of a regular diff.  My recollection is that the last time a unified diff was requested so that things like the file names show.

This is likely an oversight. Unified diffs are much preferred.  I've
sent in a patch for approval to correct this issue.

> I only maintain one port so the effort to make the changes would have been quite minor for additional ports.

As I said above, your perspective is needed when it comes to the
documentation.

> Its really not that big a change from the maintainer's point of view

This is good to know :)



-- 
Eitan Adler