5.2.Â Naming

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, DISTVERSIONorPORTVERSION

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.

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:

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.