The first part of the port's Makefile names the port, describes its version number, and lists it in the correct category.
You should set PORTNAME to the base name of your port, and PORTVERSION to the version number of the port.
The PORTREVISION variable is a monotonically increasing value which is reset to 0 with every increase of PORTVERSION (i.e., every time a new official vendor release is made), and appended to the package name if non-zero. Changes to PORTREVISION are used by automated tools (e.g., pkg_version(1)) to highlight the fact that a new package is available.
PORTREVISION should be increased each time a change is made to the port which significantly affects the content or structure of the derived package.
Examples of when PORTREVISION should be bumped:
Addition of patches to correct security vulnerabilities, bugs, or to add new functionality to the port.
Changes to the port Makefile to enable or disable compile-time options in the package.
Changes in the packing list or the install-time behavior of the package (e.g., change to a script which generates initial data for the package, like ssh host keys).
Version bump of a port's shared library dependency (in this case, someone trying to install the old package after installing a newer version of the dependency will fail since it will look for the old libfoo.x instead of libfoo.(x+1)).
Silent changes to the port distfile which have significant functional differences, i.e., changes to the distfile requiring a correction to distinfo with no corresponding change to PORTVERSION, where a diff -ru of the old and new versions shows non-trivial changes to the code.
Examples of changes which do not require a PORTREVISION bump:
Style changes to the port skeleton with no functional change to what appears in the resulting package.
Changes to MASTER_SITES or other functional changes to the port which do not affect the resulting package.
Trivial patches to the distfile such as correction of typos, which are not important enough that users of the package should go to the trouble of upgrading.
Build fixes which cause a package to become compilable where it was previously failing (as long as the changes do not introduce any functional change on any other platforms on which the port did previously build). Since PORTREVISION reflects the content of the package, if the package was not previously buildable then there is no need to increase PORTREVISION to mark a change.
A rule of thumb is to ask yourself whether a change committed to a port is something which everyone would benefit from having (either because of an enhancement, fix, or by virtue that the new package will actually work at all), and weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, the PORTREVISION should be bumped.
From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1).
In situations such as this, the PORTEPOCH version should be increased. If PORTEPOCH is nonzero it is appended to the package name as described in section 0 above. PORTEPOCH must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail (i.e., the package would not be detected as out of date): the new version number (e.g., 1.0,1 in the above example) is still numerically less than the previous version (20000801), but the ,1 suffix is treated specially by automated tools and found to be greater than the implied suffix ,0 on the earlier package.
Dropping or resetting PORTEPOCH incorrectly leads to no end of grief; if you do not understand the above discussion, please keep after it until you do, or ask questions on the mailing lists.
It is expected that PORTEPOCH will not be used for the majority of ports, and that sensible use of PORTVERSION can often preempt it becoming necessary if a future release of the software should change the version structure. However, care is needed by FreeBSD porters when a vendor release is made without an official version number — such as a code ``snapshot'' release. The temptation is to label the release with the release date, which will cause problems as in the example above when a new ``official'' release is made.
For example, if a snapshot release is made on the date 20000917, and the previous version of the software was version 1.2, the snapshot release should be given a PORTVERSION of 1.2.20000917 or similar, not 20000917, so that the succeeding release, say 1.3, is still a numerically greater value.
The gtkmumble port, version 0.10, is committed to the ports collection:
PORTNAME= gtkmumble PORTVERSION= 0.10
PKGNAME becomes gtkmumble-0.10.
A security hole is discovered which requires a local FreeBSD patch. PORTREVISION is bumped accordingly.
PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1
PKGNAME becomes gtkmumble-0.10_1
A new version is released by the vendor, numbered 0.2 (it turns out the author actually intended 0.10 to actually mean 0.1.0, not ``what comes after 0.9'' - oops, too late now). Since the new minor version 2 is numerically less than the previous version 10, the PORTEPOCH must be bumped to manually force the new package to be detected as ``newer''. Since it is a new vendor release of the code, PORTREVISION is reset to 0 (or removed from the Makefile).
PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1
PKGNAME becomes gtkmumble-0.2,1
The next release is 0.3. Since PORTEPOCH never decreases, the version variables are now:
PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1
PKGNAME becomes gtkmumble-0.3,1
Note: If PORTEPOCH were reset to 0 with this upgrade, someone who had installed the gtkmumble-0.10_1 package would not detect the gtkmumble-0.3 package as newer, since 3 is still numerically less than 10. Remember, this is the whole point of PORTEPOCH in the first place.
Two optional variables, PKGNAMEPREFIX and PKGNAMESUFFIX, are combined with PORTNAME and PORTVERSION to form PKGNAME as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure this conforms to our guidelines for a good package name. In particular, you are not allowed to use a hyphen (-) in PORTVERSION. Also, if the package name has the language- or the -compiled.specifics part (see below), use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME.
LATEST_LINK is used during package building to determine a shortened name to create links that can be used by pkg_add -r. This makes it possible to, for example, install the latest perl version by running pkg_add -r perl without knowing the exact version number. This name needs to be unique and obvious to users.
In some cases, several versions of a program may be present in the ports collection at the same time. Both the index build and the package build system need to be able to see them as different, independent ports, although they may all have the same PORTNAME, PKGNAMEPREFIX, and even PKGNAMESUFFIX. In those cases, the optional LATEST_LINK variable should be set to a different value for all ports except the ``main'' one — see the lang/gcc46 and lang/gcc ports, and the www/apache* family for examples of its use. By setting NO_LATEST_LINK, no link will be generated, which may be an option for all but the ``main'' version. Note that how to choose a ``main'' version — ``most popular'', ``best supported'', ``least patched'', and so on — is outside the scope of this handbook's recommendations; we only tell you how to specify the other ports' versions after you have picked a ``main'' one.
The following are the conventions you should follow in naming your packages. This is to have our package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes!
The package name should look like [language[_region]]-name[[-]compiled.specifics]-version.numbers.
The package name is defined as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure to set the variables to conform to that format.
FreeBSD strives to support the native language of its users. The language- part should be a two letter abbreviation of the natural language defined by ISO-639 if the port is specific to a certain language. Examples are ja for Japanese, ru for Russian, vi for Vietnamese, zh for Chinese, ko for Korean and de for German.
If the port is specific to a certain region within the language area, add the two letter country code as well. Examples are en_US for US English and fr_CH for Swiss French.
The language- part should be set in the PKGNAMEPREFIX variable.
The first letter of the name part should be lowercase. (The rest of the name may contain capital letters, so use your own discretion when you are converting a software name that has some capital letters in it.) There is a tradition of naming Perl 5 modules by prepending p5- and converting the double-colon separator to a hyphen; for example, the Data::Dumper module becomes p5-Data-Dumper.
Make sure that the port's name and version are clearly separated and placed into the PORTNAME and PORTVERSION variables. The only reason for PORTNAME to contain a version part is if the upstream distribution is really named that way, as in the textproc/libxml2 or japanese/kinput2-freewnn ports. Otherwise, the PORTNAME should not contain any version-specific information. It is quite normal for several ports to have the same PORTNAME, as the www/apache* ports do; in that case, different versions (and different index entries) are distinguished by the PKGNAMEPREFIX, PKGNAMESUFFIX, and LATEST_LINK values.
If the port can be built with different hardcoded defaults (usually part of the directory name in a family of ports), the -compiled.specifics part should state the compiled-in defaults (the hyphen is optional). Examples are paper size and font units.
The -compiled.specifics part should be set in the PKGNAMESUFFIX variable.
The version string should follow a dash (-) and be a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string pl (meaning ``patchlevel''), which can be used only when there are no major and minor version numbers in the software. If the software version has strings like ``alpha'', ``beta'', ``rc'', or ``pre'', take the first letter and put it immediately after a period. If the version string continues after those names, the numbers should follow the single alphabet without an extra period between them.
The idea is to make it easier to sort ports by looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the 0.0.yyyy.mm.dd format, not dd.mm.yyyy or the non-Y2K compliant yy.mm.dd format. It is important to prefix the version with 0.0. in case a release with an actual version number is made, which would of course be numerically less than yyyy.
Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name:
| Distribution Name | PKGNAMEPREFIX | PORTNAME | PKGNAMESUFFIX | PORTVERSION | Reason |
|---|---|---|---|---|---|
| mule-2.2.2 | (empty) | mule | (empty) | 2.2.2 | No changes required |
| EmiClock-1.0.2 | (empty) | emiclock | (empty) | 1.0.2 | No uppercase names for single programs |
| rdist-1.3alpha | (empty) | rdist | (empty) | 1.3.a | No strings like alpha allowed |
| es-0.9-beta1 | (empty) | es | (empty) | 0.9.b1 | No strings like beta allowed |
| mailman-2.0rc3 | (empty) | mailman | (empty) | 2.0.r3 | No strings like rc allowed |
| v3.3beta021.src | (empty) | tiff | (empty) | 3.3 | What the heck was that anyway? |
| tvtwm | (empty) | tvtwm | (empty) | pl11 | Version string always required |
| piewm | (empty) | piewm | (empty) | 1.0 | Version string always required |
| xvgr-2.10pl1 | (empty) | xvgr | (empty) | 2.10.1 | pl allowed only when no major/minor version numbers |
| gawk-2.15.6 | ja- | gawk | (empty) | 2.15.6 | Japanese language version |
| psutils-1.13 | (empty) | psutils | -letter | 1.13 | Paper size hardcoded at package build time |
| pkfonts | (empty) | pkfonts | 300 | 1.0 | Package for 300dpi fonts |
If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to 1.0 (like the piewm example above). Otherwise, ask the original author or use the date string (0.0.yyyy.mm.dd) as the version.