New Port Options

[Doug Hardie]

On 6 October 2012, at 06:32, Eitan Adler wrote:

> 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.

For me (and possibly others) the makefile is a necessary "evil" to get things to work.  Its not something we spend any more time on than necessary.

> 
>> 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?

Thats really difficult to say at this point - now that I have read all the comments and understand whats actually happening.  I had a number of options and there were complaints about single letters.  Eventually I noticed that they matched the first letter of each option.  That led me to the M in the example.

> 
>> 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.

Perhaps a note in the handbook prior to the examples that when referencing an option name, the letter M must be prepended because of the way make works.  Forgetting to include the M will cause some really weird error messages.

> 
>> 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 ;)

I would have used some of the alternate expressions if I had known about them.  I will never remember what those mean the next time I have to look at the makefile.

> 
>> 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?

Perhaps its a font issue, but I am not sure I would have noticed it the first time anyway.  I was just quickly scanning to see what needed to be done.  I make no pretense of understanding makefiles.  I just use them.  Perhaps a note where the constructs are introduced would catch the reader's attention.

> 
>> 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 :)

I was originally dreading going into a complex makefile that I inherited and have never opened up before.  I put this off as long as I could get away with because of that.  It turned out to be fairly simple once I knew how to do it right.

> 
> 
> 
> -- 
> Eitan Adler
>