From owner-freebsd-ports@FreeBSD.ORG Fri Jan 11 17:10:46 2008 Return-Path: Delivered-To: freebsd-ports@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 61A3316A418 for ; Fri, 11 Jan 2008 17:10:46 +0000 (UTC) (envelope-from pauls@utdallas.edu) Received: from smtp3.utdallas.edu (smtp3.utdallas.edu [129.110.10.49]) by mx1.freebsd.org (Postfix) with ESMTP id 3647113C45A for ; Fri, 11 Jan 2008 17:10:46 +0000 (UTC) (envelope-from pauls@utdallas.edu) Received: from utd59514.utdallas.edu (utd59514.utdallas.edu [129.110.3.28]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp3.utdallas.edu (Postfix) with ESMTP id AC9886550A for ; Fri, 11 Jan 2008 11:10:45 -0600 (CST) Date: Fri, 11 Jan 2008 11:10:45 -0600 From: Paul Schmehl To: FreeBSD Ports Message-ID: In-Reply-To: <790a9fff0801110834s532a7282lf63061ad2b73acf5@mail.gmail.com> References: <790a9fff0801110834s532a7282lf63061ad2b73acf5@mail.gmail.com> X-Mailer: Mulberry/4.0.8 (Linux/x86) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit Content-Disposition: inline Subject: Re: Suggested improvements for ports 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: Fri, 11 Jan 2008 17:10:46 -0000 --On Friday, January 11, 2008 10:34:15 -0600 Scot Hetzel wrote: > n 1/11/08, Paul Schmehl wrote: >> Some of this has been discussed ad infinitum, but, in an off-list >> conversation, I came up with this list of suggested improvements for port. >> I'd like to see these things done, but I'm not sure how. Improve the docs? >> Create a checklist? >> > : >> 3) There's no standard for the format of pkg-plist, pkg-message or pkg-descr, >> so port maintainers are free to put whatever they want in there. There's a >> customary way of doing it, but it's not set in stone and variations are found >> throughout ports. > > There is a standard format for pkg-plist. Which is documented in the > port's handbook. > Is there a description of when to use unexec and when not to? Is there an explanation of what to do with conf files? (Do you leave them alone? Compare them to the sample file and delete only if they're the same? Delete always?) 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? When do you use @dirrm as opposed to @dirrmtry? How are conditionals handled in pkg-plist? > pkg-descr does have a standard format: > > > > WWW: > What content goes in pkg-descr? Is it required? Optional? Is WWW: required? Optional? > pkg-message format is left to the maintainer. > > The only requirement for pkg-descr and pkg-message is that it should > be able to display on an 80 column screen without the lines wrapping. > Yes, but is it required? Not required? What content goes in it? These are all questions left to the maintainer, and a brief analysis of ports shows a great deal of inconsistency in their usage. Many ports have no pkg-message at all. Is it optional? If an OPTION must be set on a dependency port, are you required to mention that in pkg-message? What information is required? What is optional? >> 4) There's no standard for config files. Do you overwrite? Do you ignore? >> Do you create port.conf-sample? port.conf-dist? port.conf-example? Do you >> check to see if port.conf is there, and, if not, copy it to ${LOCALBASE}/etc? >> ${PREFIX}/etc? > > There is a standard for config files, and is documented in the porters > handbook. > > The port maintainer should install configuration files so that they > don't overwrite existing configuration files. > And name them now? -sample? -dist? -example? -orig? And what about removal? When you deinstall the port, do you remove the conf file? Remove only if it's unaltered? Ignore it entirely? > The way that most ports take is by patching the src to install the > standard config files with an extension (currently we use -sample, > -dist, -orig, or -example). Then the port should check for the > existance of the config file, and install one if it doesn't exist. > When the port is uninstalled, it compares the config file with the > default config file, and only removes the config file if they are the > same. > > NOTE: should standardize a default extension. > Precisely. > When there are a large number of configuration files, a few ports > install the default configuration files into an alternate directory > (i.e PREFIX/share/example/), and then copy them to > PREFIX/etc when they don't exist. On deinstall, they compare the > config file with the default config file, and only remove the config > files if they are the same. > Is this how it should always be done? This is my point. On many of these criteria there is an uncomfortable amount of "squishyness" so that port maintainers, *especially* new ones, are unsure what the "right" thing to do is. The porters handbook seems written from the standpoint of a guide more than a manual. IOW, it advises rather than instructs. I think that needs to change, because it would bring more consistency to bear on ports and eliminate some of the questions that get repeatedly asked because folks are unsure of the answer. -- Paul Schmehl (pauls@utdallas.edu) Senior Information Security Analyst The University of Texas at Dallas http://www.utdallas.edu/ir/security/