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