5.2. Naming

5.2. Naming
Prev	Chapter 5. Configuring the Makefile	Next

The first part of the port's Makefile names the port, describes its version number, and lists it in the correct category.

5.2.1. `PORTNAME`

Set PORTNAME to the base name of the software. It is used as the base for the FreeBSD package, and for DISTNAME.

Important:

The package name must be unique across the entire ports tree. Make sure that the PORTNAME is not already in use by an existing port, and that no other port already has the same PKGBASE. If the name has already been used, add either PKGNAMEPREFIX or PKGNAMESUFFIX.

5.2.2. Versions, `DISTVERSION` or `PORTVERSION`

Set DISTVERSION to the version number of the software.

PORTVERSION is the version used for the FreeBSD package. It will be automatically derived from DISTVERSION to be compatible with FreeBSD's package versioning scheme. If the version contains letters, it might be needed to set PORTVERSION and not DISTVERSION.

Important:

Only one of PORTVERSION and DISTVERSION can be set at a time.

From time to time, some software will use a version scheme that is not compatible with how DISTVERSION translates in PORTVERSION.

Tip:

When updating a port, it is possible to use pkg-version(8)'s -t argument to check if the new version is greater or lesser than before. See Example 5.1, “Using pkg-version(8) to Compare Versions.”.

Example 5.1. Using pkg-version(8) to Compare Versions.

pkg version -t takes two versions as arguments, it will respond with <, = or > if the first version is less, equal, or more than the second version, respectively.

% pkg version -t 1.2 1.3
< 
% pkg version -t 1.2 1.2
= 
% pkg version -t 1.2 1.2.0
= 
% pkg version -t 1.2 1.2.p1
> 
% pkg version -t 1.2.a1 1.2.b1
< 
% pkg version -t 1.2 1.2p1
<

	`1.2` is before `1.3`.
	`1.2` and `1.2` are equal as they have the same version.
	`1.2` and `1.2.0` are equal as nothing equals zero.
	`1.2` is after `1.2.p1` as `.p1`, think “pre-release 1”.
	`1.2.a1` is before `1.2.b1`, think “alpha” and “beta”, and `a` is before `b`.
	`1.2` is before `1.2p1` as `2p1`, think “2, patch level 1” which is a version after any `2.X` but before `3`.

Note:

In here, the a, b, and p are used as if meaning “alpha”, “beta” or “pre-release” and “patch level”, but they are only letters and are sorted alphabetically, so any letter can be used, and they will be sorted appropriately.

Table 5.1. Examples of DISTVERSION and the Derived PORTVERSION

`DISTVERSION`	`PORTVERSION`
0.7.1d	0.7.1.d
10Alpha3	10.a3
3Beta7-pre2	3.b7.p2
8:f_17	8f.17

Example 5.2. Using DISTVERSION

When the version only contains numbers separated by dots, dashes or underscores, use DISTVERSION.

PORTNAME=   nekoto
DISTVERSION=	1.2-4

It will generate a PORTVERSION of 1.2.4.

Example 5.3. Using DISTVERSION When the Version Starts with a Letter or a Prefix

When the version starts or ends with a letter, or a prefix or a suffix that is not part of the version, use DISTVERSIONPREFIX, DISTVERSION, and DISTVERSIONSUFFIX.

If the version is v1.2-4:

PORTNAME=   nekoto
DISTVERSIONPREFIX=  v
DISTVERSION=	1_2_4

Some of the time, projects using GitHub will use their name in their versions. For example, the version could be nekoto-1.2-4:

PORTNAME=   nekoto
DISTVERSIONPREFIX=  nekoto-
DISTVERSION=	1.2_4

Those projects also sometimes use some string at the end of the version, for example, 1.2-4_RELEASE:

PORTNAME=   nekoto
DISTVERSION=	1.2-4
DISTVERSIONSUFFIX=  _RELEASE

Or they do both, for example, nekoto-1.2-4_RELEASE:

PORTNAME=   nekoto
DISTVERSIONPREFIX=  nekoto-
DISTVERSION=	1.2-4
DISTVERSIONSUFFIX=  _RELEASE

