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).
The results of version number comparisons are not
always obvious. pkg_version(1) can be used to test
the comparison of two version number strings. The
pkgng equivalent is
pkg version -t
. For example:
%
pkg_version -t 0.031 0.29
>Or, for pkgng users:
%
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, 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:
PKGNAME
becomes
gtkmumble-0.10
.
A security hole is discovered which requires a local
FreeBSD patch. PORTREVISION
is bumped
accordingly.
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
).
PKGNAME
becomes
gtkmumble-0.2,1
The next release is 0.3. Since
PORTEPOCH
never decreases, the version
variables are now:
PKGNAME
becomes
gtkmumble-0.3,1
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.
format, not
yyyy
.mm
.dd
or the non-Y2K compliant
dd
.mm
.yyyy
format. It is important to prefix the version with
yy
.mm
.dd
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.
)
as the version.yyyy
.mm
.dd
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.