Suggested improvements for ports

Paul Schmehl pauls at
Fri Jan 11 09:10:46 PST 2008

--On Friday, January 11, 2008 10:34:15 -0600 Scot Hetzel <swhetzel at> 

> n 1/11/08, Paul Schmehl <pauls at> 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:
> <descr>
> WWW: <projects web site>

What content goes in pkg-descr?  Is it required?  Optional?  Is WWW: required? 

> 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.


> 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/<portname>), 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 at
Senior Information Security Analyst
The University of Texas at Dallas

More information about the freebsd-ports mailing list