Suggested improvements for ports

[Scot Hetzel]

On 1/11/08, Paul Schmehl <pauls at utdallas.edu> wrote:
> --On Friday, January 11, 2008 10:34:15 -0600 Scot Hetzel <swhetzel at gmail.com>
> wrote:
>
> > n 1/11/08, Paul Schmehl <pauls at utdallas.edu> 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?)
>
The man page for pkg_create has some information on when to use
@unexec in your pkg-plist.  I have seen @exec/@unexec  for
installation/removal of configuration files, creation/deletion of
links and creation of empty directories.

The information on configuration files is in the porter's handbook:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/plist-config.html

You only delete configuration files when they are the same as the sample files.

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

According to the porter's handbook, it mentions when the port installs
a handfull of files.

http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/porting-desc.html#AEN99

When your using PLIST_FILES, PLIST_DIRS, there is no need to use
pkg-plist.  But if your port needs to use @dirrmtry, @exec, @unexec,
... then you should be using pkg-plist.

> When do you use @dirrm as opposed to @dirrmtry?  How are conditionals handled
> in pkg-plist?
>

You use @dirrm when only your port installs files into a directory
that it has created.   You use @dirrmtry when your port installs files
into a directory that was created by another port or another port
installs files into a directory that your port created.

> > 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?
> Optional?
>
This link tells you what is required in pkg-descr (pkg-descr is
required), it also explains when WWW: should be used.

http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/porting-desc.html#AEN85

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

pkg-message is optional.  It's use is to provide additional
information that needs to be done after the port has been installed
and couldn't be accomplished using the pkg-install script.

http://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/pkg-files.html#PORTING-MESSAGE

> >> 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/<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?
>
One of these two methods should be used for configuration files.  The
most common is the first one, especially when there is only a few
configuration files.

Scot