From owner-freebsd-ports@FreeBSD.ORG Sat Oct 6 17:48:59 2012
Return-Path: <owner-freebsd-ports@FreeBSD.ORG>
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 <freebsd-ports@freebsd.org>; 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 <freebsd-ports@freebsd.org>; 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 <bc979@lafn.org>
In-Reply-To: <CAF6rxgkbrO0pgvgu4g1-iJjxwWeO_8W5y0aX7=1cK_ioAxMjUA@mail.gmail.com>
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>
<CAF6rxgkbrO0pgvgu4g1-iJjxwWeO_8W5y0aX7=1cK_ioAxMjUA@mail.gmail.com>
To: Eitan Adler <lists@eitanadler.com>
X-Mailer: Apple Mail (2.1283)
X-Virus-Scanned: clamav-milter 0.97 at zoom.lafn.org
X-Virus-Status: Clean
Cc: FreeBSD-PORTS <freebsd-ports@freebsd.org>
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 <freebsd-ports.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-ports>,
<mailto:freebsd-ports-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-ports>
List-Post: <mailto:freebsd-ports@freebsd.org>
List-Help: <mailto:freebsd-ports-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-ports>,
<mailto:freebsd-ports-request@freebsd.org?subject=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 <bc979@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:
>=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