DISTVERSIONPREFIX and DISTVERSIONSUFFIX will not be used while constructing PORTVERSION, but only used in DISTNAME.

All will generate a PORTVERSION of 1.2.4.

Example 5.4. Using DISTVERSION When the Version Contains Letters Meaning “alpha”, “beta”, or “pre-release”

When the version contains numbers separated by dots, dashes or underscores, and letters are used to mean “alpha”, “beta” or “pre-release”, which is, before the version without the letters, use DISTVERSION.

PORTNAME=   nekoto
DISTVERSION=	1.2-pre4

PORTNAME=   nekoto
DISTVERSION=	1.2p4

Both will generate a PORTVERSION of 1.2.p4 which is before than 1.2. pkg-version(8) can be used to check that fact:

% pkg version -t 1.2.p4 1.2
<

Example 5.5. Not Using DISTVERSION When the Version Contains Letters Meaning "Patch Level"

When the version contains letters that are not meant as “alpha”, “beta”, or “pre”, but more in a “patch level”, and meaning after the version without the letters, use PORTVERSION.

PORTNAME=   nekoto
PORTVERSION=	1.2p4

In this case, using DISTVERSION is not possible because it would generate a version of 1.2.p4 which would be before 1.2 and not after. pkg-version(8) will verify this:

% pkg version -t 1.2 1.2.p4
> 
% pkg version -t 1.2 1.2p4
<

	`1.2` is after `1.2.p4`, which is wrong in this case.
	`1.2` is before `1.2p4`, which is what was needed.

For some more advanced examples of setting PORTVERSION, when the software's versioning is really not compatible with FreeBSD's, or DISTNAME when the distribution file does not contain the version itself, see Section 5.4.1, “DISTNAME”.

5.2.3. `PORTREVISION` and `PORTEPOCH`

5.2.3.1. `PORTREVISION`

PORTREVISION is a monotonically increasing value which is reset to 0 with every increase of DISTVERSION, typically every time there is a new official vendor release. If PORTREVISION is non-zero, the value is appended to the package name. Changes to PORTREVISION are used by automated tools like pkg-version(8) to determine that a new package is available.

PORTREVISION must be increased each time a change is made to the port that changes the generated package in any way. That includes changes that only affect a package built with non-default options.

Examples of when PORTREVISION must 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. For example, a change to a script which generates initial data for the package, like ssh(1) 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. For example, changes to the distfile requiring a correction to distinfo with no corresponding change to DISTVERSION, 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 have to 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 decide whether a change committed to a port is something which some people would benefit from having. Either because of an enhancement, fix, or by virtue that the new package will actually work at all. Then weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, PORTREVISION must be bumped.

Note:

People using binary packages will never see the update if PORTREVISION is not bumped. Without increasing PORTREVISION, the package builders have no way to detect the change and thus, will not rebuild the package.

5.2.3.2. `PORTEPOCH`

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

Tip:

The results of version number comparisons are not always obvious. pkg version (see pkg-version(8)) can be used to test the comparison of two version number strings. For example:

% pkg version -t 0.031 0.29
>

The > output indicates that version 0.031 is considered greater than version 0.29, which may not have been obvious to the porter.

In situations such as this, PORTEPOCH must 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. For example, the package would not be detected as out of date. The new version number, 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 the discussion above was not clear enough, please consult the FreeBSD ports mailing list.

It is expected that PORTEPOCH will not be used for the majority of ports, and that sensible use of DISTVERSION, or that use PORTVERSION carefully, can often preempt it becoming necessary if a future release of the software changes 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, do not use 20000917 for DISTVERSION. The correct way is a DISTVERSION of 1.2.20000917, or similar, so that the succeeding release, say 1.3, is still a numerically greater value.

5.2.3.3. Example of `PORTREVISION` and `PORTEPOCH` Usage

The gtkmumble port, version 0.10, is committed to the ports collection:

PORTNAME=	gtkmumble
DISTVERSION=	0.10

PKGNAME becomes gtkmumble-0.10.

A security hole is discovered which requires a local FreeBSD patch. PORTREVISION is bumped accordingly.

PORTNAME=	gtkmumble
DISTVERSION=	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, 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
DISTVERSION=	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
DISTVERSION=	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.

