5.2. Naming
Prev | Chapter 5. Configuring the Makefile | Next

## 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` and `PORTVERSION`

You should set `PORTNAME` to the base name of your port, and `PORTVERSION` to the version number of the port.

### 5.2.2. `PORTREVISION` and `PORTEPOCH`

#### 5.2.2.1. `PORTREVISION`

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.

#### 5.2.2.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(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.

#### 5.2.2.3. Example of `PORTREVISION` and `PORTEPOCH` Usage

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`

### 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.3. `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, 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`.

### 5.2.4. `LATEST_LINK`

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

### 5.2.5. Package Naming Conventions

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.

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

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

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

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

5. 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.`yyyy`.`mm`.`dd`` format, not ``dd`.`mm`.`yyyy`` or the non-Y2K compliant ``yy`.`mm`.`dd`` format. It is important to prefix the version with `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.`yyyy`.`mm`.`dd``) as the version.

Prev | Up | Next
Chapter 5. Configuring the Makefile | Home | 5.3. Categorization

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.