From owner-freebsd-ports@FreeBSD.ORG Sat Oct 6 13:33:02 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 41AF8106566B for ; Sat, 6 Oct 2012 13:33:02 +0000 (UTC) (envelope-from lists@eitanadler.com) Received: from mail-pa0-f54.google.com (mail-pa0-f54.google.com [209.85.220.54]) by mx1.freebsd.org (Postfix) with ESMTP id 0BF168FC16 for ; Sat, 6 Oct 2012 13:33:01 +0000 (UTC) Received: by mail-pa0-f54.google.com with SMTP id bi1so3055860pad.13 for ; Sat, 06 Oct 2012 06:33:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=eitanadler.com; s=0xdeadbeef; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type:content-transfer-encoding; bh=lkjS4Cc6ft3R7eO8HVXsXJ7ozwyz2jymjsZJZgKEbxw=; b=lzRncfE9IN8Izh+aC1uvMBcEjNEVY6PZ6Yd2e+vF2OvfCXgMQyMn8qACL9a34esNNG C2l7lLrwYmPGfLeFzUa+C602ZRixo+2g8u+75KAEXSC9KN2r1aZ0ncb9QHV9yPW+wNar WAsk1GSER02Q1RNRd6BR8QyL/D7KPJq7TMaac= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type:content-transfer-encoding:x-gm-message-state; bh=lkjS4Cc6ft3R7eO8HVXsXJ7ozwyz2jymjsZJZgKEbxw=; b=i5FlgxJQEphHewg6IWnWy0pv3Y/tdXEN00lvWQfjEfnxPyL+yBskhy2szuYuE9qGCW WLH2dJankKu2iPNVWwycVfrDglJBG4HF5Gf+iAO00rEudYqAjiRIUYNcO7WYcxLk944M DmwR9ttGAN0Y6pRx7JoPtBF+83kMggXrSoZCRwzncimMoQOj7AlxkmsxUqtE/cFo9hXQ /5nLG8lgQPGfrQn6NG72oRAt0313x0fMcBCiXcUWAOfSnKoSixepKkELB+JOjBnITdBi EAf+ouRHBOKaxkAAp+JBdIXV9kBrYc6NjdPVQDWWBNEVYtrcLW89ZM9BrKz9UEfZo2or ot6A== Received: by 10.68.222.105 with SMTP id ql9mr38457235pbc.97.1349530381313; Sat, 06 Oct 2012 06:33:01 -0700 (PDT) MIME-Version: 1.0 Received: by 10.66.161.163 with HTTP; Sat, 6 Oct 2012 06:32:31 -0700 (PDT) In-Reply-To: <6B7F31C1-0A5C-4B65-AC5B-BCCE21817692@lafn.org> References: <6B7F31C1-0A5C-4B65-AC5B-BCCE21817692@lafn.org> From: Eitan Adler Date: Sat, 6 Oct 2012 09:32:31 -0400 Message-ID: To: Doug Hardie Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Gm-Message-State: ALoCoQnu7fLUt7ivD2uj4XTSwVK0wzlhlcVrzgLELWS9capkMFZsKLNCLITw7rZfPPuIdsWlEnYR 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 13:33:02 -0000 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 th= ings 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 provid= es. However, it does presume that you know a few things about the port str= ucture that are probably common knowledge to anyone involved with it, but n= ot to those of us who just "use" it. The first update I made to the Makefi= le cause a slew of make errors that were pretty much useless. They meant n= othing to me. My first thought was that somehow I had munged one of the in= cludes 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 read= ing the handbook, I noticed that in the PORT_OPTIONS clause you have to pre= cede the option name with a M. That is not at all obvious and is easily mi= ssed. 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' opti= on: :Mpattern Select only those words that match the rest of the modifie= r. 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 selecte= d is completely different from that for an option that is not selected. Th= at is just weird. The use of {} for one and () for the other again must ha= ve some reason other than it just won't work otherwise. No clue is given i= n 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 reg= ular diff. My recollection is that the last time a unified diff was reques= ted 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 bee= n 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 :) --=20 Eitan Adler