Date: Sat, 12 Jan 2008 11:07:37 -0600 From: Paul Schmehl <pauls@utdallas.edu> To: FreeBSD Ports <freebsd-ports@freebsd.org> Subject: Re: Suggested improvements for ports Message-ID: <C65806EC3DF5B1A0EFA06B0E@paul-schmehls-powerbook59.local> In-Reply-To: <47884F14.3040708@FreeBSD.org> References: <ED8842DFA28376008F3CA3A4@utd59514.utdallas.edu> <47884F14.3040708@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--On January 11, 2008 9:24:36 PM -0800 Doug Barton <dougb@FreeBSD.org> wrote: > I'm going to try to combine your two posts so that I can answer in one, > my apologies if I scramble something. > First, thanks for you answer. Second, a clarification. I started this thread from the viewpoint of a port maintainer (I maintain about 10 ports) who is concerned about confusing users. It was not my intent to advocate for a rigid set of rules that all port maintainers must follow. Rather, it was my intent to point out some laxity in the present docs that result in ports being created in many different ways resulting in confusion for end users. >> >> 1) You can't build a dependent port and first set the config for the >> options that you want. So, when you select sasl in postfix, you never >> get the chance to check the saslauthd option, for example. > > Portmaster actually does a depth-first traversal of the dependency tree > which allows you to do this. > Interesting. I haven't used portmaster because I'm used to doing things the "traditional" way. I *thought* portmaster was a replacement/improvement of portupgrade, so I'm not sure how it would apply when you're installing ports for the first time. Guess I need to read the docs. > >> 2) There's no standard for some of the details of port building. > > Now you're mixing in "developer" issues with "user" issues. The user > should never have to see the details you're describing here, although if > (as I gather from later in the thread) your desire is improved "how to" > docs for ports creation, than I support that goal. > Docs improvement is my goal. An ancillary goal is to achieve more consistency in the way that ports are created/configured. >> it's entirely up to the port maintainer and the committer to decide how >> to build the port. The postfix port maintainer *could* include a >> dependency for saslauthd. He chose not to. He *could* include a note >> in pkg-message that warns you that saslauthd needs to be installed as >> well. He chose not to. His choices are both reasonable and customary, >> but they don't serve the customer well. > > Now here you have to be careful. The way we handle this problem is for > those who want/need saslauthd-related postfix to create a > postfix-saslauthd version, and handle that support themselves. Bonus > points if you can do it as a slave port, but that isn't always the case. > Please note, I'm not speaking theoretically here, I've been on both > sides of this issue, and so (modulo the prospect of user confusion with > N * M different varieties of the same port) the system works. > I've btdt too. I built a slave port for one of my ports because the twain shall never meet, if you will. It was actually easier to build the slave port than to try to create a single port that met the needs of both builds. I think, however, we have to be cautious about building slave ports for the reason you state (user confusion). Another thing that used to confuse me was the existence of multiple ports for the same software. For example, bash and bash2. It took me a while to realize that bash was the *current* version and bash2 was the *older* version. If you look, however, at the apache ports or the mysql ports, they always append the version number. This makes it easier for the user to understand, without having to do a great deal of research, what each port actually is. This, perhaps, is an area where standardization would benefit the community without creating undue rigidity. > I should also point out that I've had my arm twisted by users to support > things in my ports (particularly pine/alpine) that I cannot test for > myself (particularly maildir) and so I have done so with the caveat that > support for those features _must_ come from the community, or I'll rip > them out of the port the first time they break something. This method > also works. :) > >> 3) There's no standard for the format of pkg-plist, > > This has already been covered, but for the record you're wrong about > that. > Really? Some ports use PLIST_SUB and use those macros in pkg-plist. Others do not - they use the relative path entirely. I don't recall anything in the handbook that says you must or should use one or the other. Here again is an area where standardization might improve clarity. The use of unexec is also not clear. Should I go to the trouble of checking to see if the conf file has been altered and remove it if it hasn't been? Or should I just ignore it? I've done it both ways in my own ports. The handbook doesn't make it clear. >> pkg-message or >> pkg-descr, so port maintainers are free to put whatever they want in >> there. > > There are rough guidelines (portlint will prod you on both of those, > especially pkg-descr) but you're right, no hard and fast rules. I don't > remember the latin version, but there is a very old saying to the effect > that "the one doing the work gets to decide how the work gets done." > Guidelines are good here, cookie-cutter approaches don't scale to 18k+ > ports. > I'm not looking for a cookie cutter approach, but I think the use of "must", "should" and "may" in the docs would be helpful. For example, you "must" have a WWW: in pkg-descr if there is one available. You "should" create a brief description of what the port does. You "may" use a cut and paste of the vendor's explanation but be careful to make sure it isn't so generic that it doesn't make sense to FreeBSD users. >> There's a customary way of doing it, but it's not set in stone >> and variations are found throughout ports. > > You (pl) need to wrap your head around the fact that this is, and always > will be the status quo. If you want rigid rules, go create your own > ports system. > I don't want rigid rules. >> What's the limit on the number of files you can put in PLIST_FILES? >> Directories in PLIST_DIRS? Is there any requirement to use pkg-plist? > > Don't take this the wrong way, but why do you care? If you are asking > because you want to write a port, it's a reasonable question, and should > probably be given a more thorough treatment in the handbook. That's *precisely* why I'm asking. > However, > this precisely the kind of thing for which "community" takes on real > meaning. If you get confused by this, just send a message to the list. > "I am trying to port FUBAR-1.23, and I'm wondering if ...." and you will > generally get at least one answer. Hopefully if you get more than one, > they won't conflict. :) > I'm a big proponent of putting things that get asked repeatedly down in writing. Why should the community have to answer the same questions over and over again? (And yes, I know we will always have those who ask before reading, but a link to the appropriate answer saves the responder time and trains the user to go read first. >> When do you use @dirrm as opposed to @dirrmtry? > > That's an easy one. If the directory might have files in it from another > port, use the latter. If your port is the only one putting files in it, > the former. > Not as easy as you think. I maintain a port that creates files and directories. The first time the app is launched *new* files *and* directories are created in those directories - files and directories which have names that I can't possibly know at the time of port creation. So, if I use @dirrm, the port uninstalls correctly *if* (and only if) you build it and then deinstall it without ever running the daemon. OTOH, if you *do* run the daemon, the @dirrm will generate an error during deinstall. So it's not just other ports that can create this problem. >> How are conditionals handled in pkg-plist? > > PLIST_SUB. It's probably also worth noting here that a lot of these > questions can be answered by reading through at least the first part of > bsd.port.mk. It actually documents most of this stuff pretty well, and > the descriptions are generally kept well in synch with the code. > PLIST_SUB creates macros, not conditionals. I'm referring to if-then statements needed to conditionally remove files. WRT reading bsd.port.mk, I do this myself frequently, but I can assure you, as a non-programmer, it's not always clear what the right answer is. Sometimes it's quite unclear. > You also asked a question about the use of WWW: in pkg-descr. It's > encouraged, since the automated tools make use of it (e.g., see > http://www.freebsd.org/ports/ and bore down to some specific ports) but > not mandatory. > >> 4) There's no standard for config files. > > Someone else already answered this one for you. > Yes. The answer was that we really need to standardize. :-) > Finally, I'd like to make a suggestion for you to do more work. :) The > more time you spend on something (like ports) the harder it is for you > to "see" things through the eyes of a new user. This is doubly true for > writing documentation about it. I try to add useful stuff where I can, > but life would be really great if you could take the time to document > your questions more thoroughly, maybe with some collected answers, and > start hacking away at the current docs. That is my intent. But there's no way I'm going to "hack away" at the docs without first tapping the wisdom of the people on this list who have btdt longer than I have. I only maintain about 10 ports, and I consider myself a novice - especially compared to some who have been doing this much longer than I. > If you're not keen to learn the > SGML Well, not really, but I suspect I'll end up doing it anyway. > there are people who can help you with that, but coming up with > good content that covers the needs of people like you can (somewhat > ironically) be done most easily by people like you. I hope this is a > good start. I appreciate your input. Paul Schmehl (pauls@utdallas.edu) Senior Information Security Analyst The University of Texas at Dallas http://www.utdallas.edu/ir/security/
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?C65806EC3DF5B1A0EFA06B0E>