From owner-freebsd-ports@FreeBSD.ORG Sat Oct 6 17:48:59 2012 Return-Path: Delivered-To: freebsd-ports@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 6F0401065672 for ; Sat, 6 Oct 2012 17:48:59 +0000 (UTC) (envelope-from bc979@lafn.org) Received: from zoom.lafn.org (zoom.lafn.org [108.92.93.123]) by mx1.freebsd.org (Postfix) with ESMTP id 4A2748FC16 for ; Sat, 6 Oct 2012 17:48:59 +0000 (UTC) Received: from [10.0.1.2] (pool-98-112-217-228.lsanca.fios.verizon.net [98.112.217.228]) (authenticated bits=0) by zoom.lafn.org (8.14.3/8.14.2) with ESMTP id q96HmtYW033527; Sat, 6 Oct 2012 10:48:56 -0700 (PDT) (envelope-from bc979@lafn.org) Mime-Version: 1.0 (Apple Message framework v1283) Content-Type: text/plain; charset=us-ascii From: Doug Hardie In-Reply-To: Date: Sat, 6 Oct 2012 10:48:55 -0700 Content-Transfer-Encoding: quoted-printable Message-Id: <71FE6F55-920F-4F59-9242-AAACB5FAACFE@lafn.org> References: <6B7F31C1-0A5C-4B65-AC5B-BCCE21817692@lafn.org> To: Eitan Adler X-Mailer: Apple Mail (2.1283) X-Virus-Scanned: clamav-milter 0.97 at zoom.lafn.org X-Virus-Status: Clean Cc: FreeBSD-PORTS Subject: Re: New Port Options X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 06 Oct 2012 17:48:59 -0000 On 6 October 2012, at 06:32, Eitan Adler wrote: > On 6 October 2012 01:01, Doug Hardie 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: >=20 > 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. >=20 >> 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. >=20 > 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. >=20 >> 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. >=20 > make(1) allows processing on variable contents. In particular the 'M' = option: >=20 > :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 (`\'). >=20 >=20 > 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. >=20 >> 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. >=20 > 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. >=20 >> 3. The examples are a bit difficult to distinguish between {} and = (). I had to look quite a few times before I figured that out. >=20 > 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. >=20 >> 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. >=20 > This is likely an oversight. Unified diffs are much preferred. I've > sent in a patch for approval to correct this issue. >=20 >> I only maintain one port so the effort to make the changes would have = been quite minor for additional ports. >=20 > As I said above, your perspective is needed when it comes to the > documentation. >=20 >> Its really not that big a change from the maintainer's point of view >=20 > 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. >=20 >=20 >=20 > --=20 > Eitan Adler >=20