5.2.4. `PKGNAMEPREFIX` and `PKGNAMESUFFIX`

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, the use of a hyphen (-) in PORTVERSION is not allowed. 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.

5.2.5. Package Naming Conventions

These are the conventions to follow when naming packages. This is to make the package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes!

Package names take the form of 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.

language_region-

FreeBSD strives to support the native language of its users. The language- part is a two letter abbreviation of the natural language defined by ISO-639 when 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 is set in PKGNAMEPREFIX.

name

Make sure that the port's name and version are clearly separated and placed into PORTNAME and DISTVERSION. 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, PORTNAME cannot 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 PKGNAMEPREFIX and PKGNAMESUFFIX values.

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.

-compiled.specifics

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 states the compiled-in defaults. The hyphen is optional. Examples are paper size and font units.

The -compiled.specifics part is set in PKGNAMESUFFIX.

-version.numbers

The version string follows a dash (-) and is 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 follow the single alphabet without an extra period between them (for example, 1.0b2).

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 dyyyy.mm.dd format, not dd.mm.yyyy or the non-Y2K compliant yy.mm.dd format. It is important to prefix the version with a letter, here d (for date), in case a release with an actual version number is made, which would be numerically less than yyyy.

Important:

Package name must be unique among all of the ports tree, check that there is not already a port with the same PORTNAME and if there is add one of PKGNAMEPREFIX or PKGNAMESUFFIX.

Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name, for each line, only one of DISTVERSION or PORTVERSION is set in, depending on which would be used in the port's Makefile:

Table 5.2. Package Naming Examples

Distribution Name	`PKGNAMEPREFIX`	`PORTNAME`	`PKGNAMESUFFIX`	`DISTVERSION`	`PORTVERSION`	Reason or comment
mule-2.2.2	(empty)	mule	(empty)	2.2.2		No changes required
mule-1.0.1	(empty)	mule	1	1.0.1		This is version 1 of mule, and version 2 already exists
EmiClock-1.0.2	(empty)	emiclock	(empty)	1.0.2		No uppercase names for single programs
rdist-1.3alpha	(empty)	rdist	(empty)	1.3alpha		Version will be `1.3.a`
es-0.9-beta1	(empty)	es	(empty)	0.9-beta1		Version will be `0.9.b1`
mailman-2.0rc3	(empty)	mailman	(empty)	2.0rc3		Version will be `2.0.r3`
v3.3beta021.src	(empty)	tiff	(empty)		3.3	What the heck was that anyway?
tvtwm	(empty)	tvtwm	(empty)		p11	No version in the filename, use what upstream says it is
piewm	(empty)	piewm	(empty)	1.0		No version in the filename, use what upstream says it is
xvgr-2.10pl1	(empty)	xvgr	(empty)		2.10.pl1	In that case, `pl1` means patch level, so using DISTVERSION is not possible.
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 the source file was released on (dyyyy.mm.dd, or dyyyymmdd) as the version.

Tip:

Use any letter. Here, d here stands for date, if the source is a Git repository, g followed by the commit date is commonly used, using s for snapshot is also common.

5.2. Naming

5.2.1. PORTNAME

Important:

5.2.2. Versions, DISTVERSION or PORTVERSION

Important:

Tip:

Note:

5.2.3. PORTREVISION and PORTEPOCH

5.2.3.1. PORTREVISION

Note:

5.2.3.2. PORTEPOCH

Tip:

5.2.3.3. Example of PORTREVISION and PORTEPOCH Usage

Note:

5.2.4. PKGNAMEPREFIX and PKGNAMESUFFIX

5.2.5. Package Naming Conventions

Important:

Tip:

5.2.1. `PORTNAME`

5.2.2. Versions, `DISTVERSION` or `PORTVERSION`

5.2.3. `PORTREVISION` and `PORTEPOCH`

5.2.3.1. `PORTREVISION`

5.2.3.2. `PORTEPOCH`

5.2.3.3. Example of `PORTREVISION` and `PORTEPOCH` Usage

5.2.4. `PKGNAMEPREFIX` and `PKGNAMESUFFIX`