Mports Policies
If you are working on mports, you should define the MPORT_MAINTAINER_MODE variable in your make.conf.
The following are guidelines for the behavior and layout of a port. Any time a port is updated or created, it should be checked for compliance with these guidelines. Note that this is a living document that should be checked from time to time for changes.
PKGNAME
(Note that PKGNAME currently includes the version, which is unfortunate and an artifact from our FreeBSD roots. In time PKGNAME will be renamed, and PKGSUBNAME will renamed to PKGNAME.)
Every PKGSUBNAME must be unique. This is not currently the case in the tree, but work has begun on this front.
PORTREVISION
The PORTREVISION variable should only be incremented when there changes that will affect:
- Behaviors. (used to provide the foo widget, changed this to the bar widget).
- File locations (moved configuration file to $PREFIX/etc/ instead of $PREFIX/$PKGSUBNAME/etc)
- Dependencies up or down the chain. (some depend bumped a shared lib version, bump so that people will get the new version and link correctly).
- Other issuse at the port maintainer's discretion.
The following are not cause for incrementing the PORTREVISION:
- Fixing a broken port. Version numbers are for tracking packages, not ports.
- Setting the LICENSE variable
- Stylistic changes
PORTREVISION used to be bumped in more cases, due to the way that our cluster software used to work. The cluster now checks each port for each run.
LICENSE
Every port should define a LICENSE variable with a valid license. A list of valid licenses is printed by the license-list target. The LICENSE variable should immediately follow the COMMENT variable.
INSTALLS_SHLIB
No port should use the INSTALLS_SHLIB variable. Use USE_LDCONFIG instead.
MASTER_SITES
Every port should define at least 2 master sites.
OSVERSION
No port should use OSVERSION. Currently this refers to the FreeBSD version that MBSD branched from. This will not always be the case. Eventually this will refer to the MidnightBSD version. To facilitate this change, the old uses of OSVERSION must be removed.
Sub Files
If a file like pkg-message or pkg-install requires varible substitution, the SUB_FILES framework must be used. Do not hand roll your own.
Fake Cleanups
No port should run a pkg-install script, or display a package message. This should be left to pkg_add.
pkg-message format
The pkg-message file should be as simple in layout as possible. There should be no ascii art or lines. Eventually this message may be displayed in the GUI, do not assume that it merely needs to look good on the command line.
OPTIONS
Use OPTIONS if there are knobs, even if there is only one knob. The mport package system is going to be options aware, but it can't use the options if they aren't defined.
Man Pages
Very old FreeBSD ports do not use the MANX variables for man pages. Any such port should be changed to use the MANX variables. This is important so that package deletion will correctly remove the man pages.
pre-su-install
Now that su is not used in the fake process, the pre-su-install target is deprecated. Usually it can be moved to the pre-install target, but if it is doing anything with the plist the maintainer will need to use their judgement to determine the correct fix.
Old Variables
The following variables are no longer used (they are either totally deprecated, or needed by older FreeBSD versions):
- USE_GETOPT_LONG
- USE_REINPLACE
No port should use these variables
Interactive Scripts
No pkg-install or pkg-deinstall script should expect to run in an interactive envirement. They should not prompt the user or expect input from the user.
Plist and Echo
Don't expect to be able to echo things to the user from the plist during
a @exec or @unexec directive. It will work fine
with the old FreeBSD pkg_* tools, but the behavior is undefined under
libmport. The user might see what you have to say, it might not. If in
doubt use a pkg-install script or a pkg-message file.
pkg-req
Package requirement scripts are deprecated. There is only one such script at the moment and its function will be reimplemented under the mport package system.