Skip site navigation (1)Skip section navigation (2)
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>