Date: Sat, 6 Oct 2012 10:48:55 -0700 From: Doug Hardie <bc979@lafn.org> To: Eitan Adler <lists@eitanadler.com> Cc: FreeBSD-PORTS <freebsd-ports@freebsd.org> Subject: Re: New Port Options Message-ID: <71FE6F55-920F-4F59-9242-AAACB5FAACFE@lafn.org> In-Reply-To: <CAF6rxgkbrO0pgvgu4g1-iJjxwWeO_8W5y0aX7=1cK_ioAxMjUA@mail.gmail.com> References: <6B7F31C1-0A5C-4B65-AC5B-BCCE21817692@lafn.org> <CAF6rxgkbrO0pgvgu4g1-iJjxwWeO_8W5y0aX7=1cK_ioAxMjUA@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?71FE6F55-920F-4F59-9242-AAACB5FAACFE>