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 pre-empt
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
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.
在某些情況,可能會同時存在有不同版本的同一程式。
由於它們可能會有同樣的 PORTNAME、
PKGNAMEPREFIX,甚至
PKGNAMESUFFIX 也相同,所以得讓這些程式有所不同,
才能讓 port 的 index 以及 package 能順利產生。 遇到這類情況,
the optional LATEST_LINK variable should be set to
a different value for all ports except the “main”
one —— see the editors/vim5 and
editors/vim ports, and the
www/apache* family for examples of its use.
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
papersize 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
yyyy.mm.dd
format, not
dd.mm.yyyy
or the non-Y2K compliant
yy.mm.dd
format.
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 | Papersize 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
(yyyy.mm.dd)
as the version.
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>.