# FreeBSD Porter's Handbook

The FreeBSD Documentation Project
April 2000
2000
2001
2002
2003
2004
2005
The FreeBSD Documentation Project

&bookinfo.trademarks;

&bookinfo.legalnotice;

## Introduction

The FreeBSD ports collection is the way almost everyone installs applications ("ports") on FreeBSD. Like everything else about FreeBSD, it is primarily a volunteer effort. It is important to keep this in mind when reading this document.

In FreeBSD, anyone may submit a new port, or volunteer to maintain an existing port if it is unmaintained—you do not need any special commit privileges to do so.

## Making a port yourself

So, you are interested in making your own port or upgrading an existing one? Great!

What follows are some guidelines for creating a new port for FreeBSD. If you want to upgrade an existing port, you should read this and then read .

When this document is not sufficiently detailed, you should refer to `/usr/ports/Mk/bsd.port.mk`, which all port Makefiles include. Even if you do not hack Makefiles daily, it is well commented, and you will still gain much knowledge from it. Additionally, you may send specific questions to the &a.ports;.

Only a fraction of the variables (VAR) that can be overridden are mentioned in this document. Most (if not all) are documented at the start of `/usr/ports/Mk/bsd.port.mk`; the others probably ought to be. Note that this file uses a non-standard tab setting: Emacs and Vim should recognize the setting on loading the file. Both &man.vi.1; and &man.ex.1; can be set to use the correct value by typing `:set tabstop=4` once the file has been loaded.

## Quick Porting

This section tells you how to do a quick port. In many cases, it is not sufficient, so you will have to read further on into the document.

First, get the original tarball and put it into DISTDIR, which defaults to `/usr/ports/distfiles`.

The following assumes that the software compiled out-of-the-box, i.e., there was absolutely no change required for the port to work on your FreeBSD box. If you needed to change something, you will have to refer to the next section too.

### Writing the `Makefile`

The minimal `Makefile` would look something like this:

    # New ports collection makefile for:   oneko
    # Date created:        5 December 1994
    # Whom:                asami
    #
    # &dollar;FreeBSD&dollar;
    #

    PORTNAME=      oneko
    PORTVERSION=   1.1b
    CATEGORIES=    games
    MASTER_SITES=  ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

    MAINTAINER=    asami@FreeBSD.org
    COMMENT=       A cat chasing a mouse all over the screen

    MAN1=          oneko.1
    MANCOMPRESSED= yes
    USE_IMAKE=     yes

    .include <bsd.port.mk>

See if you can figure it out. Do not worry about the contents of the `&dollar;FreeBSD&dollar;` line, it will be filled in automatically by CVS when the port is imported to our main ports tree. You can find a more detailed example in the sample Makefile section.

### Writing the description files

There are two description files that are required for any port, whether they actually package or not. They are `pkg-descr` and `pkg-plist`. Their `pkg-` prefix distinguishes them from other files.

#### `pkg-descr`

This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient.

This is not a manual or an in-depth description on how to use or compile the port! Please be careful if you are copying from the `README` or manpage; too often they are not a concise description of the port or are in an awkward format (e.g., manpages have justified spacing). If the ported software has an official WWW homepage, you should list it here. Prefix one of the websites with `WWW:` so that automated tools will work correctly.

It is recommended that you sign your name at the end of this file, as in:

    This is a port of oneko, in which a cat chases a poor mouse all over
    the screen.
     :
    (etc.)

    WWW: http://www.oneko.org/

    - Satoshi
    asami@cs.berkeley.edu

#### `pkg-plist`

This file lists all the files installed by the port. It is also called the packing list because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually `/usr/local` or `/usr/X11R6`). If you are using the MANn variables (as you should be), do not list any manpages here.

Here is a small example:

    bin/oneko
    lib/X11/app-defaults/Oneko
    lib/X11/oneko/cat1.xpm
    lib/X11/oneko/cat2.xpm
    lib/X11/oneko/mouse.xpm
    @dirrm lib/X11/oneko

Refer to the &man.pkg.create.1; manual page for details on the packing list.

You should list all the files, but not the name directories, in the list. Also, if the port creates directories for itself during installation, make sure to add `@dirrm` lines as necessary to remove them when the port is deleted.

It is recommended that you keep all the filenames in this file sorted alphabetically. It will make verifying the changes when you upgrade the port much easier.

Creating a packing list manually can be a very tedious task. If the port installs a large numbers of files, creating the packing list automatically might save time.

There is only one case when `pkg-plist` can be omitted from a port. If the port installs just a handful of files, and perhaps directories, the files and directories may be listed in the variables PLIST_FILES and PLIST_DIRS, respectively, within the port's `Makefile`. For instance, we could get along without `pkg-plist` in the above `oneko` port by adding the following lines to the `Makefile`:

    PLIST_FILES=    bin/oneko \
                    lib/X11/app-defaults/Oneko \
                    lib/X11/oneko/cat1.xpm \
                    lib/X11/oneko/cat2.xpm \
                    lib/X11/oneko/mouse.xpm
    PLIST_DIRS=     lib/X11/oneko

Of course, PLIST_DIRS should be left unset if a port installs no directories of its own.

The price for this way of listing port's files and directories is that you cannot use command sequences described in &man.pkg.create.1;. Therefore, it is suitable only for simple ports and makes them even simpler. At the same time, it has the advantage of reducing the number of files in the ports collection. Please consider using this technique before you resort to `pkg-plist`.

Later we will see how `pkg-plist` and PLIST_FILES can be used to fulfil more sophisticated tasks.

### Creating the checksum file

Just type `make makesum`. The ports make rules will automatically generate the file `distinfo`.

If a file fetched has its checksum changed regularly and you are certain the source is trusted (i.e. it comes from manufacturer CDs or documentation generated daily), you should specify these files in the IGNOREFILES variable. Then the checksum is not calculated for that file when you run `make makesum`, but set to `IGNORE`.

### Testing the port

You should make sure that the port rules do exactly what you want them to do, including packaging up the port. These are the important points you need to verify.

- `pkg-plist` does not contain anything not installed by your port

- `pkg-plist` contains everything that is installed by your port

- Your port can be installed multiple times using the reinstall target

- Your port cleans up after itself upon deinstall

#### Recommended test ordering

1. `make install`

2. `make package`

3. `make deinstall`

4. `pkg_add package-name`

5. `make deinstall`

6. `make reinstall`

7. `make package`

Make sure that there are not any warnings issued in any of the package and deinstall stages. After step 3, check to see if all the new directories are correctly deleted. Also, try using the software after step 4, to ensure that it works correctly when installed from a package.

### Checking your port with `portlint`

Please use `portlint` to see if your port conforms to our guidelines. The `portlint` program is part of the ports collection. In particular, you may want to check if the Makefile is in the right shape and the package is named appropriately.

### Submitting the port

First, make sure you have read the DOs and DON'Ts section.

Now that you are happy with your port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too. We do not need your `work` directory or the `pkgname.tgz` package, so delete them now. Next, simply include the output of `shar `find port_dir`` in a bug report and send it with the &man.send-pr.1; program (see Bug Reports and General Commentary for more information about &man.send-pr.1;). If the uncompressed port is larger than 20KB, you should compress it into a tarfile and use &man.uuencode.1; before including it in the bug report (uuencoded tarfiles are acceptable even if the bug report is smaller than 20KB but are not preferred). Be sure to classify the bug report as category `ports` and class `change-request` (Do not mark the report `confidential`!). Also add a short description of the program you ported to the Description field of the PR and the shar or uuencoded tarfile to the Fix field.

You can make our work a lot easier, if you use a good description in the synopsis of the problem report. We prefer something like New port: <category>/<portname> <short description of the port> for new ports and Update port: <category>/<portname> <short description of the update> for port updates. If you stick to this scheme, the chance that someone will take a look at your PR soon is much better.

One more time, do not include the original source distfile, the `work` directory, or the package you built with `make package`.

After you have submitted your port, please be patient. Sometimes it can take a few months before a port is included in FreeBSD, although it might only take a few days. You can view the list of ports waiting to be committed to FreeBSD.

Once we have looked at your port, we will get back to you if necessary, and put it in the tree. Your name will also appear in the list of Additional FreeBSD Contributors and other files. Isn't that great?!? :-)

## Slow Porting

Ok, so it was not that simple, and the port required some modifications to get it to work. In this section, we will explain, step by step, how to modify it to get it to work with the ports paradigm.

### How things work

First, this is the sequence of events which occurs when the user first types `make` in your port's directory. You may find that having `bsd.port.mk` in another window while you read this really helps to understand it.

But do not worry if you do not really understand what `bsd.port.mk` is doing, not many people do... :->

1. The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in DISTDIR. If fetch cannot find the required files in DISTDIR it will look up the URL MASTER_SITES, which is set in the Makefile, as well as our main FTP site at , where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with FETCH, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in DISTDIR for future use and proceed.

2. The extract target is run. It looks for your port's distribution file (typically a gzip'd tarball) in DISTDIR and unpacks it into a temporary subdirectory specified by WRKDIR (defaults to `work`).

3. The patch target is run. First, any patches defined in PATCHFILES are applied. Second, if any patch files named `patch-*` are found in PATCHDIR (defaults to the `files` subdirectory), they are applied at this time in alphabetical order.

4. The configure target is run. This can do any one of many different things.

   1. If it exists, `scripts/configure` is run.

   2. If HAS_CONFIGURE or GNU_CONFIGURE is set, `WRKSRC/configure` is run.

   3. If USE_IMAKE is set, XMKMF (default: `xmkmf -a`) is run.

5. The build target is run. This is responsible for descending into the port's private working directory (WRKSRC) and building it. If USE_GMAKE is set, GNU `make` will be used, otherwise the system `make` will be used.

The above are the default actions. In addition, you can define targets pre-something or post-something, or put scripts with those names, in the `scripts` subdirectory, and they will be run before or after the default actions are done.

For example, if you have a post-extract target defined in your `Makefile`, and a file `pre-build` in the `scripts` subdirectory, the post-extract target will be called after the regular extraction actions, and the `pre-build` script will be executed before the default build rules are done. It is recommended that you use `Makefile` targets if the actions are simple enough, because it will be easier for someone to figure out what kind of non-default action the port requires.

The default actions are done by the `bsd.port.mk` targets do-something. For example, the commands to extract a port are in the target do-extract. If you are not happy with the default target, you can fix it by redefining the do-something target in your `Makefile`.

The main targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one are completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix do-extract, but never ever change the way extract operates!

Now that you understand what goes on when the user types `make`, let us go through the recommended steps to create the perfect port.

### Getting the original sources

Get the original sources (normally) as a compressed tarball (`foo.tar.gz` or `foo.tar.Z`) and copy it into DISTDIR. Always use mainstream sources when and where you can.

You will need to set the variable MASTER_SITES to reflect where the original tarball resides. You will find convenient shorthand definitions for most mainstream sites in `bsd.sites.mk`. Please use these sites—and the associated definitions—if at all possible, to help avoid the problem of having the same information repeated over again many times in the source base. As these sites tend to change over time, this becomes a maintenance nightmare for everyone involved.

If you cannot find a FTP/HTTP site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, you might want to put a copy on a reliable FTP or HTTP server that you control (e.g., your home page).

If you cannot find somewhere convenient and reliable to put the distfile we can house it ourselves on ftp.FreeBSD.org; however, this is the least-preferred solution. The distfile must be placed into `~/public_distfiles/` of someone's freefall account. Ask the person who commits your port to do this. This person will also set MASTER_SITES to MASTER_SITE_LOCAL and MASTER_SITE_SUBDIR to their freefall username.

If your port's distfile changes all the time without any kind of version update by the author, consider putting the distfile on your home page and listing it as the first MASTER_SITES. If you can, try to talk the port author out of doing this; it really does help to establish some kind of source code control. Hosting your own version will prevent users from getting checksum mismatch errors, and also reduce the workload of maintainers of our FTP site. Also, if there is only one master site for the port, it is recommended that you house a backup at your site and list it as the second MASTER_SITES.

If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in DISTDIR. Do not worry if they come from a site other than where you got the main source tarball, we have a way to handle these situations (see the description of PATCHFILES below).

### Modifying the port

Unpack a copy of the tarball in a private directory and make whatever changes are necessary to get the port to compile properly under the current version of FreeBSD. Keep careful track of everything you do, as you will be automating the process shortly. Everything, including the deletion, addition, or modification of files should be doable using an automated script or patch file when your port is finished.

If your port requires significant user interaction/customization to compile or install, you should take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the new ports collection is to make each port as plug-and-play as possible for the end-user while using a minimum of disk space.

Unless explicitly stated, patch files, scripts, and other files you have created and contributed to the FreeBSD ports collection are assumed to be covered by the standard BSD copyright conditions.

### Patching

In the preparation of the port, files that have been added or changed can be picked up with a recursive &man.diff.1; for later feeding to &man.patch.1;. Each set of patches you wish to apply should be collected into a file named `patch-*` where * denotes the sequence in which the patches will be applied. If you wish, you can use names that indicate the pathnames of the files that are patched, such as `patch-Imakefile` or `patch-src-config.h`. These files should be stored in PATCHDIR, from where they will be automatically applied. All patches should be relative to WRKSRC (generally the directory your port's tarball unpacks itself into, that being where the build is done). To make fixes and upgrades easier, you should avoid having more than one patch fix the same file (e.g., `patch-file` and `patch-file2` both changing `WRKSRC/foobar.c`).

Please only use characters `[-+._a-zA-Z0-9]` for naming your patches. Do not use any other characters besides them. Do not name your patches like `patch-aa` or `patch-ab` etc, always mention path and file name in patch names.

Do not put RCS strings in patches. CVS will mangle them when we put the files into the ports tree, and when we check them out again, they will come out different and the patch will fail. RCS strings are surrounded by dollar (`&dollar;`) signs, and typically start with `&dollar;Id` or `&dollar;RCS`.

Using the recurse (`-r`) option to &man.diff.1; to generate patches is fine, but please take a look at the resulting patches to make sure you do not have any unnecessary junk in there. In particular, diffs between two backup files, `Makefile`s when the port uses `Imake` or GNU `configure`, etc., are unnecessary and should be deleted. If you had to edit `configure.in` and run `autoconf` to regenerate `configure`, do not take the diffs of `configure` (it often grows to a few thousand lines!); define `USE_AUTOCONF_VER=213` and take the diffs of `configure.in`.

Quite often, there is a situation when the software being ported, especially if it is primarily developed on &windows;, uses the CR/LF convention for most of its source files. This may cause problems with further patching, compiler warnings, scripts execution (`/bin/sh^M` not found), etc. To quickly convert those files from CR/LF to just LF, you can do something like this:

    USE_REINPLACE=	yes

    post-extract:
    	@${FIND} -E ${WRKDIR} -type f -iregex ".*\.(c|cpp|h|txt)" -print0 | \
    		${XARGS} -0 ${REINPLACE_CMD} -e 's/[[:cntrl:]]*$$//'

Of course, if you need to process each and every file, `-iregex` above can be omitted. Be aware that this piece of code will strip all trailing control characters from each line of processed file (except `\n`).

Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. Once you are happy with the resulting diff, please split it up into one source file per patch file.

### Configuring

Include any additional customization commands in your `configure` script and save it in the `scripts` subdirectory. As mentioned above, you can also do this with `Makefile` targets and/or scripts with the name `pre-configure` or `post-configure`.

### Handling user input

If your port requires user input to build, configure, or install, you must set IS_INTERACTIVE in your `Makefile`. This will allow overnight builds to skip your port if the user sets the variable `BATCH` in his environment (and if the user sets the variable `INTERACTIVE`, then only those ports requiring interaction are built). This will save a lot of wasted time on the set of machines that continually build ports (see below).

It is also recommended that if there are reasonable default answers to the questions, you check the PACKAGE_BUILDING variable and turn off the interactive script when it is set. This will allow us to build the packages for CDROMs and FTP.

## Configuring the Makefile

Configuring the `Makefile` is pretty simple, and again we suggest that you look at existing examples before starting. Also, there is a sample Makefile in this handbook, so take a look and please follow the ordering of variables and sections in that template to make your port easier for others to read.

Now, consider the following problems in sequence as you design your new `Makefile`:

### The original source

Does it live in DISTDIR as a standard gzip'd tarball named something like `foozolix-1.2.tar.gz`? If so, you can go on to the next step. If not, you should look at overriding any of the DISTNAME, EXTRACT_CMD, EXTRACT_BEFORE_ARGS, EXTRACT_AFTER_ARGS, EXTRACT_SUFX, or DISTFILES variables, depending on how alien a format your port's distribution file is. (The most common case is `EXTRACT_SUFX=.tar.Z`, when the tarball is condensed by regular `compress`, not `gzip`.)

In the worst case, you can simply create your own do-extract target to override the default, though this should be rarely, if ever, necessary.

### Naming

The first part of the port's `Makefile` names the port, describes its version number, and lists it in the correct category.

#### PORTNAME and PORTVERSION

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

#### PORTREVISION and PORTEPOCH

##### 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. &man.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.

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

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.

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

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.

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

#### 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 `name` part should be lowercase. (The rest of the name can 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`. If the software in question has numbers, hyphens, or underscores in its name, you may include them as well (like `kinput2`).

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

4. 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
XFree86-3.3.6 | (empty) | XFree86 | (empty) | 3.3.6 | 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.

### Categorization

#### CATEGORIES

When a package is created, it is put under `/usr/ports/packages/All` and links are made from one or more subdirectories of `/usr/ports/packages`. The names of these subdirectories are specified by the variable CATEGORIES. It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. Please take a look at the current list of categories and pick the ones that are suitable for your port.

This list also determines where in the ports tree the port is imported. If you put more than one category here, it is assumed that the port files will be put in the subdirectory with the name in the first category. See below for more discussion about how to pick the right categories.

#### Current list of categories

Here is the current list of port categories. Those marked with an asterisk (`*`) are virtual categories—those that do not have a corresponding subdirectory in the ports tree. They are only used as secondary categories, and only for search purposes.

For non-virtual categories, you will find a one-line description in the COMMENT in that subdirectory's `Makefile`.

Category | Description | Notes
--- | --- | ---
`accessibility` | Ports to help disabled users. |
`afterstep*` | Ports to support the AfterStep window manager. |
`arabic` | Arabic language support. |
`archivers` | Archiving tools. |
`astro` | Astronomical ports. |
`audio` | Sound support. |
`benchmarks` | Benchmarking utilities. |
`biology` | Biology-related software. |
`cad` | Computer aided design tools. |
`chinese` | Chinese language support. |
`comms` | Communication software. | Mostly software to talk to your serial port.
`converters` | Character code converters. |
`databases` | Databases. |
`deskutils` | Things that used to be on the desktop before computers were invented. |
`devel` | Development utilities. | Do not put libraries here just because they are libraries—unless they truly do not belong anywhere else, they should not be in this category.
`dns` | DNS-related software. |
`editors` | General editors. | Specialized editors go in the section for those tools (e.g., a mathematical-formula editor will go in `math`).
`elisp*` | Emacs-lisp ports. |
`emulators` | Emulators for other operating systems. | Terminal emulators do not belong here—X-based ones should go to `x11` and text-based ones to either `comms` or `misc`, depending on the exact functionality.
`finance` | Monetary, financial and related applications. |
`french` | French language support. |
`ftp` | FTP client and server utilities. | If your port speaks both FTP and HTTP, put it in `ftp` with a secondary category of `www`.
`games` | Games. |
`german` | German language support. |
`gnome*` | Ports from the GNOME Project. |
`graphics` | Graphics utilities. |
`haskell*` | Software related to the Haskell language. |
`hebrew` | Hebrew language support. |
`hungarian` | Hungarian language support. |
`ipv6*` | IPv6 related software. |
`irc` | Internet Relay Chat utilities. |
`japanese` | Japanese language support. |
`java` | Software related to the Java language. | The `java` category shall not be the only one for a port. Save for ports directly related to the Java language, porters are also encouraged not to use `java` as the main category of a port.
`kde*` | Ports from the K Desktop Environment (KDE) Project. |
`korean` | Korean language support. |
`lang` | Programming languages. |
`linux*` | Linux applications and support utilities. |
`lisp*` | Software related to the Lisp language. |
`mail` | Mail software. |
`math` | Numerical computation software and other utilities for mathematics. |
`mbone` | MBone applications. |
`misc` | Miscellaneous utilities | Basically things that do not belong anywhere else. If at all possible, try to find a better category for your port than `misc`, as ports tend to get overlooked in here.
`multimedia` | Multimedia software. |
`net` | Miscellaneous networking software. |
`net-mgmt` | Networking management software. |
`news` | USENET news software. |
`offix*` | Ports from the OffiX suite. |
`palm` | Software support for the Palm™ series. |
`parallel*` | Applications dealing with parallelism in computing. |
`pear*` | Ports related to the Pear PHP framework. |
`perl5*` | Ports that require Perl version 5 to run. |
`plan9*` | Various programs from Plan9. |
`polish` | Polish language support. |
`portuguese` | Portuguese language support. |
`print` | Printing software. | Desktop publishing tools (previewers, etc.) belong here too.
`python*` | Software related to the Python language. |
`ruby*` | Software related to the Ruby language. |
`russian` | Russian language support. |
`science` | Scientific ports that do not fit into other categories such as `astro`, `biology` and `math`. |
`security` | Security utilities. |
`shells` | Command line shells. |
`sysutils` | System utilities. |
`tcl76*` | Ports that use Tcl version 7.6 to run. |
`tcl80*` | Ports that use Tcl version 8.0 to run. |
`tcl81*` | Ports that use Tcl version 8.1 to run. |
`tcl82*` | Ports that use Tcl version 8.2 to run. |
`tcl83*` | Ports that use Tcl version 8.3 to run. |
`textproc` | Text processing utilities. | It does not include desktop publishing tools, which go to `print`.
`tk42*` | Ports that use Tk version 4.2 to run. |
`tk80*` | Ports that use Tk version 8.0 to run. |
`tk81*` | Ports that use Tk version 8.1 to run. |
`tk82*` | Ports that use Tk version 8.2 to run. |
`tk83*` | Ports that use Tk version 8.3 to run. |
`tkstep80*` | Ports that use TkSTEP version 8.0 to run. |
`ukrainian` | Ukrainian language support. |
`vietnamese` | Vietnamese language support. |
`windowmaker*` | Ports to support the WindowMaker window manager. |
`www` | Software related to the World Wide Web. | HTML language support belongs here too.
`x11` | The X Window System and friends. | This category is only for software that directly supports the window system. Do not put regular X applications here; most of them should go into other `x11-*` categories (see below). If your port is an X application, define USE_XLIB (implied by USE_IMAKE) and put it in the appropriate category.
`x11-clocks` | X11 clocks. |
`x11-fm` | X11 file managers. |
`x11-fonts` | X11 fonts and font utilities. |
`x11-servers` | X11 servers. |
`x11-toolkits` | X11 toolkits. |
`x11-wm` | X11 window managers. |
`zope*` | Zope support. |

#### Choosing the right category

As many of the categories overlap, you often have to choose which of the categories should be the primary category of your port. There are several rules that govern this issue. Here is the list of priorities, in decreasing order of precedence:

- The first category must be a physical category (see above). This is necessary to make the packaging work. Virtual categories and physical categories may be intermixed after that.

- Language specific categories always come first. For example, if your port installs Japanese X11 fonts, then your CATEGORIES line would read `japanese x11-fonts`.

- Specific categories are listed before less-specific ones. For instance, an HTML editor should be listed as `www editors`, not the other way around. Also, you should not list `net` when the port belongs to any of `irc`, `mail`, `mbone`, `news`, `security`, or `www`, as `net` is included implicitly.

- `x11` is used as a secondary category only when the primary category is a natural language. In particular, you should not put `x11` in the category line for X applications.

- Emacs modes should be placed in the same ports category as the application supported by the mode, not in `editors`. For example, an Emacs mode to edit source files of some programming language should go into `lang`.

- `misc` should not appear with any other non-virtual category. If you have `misc` with something else in your CATEGORIES line, that means you can safely delete `misc` and just put the port in that other subdirectory!

- If your port truly does not belong anywhere else, put it in `misc`.

If you are not sure about the category, please put a comment to that effect in your &man.send-pr.1; submission so we can discuss it before we import it. If you are a committer, send a note to the &a.ports; so we can discuss it first. Too often, new ports are imported to the wrong category only to be moved right away. This causes unnecessary and undesirable bloat in the master source repository.

#### Proposing a new category

As the Ports Collection has grown over time, various new categories have been introduced. New categories can either be virtual categories—those that do not have a corresponding subdirectory in the ports tree— or physical categories—those that do. The following text discusses the issues involved in creating a new physical category so that you can understand them before you propose one.

Our existing practice has been to avoid creating a new physical category unless either a large number of ports would logically belong to it, or the ports that would belong to it are a logically distinct group that is of limited general interest (for instance, categories related to spoken human languages), or preferably both.

The rationale for this is that such a change creates a fair amount of work for both the committers and also for all users who track changes to the Ports Collection. In addition, proposed category changes just naturally seem to attract controversy. (Perhaps this is because there is no clear consensus on when a category is too big, nor whether categories should lend themselves to browsing (and thus what number of categories would be an ideal number), and so forth.)

Here is the procedure:

1. Propose the new category on &a.ports;. You should include a detailed rationale for the new category, including why you feel the existing categories are not sufficient, and the list of existing ports proposed to move. (If there are new ports pending in GNATS that would fit this category, list them too.) If you are the maintainer and/or submitter, respectively, mention that as it may help you to make your case.

2. Participate in the discussion.

3. If it seems that there is support for your idea, file a PR which includes both the rationale and the list of existing ports that need to be moved. Ideally, this PR should also include patches for the following:

   - `Makefile`s for the new ports once they are repocopied

   - `Makefile` for the new category

   - `Makefile` for the old ports' categories

   - `Makefile`s for ports that depend on the old ports

   - (for extra credit, you can include the other files that have to changes, as per the procedure in the Committer's Guide.)

4. Since it affects the ports infrastructure and involves not only performing repo-copies but also possibly running regression tests on the build cluster, the PR should be assigned to the &a.portmgr;.

5. If that PR is approved, a committer will need to follow the rest of the procedure that is outlined in the Committer's Guide.

Proposing a new virtual category should be similar to the above but much less involved, since no ports will actually have to move. In this case, the only patches to include in the PR would be those to add the new category to the CATEGORIESs of the affected ports.

#### Proposing reorganizing all the categories

Occasionally someone proposes reorganizing the categories with either a 2-level structure, or some other kind of keyword structure. To date, nothing has come of any of these proposals because, while they are very easy to make, the effort involved to retrofit the entire existing ports collection with any kind of reorganization is daunting to say the very least. Please read the history of these proposals in the mailing list archives before you post this idea; furthermore, you should be prepared to be challenged to offer a working prototype.

### The distribution files

The second part of the `Makefile` describes the files that must be downloaded in order to build the port, and where they can be downloaded from.

#### DISTNAME

DISTNAME is the name of the port as called by the authors of the software. DISTNAME defaults to `${PORTNAME}-${PORTVERSION}`, so override it only if necessary. DISTNAME is only used in two places. First, the distribution file list (DISTFILES) defaults to ${DISTNAME}${EXTRACT_SUFX}. Second, the distribution file is expected to extract into a subdirectory named WRKSRC, which defaults to `work/${DISTNAME}`.

PKGNAMEPREFIX and PKGNAMESUFFIX do not affect DISTNAME. Also note that if WRKSRC is equal to `work/${PORTNAME}-${PORTVERSION}` while the original source archive is named something other than ${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}, you should probably leave DISTNAME alone— you are better off defining DISTFILES than having to set both DISTNAME and WRKSRC (and possibly EXTRACT_SUFX).

#### MASTER_SITES

Record the directory part of the FTP/HTTP-URL pointing at the original tarball in MASTER_SITES. Do not forget the trailing slash (`/`)!

The `make` macros will try to use this specification for grabbing the distribution file with FETCH if they cannot find it already on the system.

It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard against wide-area network problems. We are even planning to add support for automatically determining the closest master site and fetching from there; having multiple sites will go a long way towards helping this effort.

If the original tarball is part of one of the popular archives such as X-contrib, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using MASTER_SITE_* (e.g., MASTER_SITE_XCONTRIB and MASTER_SITE_PERL_GNU). Simply set MASTER_SITES to one of these variables and MASTER_SITE_SUBDIR to the path within the archive. Here is an example:

    MASTER_SITES=         ${MASTER_SITE_XCONTRIB}
    MASTER_SITE_SUBDIR=   applications

These variables are defined in `/usr/ports/Mk/bsd.sites.mk`. There are new entries added all the time, so make sure to check the latest version of this file before submitting a port.

The user can also set the MASTER_SITE_* variables in `/etc/make.conf` to override our choices, and use their favorite mirrors of these popular archives instead.

#### EXTRACT_SUFX

If you have one distribution file, and it uses an odd suffix to indicate the compression mechanism, set EXTRACT_SUFX.

For example, if the distribution file was named `foo.tgz` instead of the more normal `foo.tar.gz`, you would write:

    DISTNAME=      foo
    EXTRACT_SUFX=  .tgz

The USE_BZIP2 and USE_ZIP variables automatically set EXTRACT_SUFX to `.bz2` or `.zip` as necessary. If neither of these are set then EXTRACT_SUFX defaults to `.tar.gz`.

You never need to set both EXTRACT_SUFX and DISTFILES.

#### DISTFILES

Sometimes the names of the files to be downloaded have no resemblance to the name of the port. For example, it might be called `source.tar.gz` or similar. In other cases the application's source code might be in several different archives, all of which must be downloaded.

If this is the case, set DISTFILES to be a space separated list of all the files that must be downloaded.

    DISTFILES=     source1.tar.gz source2.tar.gz

If not explicitly set, DISTFILES defaults to `${DISTNAME}${EXTRACT_SUFX}`.

#### EXTRACT_ONLY

If only some of the DISTFILES must be extracted—for example, one of them is the source code, while another is an uncompressed document—list the filenames that must be extracted in EXTRACT_ONLY.

    DISTFILES=     source.tar.gz manual.html
    EXTRACT_ONLY=  source.tar.gz

If none of the DISTFILES should be uncompressed then set EXTRACT_ONLY to the empty string.

    EXTRACT_ONLY=

#### PATCHFILES

If your port requires some additional patches that are available by FTP or HTTP, set PATCHFILES to the names of the files and PATCH_SITES to the URL of the directory that contains them (the format is the same as MASTER_SITES).

If the patch is not relative to the top of the source tree (i.e., WRKSRC) because it contains some extra pathnames, set PATCH_DIST_STRIP accordingly. For instance, if all the pathnames in the patch have an extra `foozolix-1.0/` in front of the filenames, then set `PATCH_DIST_STRIP=-p1`.

Do not worry if the patches are compressed; they will be decompressed automatically if the filenames end with `.gz` or `.Z`.

If the patch is distributed with some other files, such as documentation, in a gzip'd tarball, you cannot just use PATCHFILES. If that is the case, add the name and the location of the patch tarball to DISTFILES and MASTER_SITES. Then, use the EXTRA_PATCHES variable to point to those files and `bsd.port.mk` will automatically apply them for you. In particular, do not copy patch files into the PATCHDIR directory—that directory may not be writable.

The tarball will have been extracted alongside the regular source by then, so there is no need to explicitly extract it if it is a regular gzip'd or compress'd tarball. If you do the latter, take extra care not to overwrite something that already exists in that directory. Also, do not forget to add a command to remove the copied patch in the pre-clean target.

#### Multiple distribution files or patches from different sites and subdirectories (`MASTER_SITES:n`)

(Consider this to be a somewhat advanced topic; those new to this document may wish to skip this section at first).

This section has information on the fetching mechanism known as both `MASTER_SITES:n` and `MASTER_SITES_NN`. We will refer to this mechanism as `MASTER_SITES:n` hereon.

A little background first. OpenBSD has a neat feature inside both DISTFILES and PATCHFILES variables, both files and patches can be postfixed with `:n` identifiers where `n` both can be `[0-9]` and denote a group designation. For example:

    DISTFILES=      alpha:0 beta:1

In OpenBSD, distribution file `alpha` will be associated with variable MASTER_SITES0 instead of our common MASTER_SITES and `beta` with MASTER_SITES1.

This is a very interesting feature which can decrease that endless search for the correct download site.

Just picture 2 files in DISTFILES and 20 sites in MASTER_SITES, the sites slow as hell where `beta` is carried by all sites in MASTER_SITES, and `alpha` can only be found in the 20th site. It would be such a waste to check all of them if maintainer knew this beforehand, would it not? Not a good start for that lovely weekend!

Now that you have the idea, just imagine more DISTFILES and more MASTER_SITES. Surely our distfiles survey meister would appreciate the relief to network strain that this would bring.

In the next sections, information will follow on the FreeBSD implementation of this idea. We improved a bit on OpenBSD's concept.

##### Simplified information

This section tells you how to quickly prepare fine grained fetching of multiple distribution files and patches from different sites and subdirectories. We describe here a case of simplified `MASTER_SITES:n` usage. This will be sufficient for most scenarios. However, if you need further information, you will have to refer to the next section.

Some applications consist of multiple distribution files that must be downloaded from a number of different sites. For example, Ghostscript consists of the core of the program, and then a large number of driver files that are used depending on the user's printer. Some of these driver files are supplied with the core, but many others must be downloaded from a variety of different sites.

To support this, each entry in DISTFILES may be followed by a colon and a tag name. Each site listed in MASTER_SITES is then followed by a colon, and the tag that indicates which distribution files should be downloaded from this site.

For example, consider an application with the source split in two parts, `source1.tar.gz` and `source2.tar.gz`, which must be downloaded from two different sites. The port's `Makefile` would include lines like .

###### Simplified use of `MASTER_SITES:n` with 1 file per site

    MASTER_SITES=   ftp://ftp.example1.com/:source1 \
    		ftp://ftp.example2.com/:source2
    DISTFILES=      source1.tar.gz:source1 \
    		source2.tar.gz:source2

Multiple distribution files can have the same tag. Continuing the previous example, suppose that there was a third distfile, `source3.tar.gz`, that should be downloaded from ftp.example2.com. The `Makefile` would then be written like .

###### Simplified use of `MASTER_SITES:n` with more than 1 file per site

    MASTER_SITES=   ftp://ftp.example1.com/:source1 \
    		ftp://ftp.example2.com/:source2
    DISTFILES=      source1.tar.gz:source1 \
    		source2.tar.gz:source2 \
    		source3.tar.gz:source2

##### Detailed information

Okay, so the previous section example did not reflect your needs? In this section we will explain in detail how the fine grained fetching mechanism `MASTER_SITES:n` works and how you can modify your ports to use it.

1. Elements can be postfixed with `:n` where n is `[^:,]+`, i.e., n could conceptually be any alphanumeric string but we will limit it to `[a-zA-Z_][0-9a-zA-Z_]+` for now.

   Moreover, string matching is case sensitive; i.e., `n` is different from `N`.

   However, the following words cannot be used for postfixing purposes since they yield special meaning: `default`, `all` and `ALL` (they are used internally in item ). Furthermore, `DEFAULT` is a special purpose word (check item ).

2. Elements postfixed with `:n` belong to the group `n`, `:m` belong to group `m` and so forth.

3. Elements without a postfix are groupless, i.e., they all belong to the special group `DEFAULT`. If you postfix any elements with `DEFAULT`, you are just being redundant unless you want to have an element belonging to both `DEFAULT` and other groups at the same time (check item ).

   The following examples are equivalent but the first one is preferred:

       MASTER_SITES=   alpha

       MASTER_SITES=   alpha:DEFAULT

4. Groups are not exclusive, an element may belong to several different groups at the same time and a group can either have either several different elements or none at all. Repeated elements within the same group will be simply that, repeated elements.

5. When you want an element to belong to several groups at the same time, you can use the comma operator (`,`).

   Instead of repeating it several times, each time with a different postfix, we can list several groups at once in a single postfix. For instance, `:m,n,o` marks an element that belongs to group `m`, `n` and `o`.

   All the following examples are equivalent but the last one is preferred:

       MASTER_SITES=   alpha alpha:SOME_SITE

       MASTER_SITES=   alpha:DEFAULT alpha:SOME_SITE

       MASTER_SITES=   alpha:SOME_SITE,DEFAULT

       MASTER_SITES=   alpha:DEFAULT,SOME_SITE

6. All sites within a given group are sorted according to MASTER_SORT_AWK. All groups within MASTER_SITES and PATCH_SITES are sorted as well.

7. Group semantics can be used in any of the following variables MASTER_SITES, PATCH_SITES, MASTER_SITE_SUBDIR, PATCH_SITE_SUBDIR, DISTFILES, and PATCHFILES according to the following syntax:

   1. All MASTER_SITES, PATCH_SITES, MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR elements must be terminated with the forward slash `/` character. If any elements belong to any groups, the group postfix `:n` must come right after the terminator `/`. The `MASTER_SITES:n` mechanism relies on the existence of the terminator `/` to avoid confusing elements where a `:n` is a valid part of the element with occurrences where `:n` denotes group `n`. For compatibility purposes, since the `/` terminator was not required before in both MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR elements, if the postfix immediate preceding character is not a `/` then `:n` will be considered a valid part of the element instead of a group postfix even if an element is postfixed with `:n`. See both and .

      ###### Detailed use of `MASTER_SITES:n` in MASTER_SITE_SUBDIR

          MASTER_SITE_SUBDIR=     old:n new/:NEW

      - Directories within group `DEFAULT` -> old:n

      - Directories within group `NEW` -> new

      ###### Detailed use of `MASTER_SITES:n` with comma operator, multiple files, multiple sites and multiple subdirectories

          MASTER_SITES=   http://site1/%SUBDIR%/ http://site2/:DEFAULT \
          		http://site3/:group3 http://site4/:group4 \
          		http://site5/:group5 http://site6/:group6 \
          		http://site7/:DEFAULT,group6 \
          		http://site8/%SUBDIR%/:group6,group7 \
          		http://site9/:group8
          DISTFILES=      file1 file2:DEFAULT file3:group3 \
          		file4:group4,group5,group6 file5:grouping \
          		file6:group7
          MASTER_SITE_SUBDIR=     directory-trial:1 directory-n/:groupn \
          			directory-one/:group6,DEFAULT \
          			directory

      The previous example results in the following fine grained fetching. Sites are listed in the exact order they will be used.

      - `file1` will be fetched from

        - MASTER_SITE_OVERRIDE

        - http://site1/directory/

        - http://site1/directory-one/

        - http://site1/directory-trial:1/

        - http://site2/

        - http://site7/

        - MASTER_SITE_BACKUP

      - `file2` will be fetched exactly as `file1` since they both belong to the same group

        - MASTER_SITE_OVERRIDE

        - http://site1/directory/

        - http://site1/directory-one/

        - http://site1/directory-trial:1/

        - http://site2/

        - http://site7/

        - MASTER_SITE_BACKUP

      - `file3` will be fetched from

        - MASTER_SITE_OVERRIDE

        - http://site3/

        - MASTER_SITE_BACKUP

      - `file4` will be fetched from

        - MASTER_SITE_OVERRIDE

        - http://site4/

        - http://site5/

        - http://site6/

        - http://site7/

        - http://site8/directory-one/

        - MASTER_SITE_BACKUP

      - `file5` will be fetched from

        - MASTER_SITE_OVERRIDE

        - MASTER_SITE_BACKUP

      - `file6` will be fetched from

        - MASTER_SITE_OVERRIDE

        - http://site8/directory-one/

        - MASTER_SITE_BACKUP

8. How do I group one of the special variables from `bsd.sites.mk`, e.g., MASTER_SITE_SOURCEFORGE?

   See .

   ###### Detailed use of `MASTER_SITES:n` with MASTER_SITE_SOURCEFORGE

       MASTER_SITES=   http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
       DISTFILES=      something.tar.gz:sourceforge

   `something.tar.gz` will be fetched from all sites within MASTER_SITE_SOURCEFORGE.

9. How do I use this with PATCH* variables?

   All examples were done with MASTER* variables but they work exactly the same for PATCH* ones as can be seen in .

   ###### Simplified use of `MASTER_SITES:n` with PATCH_SITES.

       PATCH_SITES=    http://site1/ http://site2/:test
       PATCHFILES=     patch1:test

##### What does change for ports? What does not?

1. All current ports remain the same. The `MASTER_SITES:n` feature code is only activated if there are elements postfixed with `:n` like elements according to the aforementioned syntax rules, especially as shown in item .

2. The port targets remain the same: checksum, makesum, patch, configure, build, etc. With the obvious exceptions of do-fetch, fetch-list, master-sites and patch-sites.

   - do-fetch: deploys the new grouping postfixed DISTFILES and PATCHFILES with their matching group elements within both MASTER_SITES and PATCH_SITES which use matching group elements within both MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR. Check .

   - fetch-list: works like old fetch-list with the exception that it groups just like do-fetch.

   - master-sites and patch-sites: (incompatible with older versions) only return the elements of group `DEFAULT`; in fact, they execute targets master-sites-default and patch-sites-default respectively.

     Furthermore, using target either master-sites-all or patch-sites-all is preferred to directly checking either MASTER_SITES or PATCH_SITES. Also, directly checking is not guaranteed to work in any future versions. Check item for more information on these new port targets.

3. New port targets

   1. There are master-sites-n and patch-sites-n targets which will list the elements of the respective group n within MASTER_SITES and PATCH_SITES respectively. For instance, both master-sites-DEFAULT and patch-sites-DEFAULT will return the elements of group `DEFAULT`, master-sites-test and patch-sites-test of group `test`, and thereon.

   2. There are new targets master-sites-all and patch-sites-all which do the work of the old master-sites and patch-sites ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many MASTER_SITE_BACKUP and MASTER_SITE_OVERRIDE as there are groups defined within either DISTFILES or PATCHFILES; respectively for master-sites-all and patch-sites-all.

#### DIST_SUBDIR

Do not let your port clutter `/usr/ports/distfiles`. If your port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (e.g., `Makefile`), set DIST_SUBDIR to the name of the port (`${PORTNAME}` or `${PKGNAMEPREFIX}${PORTNAME}` should work fine). This will change DISTDIR from the default `/usr/ports/distfiles` to `/usr/ports/distfiles/DIST_SUBDIR`, and in effect puts everything that is required for your port into that subdirectory.

It will also look at the subdirectory with the same name on the backup master site at `ftp.FreeBSD.org`. (Setting DISTDIR explicitly in your Makefile will not accomplish this, so please use DIST_SUBDIR.)

This does not affect the MASTER_SITES you define in your `Makefile`.

### MAINTAINER

Set your mail-address here. Please. :-)

Note that only a single address without the comment part is allowed as a MAINTAINER value. The format used should be `user@hostname.domain`. Please do not include any descriptive text such as your real name in this entry—that merely confuses `bsd.port.mk`. Instead, put that information into your `pkg-descr`.

For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section.

If the maintainer of a port does not respond to an update request from a user after two weeks (excluding major public holidays), then that is considered a maintainer timeout, and the update may be made without explicit maintainer approval. If the maintainer does not respond within three months, then that maintainer is considered absent without leave, and can be replaced as the maintainer of the particular port in question. Exceptions to this are anything maintained by the &a.portmgr;, or the &a.security-officer;. No unauthorized commits may ever be made to ports maintained by those groups.

The &a.portmgr; reserves the right to revoke or override anyone's maintainership for any reason, and the &a.security-officer; reserves the right to revoke or override maintainership for security reasons.

### COMMENT

This is a one-line description of the port. Please do not include the package name (or version number of the software) in the comment. The comment should begin with a capital and end without a period. Here is an example:

    COMMENT=       A cat chasing a mouse all over the screen

The COMMENT variable should immediately follow the MAINTAINER variable in the `Makefile`.

Please try to keep the COMMENT line less than 70 characters, as it is displayed to users as a one-line summary of the port.

### Dependencies

Many ports depend on other ports. There are seven variables that you can use to ensure that all the required bits will be on the user's machine. There are also some pre-supported dependency variables for common cases, plus a few more to control the behavior of dependencies.

#### LIB_DEPENDS

This variable specifies the shared libraries this port depends on. It is a list of lib:dir:target tuples where lib is the name of the shared library, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. For example,

     LIB_DEPENDS=
    	      jpeg.9:${PORTSDIR}/graphics/jpeg:install

will check for a shared jpeg library with major version 9, and descend into the `graphics/jpeg` subdirectory of your ports tree to build and install it if it is not found. The target part can be omitted if it is equal to DEPENDS_TARGET (which defaults to `install`).

The lib part is an argument given to `ldconfig -r | grep -wF`. There shall be no regular expressions in this variable.

The dependency is checked twice, once from within the extract target and then from within the install target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system.

#### RUN_DEPENDS

This variable specifies executables or files this port depends on during run-time. It is a list of path:dir:target tuples where path is the name of the executable or file, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. If path starts with a slash (`/`), it is treated as a file and its existence is tested with `test -e`; otherwise, it is assumed to be an executable, and `which -s` is used to determine if the program exists in the search path.

For example,

    RUN_DEPENDS=   ${LOCALBASE}/etc/innd:${PORTSDIR}/news/inn \
    	       wish8.0:${PORTSDIR}/x11-toolkits/tk80

will check if the file or directory `/usr/local/etc/innd` exists, and build and install it from the `news/inn` subdirectory of the ports tree if it is not found. It will also see if an executable called `wish8.0` is in the search path, and descend into the `x11-toolkits/tk80` subdirectory of your ports tree to build and install it if it is not found.

In this case, `innd` is actually an executable; if an executable is in a place that is not expected to be in the search path, you should use the full pathname.

The official search `PATH` used on the ports build cluster is

    /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/X11R6/bin

The dependency is checked from within the install target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. The target part can be omitted if it is the same as DEPENDS_TARGET.

#### BUILD_DEPENDS

This variable specifies executables or files this port requires to build. Like RUN_DEPENDS, it is a list of path:dir:target tuples. For example,

     BUILD_DEPENDS=
    	      unzip:${PORTSDIR}/archivers/unzip

will check for an executable called `unzip`, and descend into the `archivers/unzip` subdirectory of your ports tree to build and install it if it is not found.

build here means everything from extraction to compilation. The dependency is checked from within the extract target. The target part can be omitted if it is the same as DEPENDS_TARGET

#### FETCH_DEPENDS

This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of path:dir:target tuples. For example,

     FETCH_DEPENDS=
    	      ncftp2:${PORTSDIR}/net/ncftp2

will check for an executable called `ncftp2`, and descend into the `net/ncftp2` subdirectory of your ports tree to build and install it if it is not found.

The dependency is checked from within the fetch target. The target part can be omitted if it is the same as DEPENDS_TARGET.

#### EXTRACT_DEPENDS

This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of path:dir:target tuples. For example,

    EXTRACT_DEPENDS=
    	      unzip:${PORTSDIR}/archivers/unzip

will check for an executable called `unzip`, and descend into the `archivers/unzip` subdirectory of your ports tree to build and install it if it is not found.

The dependency is checked from within the extract target. The target part can be omitted if it is the same as DEPENDS_TARGET.

Use this variable only if the extraction does not already work (the default assumes `gzip`) and cannot be made to work using USE_ZIP or USE_BZIP2 described in .

#### PATCH_DEPENDS

This variable specifies executables or files this port requires to patch. Like the previous, it is a list of path:dir:target tuples. For example,

     PATCH_DEPENDS=
    	      ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract

will descend into the `java/jfc` subdirectory of your ports tree to build and install it if it is not found.

The dependency is checked from within the patch target. The target part can be omitted if it is the same as DEPENDS_TARGET.

#### DEPENDS

If there is a dependency that does not fall into either of the above categories, or your port requires having the source of the other port extracted in addition to having it installed, then use this variable. This is a list of dir:target, as there is nothing to check, unlike the previous four. The target part can be omitted if it is the same as DEPENDS_TARGET.

#### USE_*

A number of variables exist in order to encapsulate common dependencies that many ports have. Although their use is optional, they can help to reduce the verbosity of the port `Makefile`s. Each of them is styled as USE_*. The usage of these variables is restricted to the port `Makefile`s and `ports/Mk/bsd.*.mk` and is not designed to encapsulate user-settable options — use WITH_* and WITHOUT_* for that purpose.

It is always incorrect to set any USE_* in `/etc/make.conf`. For instance, setting

    USE_GCC=3.2

would adds a dependency on gcc32 for every port, including gcc32 itself!

##### The USE_* variables

Variable | Means
--- | ---
USE_BZIP2 | The port's tarballs are compressed with `bzip2`.
USE_ZIP | The port's tarballs are compressed with `zip`.
USE_GMAKE | The port requires `gmake` to build.
USE_PERL5 | The port requires `perl 5` to build and install. See for additional variables that can be set relating to `perl`.
USE_X_PREFIX | The port installs in to X11BASE rather than PREFIX. See for additional variables that can be set relating to X11.
USE_AUTOMAKE_VER | The port uses GNU `automake` as part of its build process. See for additional variables that can be set relating to `automake`.
USE_AUTOCONF_VER | The port uses GNU `autoconf` as part of its build process. See for additional variables that can be set relating to `autoconf`.
USE_LIBTOOL_VER | The port uses GNU `libtool` as part of its build process. See for additional variables that can be set relating to `libtool`.
GMAKE | The full path for `gmake` if it is not in the `PATH`.
USE_BISON | The port uses `bison` for building.
USE_SDL | The port uses `SDL` for building and running. See on how to use USE_SDL.
NO_INSTALL_MANPAGES | Do not use the install.man target.

Define `USE_XLIB=yes` if your port requires the X Window System to be installed (it is implied by USE_IMAKE). Define `USE_GMAKE=yes` if your port requires GNU `make` instead of BSD `make`. Define `USE_AUTOCONF_VER=213` if your port requires GNU autoconf to be run. Define `USE_QT_VER=3` if your port uses the latest Qt toolkit. Use `USE_PERL5=yes` if your port requires version 5 of the `perl` language. (The last is especially important since some versions of FreeBSD have `perl5` as part of the base system while others do not.)

#### Notes on dependencies

As mentioned above, the default target to call when a dependency is required is DEPENDS_TARGET. It defaults to `install`. This is a user variable; it is never defined in a port's `Makefile`. If your port needs a special way to handle a dependency, use the `:target` part of the *_DEPENDS variables instead of redefining DEPENDS_TARGET.

When you type `make clean`, its dependencies are automatically cleaned too. If you do not wish this to happen, define the variable NOCLEANDEPENDS in your environment. This may be particularly desirable if the port has something that takes a long time to rebuild in its dependency list, such as KDE, GNOME or Mozilla.

To depend on another port unconditionally, use the variable ${NONEXISTENT} as the first field of BUILD_DEPENDS or RUN_DEPENDS. Use this only when you need to get the source of the other port. You can often save compilation time by specifying the target too. For instance

    BUILD_DEPENDS=   ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract

will always descend to the `jpeg` port and extract it.

Do not use DEPENDS unless there is no other way the behavior you want can be accomplished. It will cause the other port to always be built (and installed, by default), and the dependency will go into the packages as well. If this is really what you need, you should probably write it as `BUILD_DEPENDS` and `RUN_DEPENDS` instead—at least the intention will be clear.

#### Circular dependencies are fatal

Do not introduce any circular dependencies into the ports tree!

The ports building technology does not tolerate circular dependencies. If you introduce one, you will have someone, somewhere in the world, whose FreeBSD installation will break almost immediately, with many others quickly to follow. These can really be hard to detect; if in doubt, before you make that change, make sure you have done the following: `cd /usr/ports; make index`. That process can be quite slow on older machines, but you may be able to save a large number of people—including yourself— a lot of grief in the process.

### Makefile Options

Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Examples include choice of natural (human) language, GUI versus command-line, or type of database to support. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to control which configuration should be built. Supporting these properly will make users happy, and effectively provide 2 or more ports for the price of one.

#### WITH_* and WITHOUT_*

These variables are designed to be set by the system administrator. There are many that are standardized in `ports/Mk/bsd.*.mk`; others are not, which can be confusing. If you need to add such a configuration variable, please consider using one of the ones from the following list.

You should not assume that a WITH_* necessarily has a corresponding WITHOUT_* variable and vice versa. In general, the default is simply assumed.

Unless otherwise specified, these variables are only tested for being set or not set, rather than being set to some kind of variable such as `YES` or `NO`.

##### The WITH_* and WITHOUT_* variables

Variable | Means
--- | ---
WITH_APACHE2 | If set, use `www/apache2` instead of the default of `www/apache`.
WITH_BERKELEY_DB | Define this variable to specify the ability to use a variant of the Berkeley database package such as `databases/db41`. An associated variable, WITH_BDB_VER, may be set to values such as 2, 3, 4, 41 or 42.
WITH_MYSQL | Define this variable to specify the ability to use a variant of the MySQL database package such as `databases/mysql40-server`. An associated variable, WANT_MYSQL_VER, may be set to values such as 323, 40, 41, or 50.
WITHOUT_NLS | If set, says that internationalization is not needed, which can save compile time. By default, internationalization is used.
WITH_OPENSSL_BASE | Use the version of OpenSSL in the base system.
WITH_OPENSSL_PORT | Use the version of OpenSSL from `security/openssh`, overwriting the version that was originally installed in the base system.
WITH_POSTGRESQL | Define this variable to specify the ability to use a variant of the PostGreSQL database package such as `databases/postgresql72`.
WITHOUT_X11 | If the port can be built both with and without X support, then it should normally be built with X support. If this variable is defined, then the version that does not have X support should be built instead.

#### OPTIONS

##### Background

The OPTIONS variable gives the user who installs the port a dialog with the available options and saves them to `/var/db/ports/portname/options`. Next time when the port has to be rebuild, the options are reused. Never again you will have to remember all the twenty WITH_* and WITHOUT_* options you used to build this port!

##### Syntax

The syntax for the OPTIONS variable is:

    OPTIONS=	OPTION	"descriptive text" default ...

The value for default is either `ON` or `OFF`. Multiple repetitions of these three fields are allowed.

When the user runs `make config` (or runs `make build` for the first time), the framework will check for `/var/db/ports/portname /options`. If that file does not exist, it will use the values of OPTIONS to create a dialogbox where the options can be enabled or disabled. Then the options file is saved and the selected variables will be used when building the port.

Use `make showconfig` to see the saved configuration. Use `make rmconfig` to remove the saved configuration.

###### Example

###### Simple use of OPTIONS

    OPTIONS=	FOO "Enable option foo" On \
    			BAR "Support feature bar" Off

    .include <bsd.port.pre.mk>

    .if defined(WITHOUT_FOO)
    CONFIGURE_ARGS+=	--without-foo
    .else
    CONFIGURE_ARGS+=	--with-foo
    .endif

    .if defined(WITH_BAR)
    RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
    .endif

    .include <bsd.port.post.mk>

###### Brokenness

- `make index` does not follow OPTIONS yet (ports/75727)

- PACKAGE_BUILDING is ignoring OPTIONS (ports/75727?)

### Specifying the working directory

Each port is extracted in to a working directory, which must be writable. The ports system defaults to having the DISTFILES unpack in to a directory called `${DISTNAME}`. In other words, if you have set:

    PORTNAME=      foo
    PORTVERSION=   1.0

then the port's distribution files contain a top-level directory, `foo-1.0`, and the rest of the files are located under that directory.

There are a number of variables you can override if that is not the case.

#### WRKSRC

The variable lists the name of the directory that is created when the application's distfiles are extracted. If our previous example extracted into a directory called `foo` (and not `foo-1.0`) you would write:

    WRKSRC=      ${WRKDIR}/foo

or possibly

    WRKSRC=      ${WRKDIR}/${PORTNAME}

#### NO_WRKSUBDIR

If the port does not extract in to a subdirectory at all then you should set NO_WRKSUBDIR to indicate that.

    NO_WRKSUBDIR= yes

### CONFLICTS

If your package cannot coexist with other packages (because of file conflicts, runtime incompatibility, etc.), list the other package names in the CONFLICTS variable. You can use shell globs like `*` and `?` here. Packages names should be enumerated the same way they appear in `/var/db/pkg`. Please make sure that CONFLICTS does not match this port's package itself, or else forcing its installation with FORCE_PKG_REGISTER will no longer work.

CONFLICTS automatically sets IGNORE, which is more fully documented in .

### Building mechanisms

If your package uses GNU `make`, set `USE_GMAKE=yes`. If your package uses `configure`, set `HAS_CONFIGURE=yes`. If your package uses GNU `configure`, set `GNU_CONFIGURE=yes` (this implies `HAS_CONFIGURE`). If you want to give some extra arguments to `configure` (the default argument list `--prefix=&dollar;{PREFIX}` for GNU `configure` and empty for non-GNU `configure`), set those extra arguments in CONFIGURE_ARGS. If your package uses GNU `autoconf`, set `USE_AUTOCONF_VER=213`. This implies GNU_CONFIGURE, and will cause `autoconf` to be run before `configure`.

If your package uses GNU `configure`, and the resulting executable file has a strange name like `i386-portbld-freebsd4.7-`appname, you will need to additionally override the CONFIGURE_TARGET variable to specify the target in the way required by scripts generated by recent versions of `autoconf`. Add the following line immediately after the `GNU_CONFIGURE=yes` line in your `Makefile`:

`CONFIGURE_TARGET=--build=${MACHINE_ARCH}-portbld-freebsd${OSREL}`

If your package is an X application that creates `Makefile`s from `Imakefile`s using `imake`, then set `USE_IMAKE=yes`. This will cause the configure stage to automatically do an `xmkmf -a`. If the `-a` flag is a problem for your port, set `XMKMF=xmkmf`. If the port uses `imake` but does not understand the install.man target, `NO_INSTALL_MANPAGES=yes` should be set. In addition, the author of the original port should be shot. :->

If your port's source `Makefile` has something else than all as the main build target, set ALL_TARGET accordingly. Same goes for install and INSTALL_TARGET.

## Special considerations

There are some more things you have to take into account when you create a port. This section explains the most common of those.

### Shared Libraries

If your port installs one or more shared libraries, define a INSTALLS_SHLIB make variable, which will instruct a `bsd.port.mk` to run `&dollar;{LDCONFIG} -m` on the directory where the new library is installed (usually `PREFIX/lib`) during post-install target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate `@exec /sbin/ldconfig -m` and `@unexec /sbin/ldconfig -R` pair into your `pkg-plist` file, so that a user who installed the package can start using the shared library immediately and de-installation will not cause the system to still believe the library is there.

If you need, you can override the default location where the new library is installed by defining the LDCONFIG_DIRS make variable, which should contain a list of directories into which shared libraries are to be installed. For example if your port installs shared libraries into `PREFIX/lib/foo` and `PREFIX/lib/bar` directories you could use the following in your `Makefile`:

    INSTALLS_SHLIB= yes
    LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar

Note that content of LDCONFIG_DIRS is passed through &man.sed.1; just like the rest of `pkg-plist`, so PLIST_SUB substitutions also apply here. It is recommended that you use `%%PREFIX%%` for PREFIX, `%%LOCALBASE%%` for LOCALBASE and `%%X11BASE%%` for X11BASE.

### Ports with distribution restrictions

Licenses vary, and some of them place restrictions on how the application can be packaged, whether it can be sold for profit, and so on.

It is your responsibility as a porter to read the licensing terms of the software and make sure that the FreeBSD project will not be held accountable for violating them by redistributing the source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt, please contact the &a.ports;.

In situations like this, the variables described in the following sections can be set.

#### NO_PACKAGE

This variable indicates that we may not generate a binary package of the application. For instance, the license may disallow binary redistribution, or it may prohibit distribution of packages created from patched sources.

However, the port's DISTFILES may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless NO_CDROM is set as well.

NO_PACKAGE should also be used if the binary package is not generally useful, and the application should always be compiled from the source code. For example, if the application has configuration information that is site specific hard coded in to it at compile time, set NO_PACKAGE.

NO_PACKAGE should be set to a string describing the reason why the package should not be generated.

#### NO_CDROM

This variable alone indicates that, although we are allowed to generate binary packages, we may put neither those packages nor the port's DISTFILES onto a CD-ROM (or similar media) for resale. However, the binary packages and the port's DISTFILES will still be available via FTP/HTTP.

If this variable is set along with NO_PACKAGE, then only the port's DISTFILES will be available, and only via FTP/HTTP.

NO_CDROM should be set to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, this should be used if the port's license is for non-commercial use only.

#### RESTRICTED

Set this variable alone if the application's license permits neither mirroring the application's DISTFILES nor distributing the binary package in any way.

NO_CDROM or NO_PACKAGE should not be set along with RESTRICTED since the latter variable implies the former ones.

RESTRICTED should be set to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download the DISTFILES, possibly after registering for the software or agreeing to accept the terms of an EULA.

#### RESTRICTED_FILES

When RESTRICTED or NO_CDROM is set, this variable defaults to `${DISTFILES} ${PATCHFILES}`, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them.

Note that the port committer should add an entry to `/usr/ports/LEGAL` for every listed distribution file, describing exactly what the restriction entails.

### Using `perl`

#### Variables for ports that use `perl`

Variable | Means
--- | ---
USE_PERL5 | Says that the port uses `perl 5` to build and run.
USE_PERL5_BUILD | Says that the port uses `perl 5` to build.
USE_PERL5_RUN | Says that the port uses `perl 5` to run.
PERL | The full path of `perl 5`, either in the system or installed from a port, but without the version number. Use this if you need to replace `#!`lines in scripts.
PERL_CONFIGURE | Configure using Perl's MakeMaker. It implies USE_PERL5.
PERL_MODBUILD | Configure, build and install using Module::Build. It implies PERL_CONFIGURE.
Read only variables
PERL_VERSION | The full version of `perl` installed (e.g., `5.00503`).
PERL_VER | The short version of `perl` installed (e.g., `5.005`).
PERL_LEVEL | The installed `perl` version as an integer of the form `MNNNPP` (e.g., `500503`).
PERL_ARCH | Where `perl` stores architecture dependent libraries. Defaults to `${ARCH}-freebsd`.
PERL_PORT | Name of the `perl` port that is installed (e.g., `perl5`).
SITE_PERL | Directory name where site specific `perl` packages go. This value is added to PLIST_SUB.

### Using X11

#### Variables for ports that use X

USE_X_PREFIX | The port installs in X11BASE, not PREFIX.
USE_XLIB | The port uses the X libraries.
USE_MOTIF | The port uses the Motif toolkit. Implies USE_XPM.
USE_IMAKE | The port uses `imake`. Implies USE_X_PREFIX.
XMKMF | Set to the path of `xmkmf` if not in the `PATH`. Defaults to `xmkmf -a`.

### Using `automake`, `autoconf`, and `libtool`

#### Variables for ports that use automake, autoconf or libtool

Variable | Means
--- | ---
AUTOMAKE | The full path for `automake` if it is not in the `PATH`.
USE_AUTOMAKE_VER | The port uses `automake`. Valid values for this variable are `14` and `15`, and sets the AUTOMAKE_DIR and ACLOCAL_DIR variables appropriately.
AUTOMAKE_ARGS | One or more command line arguments to pass to AUTOMAKE if USE_AUTOMAKE_VER is set.
AUTOMAKE_ENV | One or more environment variables to set (and their values) before running AUTOMAKE.
ACLOCAL | Set to the path of the GNU `aclocal` if it is not in the `PATH`. The default is set according to the USE_AUTOMAKE_VER variable.
ACLOCAL_DIR | Set to the path of the GNU `aclocal` shared directory. The default is set according to the USE_AUTOMAKE_VER variable.
AUTOMAKE_DIR | Set to the path of the GNU `automake` shared directory. The default is set according to the USE_AUTOMAKE_VER variable.
USE_AUTOCONF_VER | Specifies that the port uses `autoconf`. Implies `GNU_CONFIGURE`. The default value is 213.
AUTOCONF | Set to the path of GNU `autoconf` if it is not in the `PATH`. The default is set according to the USE_AUTOCONF_VER variable.
AUTOCONF_ARGS | Command line arguments to pass to `autoconf`.
AUTOCONF_ENV | Set these `variable=value` pairs in the environment before running `autoconf`.
USE_AUTOHEADER_VER | Specifies that the port uses `autoheader`. Implies `USE_AUTOCONF_VER`. The default value is 213.
AUTOHEADER | Set to the path of GNU `autoheader` if it is not in the `PATH`. The default is set according to USE_AUTOCONF_VER.
AUTORECONF | Set to the path of GNU `autoreconf` if it is not in the `PATH`. The default is set according to USE_AUTOCONF_VER.
AUTOSCAN | Set to the path of GNU `autoscan` if it is not set in the `PATH`. The default is set according to USE_AUTOCONF_VER.
AUTOIFNAMES | Set to the path of GNU `autoifnames` if it is not set in the `PATH`. The default is set according to USE_AUTOCONF_VER.
USE_LIBTOOL_VER | The port uses `libtool`. Implies GNU_CONFIGURE. The default value is 13.
LIBTOOL | Set to the path of `libtool` if it is not set in the `PATH`.
LIBTOOLFILES | The files to patch for `libtool`. Defaults to `aclocal.m4` if USE_AUTOCONF is defined, `configure` otherwise.
LIBTOOLFLAGS | Additional flags to pass to `ltconfig`. Defaults to `--disable-ltlibs`.

### Using GNOME

The FreeBSD/GNOME project uses its own set of variables to define which GNOME components a particular port uses. A comprehensive list of these variables exists within the FreeBSD/GNOME project's homepage.

Your port does not need to depend on GNOME if it merely installs pkg-config metadata files to `PREFIX/libdata/pkgconfig`. As usual, your port should be prepared to clean up after itself and remove that directory if it becomes empty. Assuming that your port installs a file named `gtkmumble.pc` to the said location, just add the following lines to `pkg-plist`:

    libdata/pkgconfig/gtkmumble.pc
    @unexec rmdir %B 2>/dev/null || true

The latter line must appear immediately after the former one so that `%B` expands correctly. Please refer to &man.pkg.create.1; for a detailed description of the syntax used in `pkg-plist`.

### Using KDE

#### Variables for ports that use KDE

USE_QT_VER | The port uses the Qt toolkit. Possible values are `1` and `3`; each specify the major version of Qt to use. Sets both MOC and QTCPPFLAGSto default appropriate values.
USE_KDELIBS_VER | The port uses KDE libraries. Possible values are `3`; each specify the major version of KDE to use. Implies USE_QT_VER of the appropriate version.
USE_KDEBASE_VER | The port uses KDE base. Possible values are `3`; each specify the major version of KDE to use. Implies USE_KDELIBS_VER of the appropriate version.
MOC | Set to the path of `moc`. Default set according to USE_QT_VER value.
QTCPPFLAGS | Set the CPPFLAGS to use when processing Qt code. Default set according to USE_QT_VER value.

### Using Bison

This section is yet to be written.

### Using Java

#### Variable definitions

If your port needs a Java™ Development Kit (JDK) to either build, run or even extract the distfile, then it should define USE_JAVA.

There are several JDKs in the ports collection, from various vendors, and in several versions. If your port must use one of these versions, you can define which one. The most current version is `java/jdk14`.

##### Variables that may be set by ports that use Java

Variable | Means
--- | ---
USE_JAVA | Should be defined for the remaining variables to have any effect.
JAVA_VERSION | List of space-separated suitable Java versions for the port. An optional `"+"` allows you to specify a range of versions (allowed values: `1.1[+] 1.2[+] 1.3[+] 1.4[+]`).
JAVA_OS | List of space-separated suitable JDK port operating systems for the port (allowed values: `native linux`).
JAVA_VENDOR | List of space-separated suitable JDK port vendors for the port (allowed values: `freebsd bsdjava sun ibm blackdown`).
JAVA_BUILD | When set, it means that the selected JDK port should be added to the build dependencies of the port.
JAVA_RUN | When set, it means that the selected JDK port should be added to the run dependencies of the port.
JAVA_EXTRACT | When set, it means that the selected JDK port should be added to the extract dependencies of the port.

USE_JIKES

Whether the port should or should not use the `jikes` bytecode compiler to build. When no value is set for this variable, the port will use `jikes` to build if available. You may also explicitly forbid or enforce the use of `jikes` (by setting `'no'` or `'yes'`). In the later case, `devel/jikes` will be added to build dependencies of the port. In any case that `jikes` is actually used in place of `javac`, then the HAVE_JIKES variable is defined by `bsd.java.mk`.

Below is the list of all settings a port will receive after setting USE_JAVA:

##### Variables provided to ports that use Java

Variable | Value
--- | ---
JAVA_PORT | The name of the JDK port (e.g. `'java/jdk14'`).
JAVA_PORT_VERSION | The full version of the JDK port (e.g. `'1.4.2'`). If you only need the first two digits of this version number, use ${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}.
JAVA_PORT_OS | The operating system used by the JDK port (e.g. `'linux'`).
JAVA_PORT_VENDOR | The vendor of the JDK port (e.g. `'sun'`).
JAVA_PORT_OS_DESCRIPTION | Description of the operating system used by the JDK port (e.g. `'Linux'`).
JAVA_PORT_VENDOR_DESCRIPTION | Description of the vendor of the JDK port (e.g. `'FreeBSD Foundation'`).
JAVA_HOME | Path to the installation directory of the JDK (e.g. `'/usr/local/jdk1.3.1'`).
JAVAC | Path to the Java compiler to use (e.g. `'/usr/local/jdk1.1.8/bin/javac'` or `'/usr/local/bin/jikes'`).
JAR | Path to the `jar` tool to use (e.g. `'/usr/local/jdk1.2.2/bin/jar'` or `'/usr/local/bin/fastjar'`).
APPLETVIEWER | Path to the `appletviewer` utility (e.g. `'/usr/local/linux-jdk1.2.2/bin/appletviewer'`).
JAVA | Path to the `java` executable. Use this for executing Java programs (e.g. `'/usr/local/jdk1.3.1/bin/java'`).
JAVADOC | Path to the `javadoc` utility program.
JAVAH | Path to the `javah` program.
JAVAP | Path to the `javap` program.
JAVA_KEYTOOL | Path to the `keytool` utility program. This variable is available only if the JDK is Java 1.2 or higher.
JAVA_N2A | Path to the `native2ascii` tool.
JAVA_POLICYTOOL | Path to the `policytool` program. This variable is available only if the JDK is Java 1.2 or higher.
JAVA_SERIALVER | Path to the `serialver` utility program.
RMIC | Path to the RMI stub/skeleton generator, `rmic`.
RMIREGISTRY | Path to the RMI registry program, `rmiregistry`.
RMID | Path to the RMI daemon program `rmid`. This variable is only available if the JDK is Java 1.2 or higher.
JAVA_CLASSES | Path to the archive that contains the JDK class files. On JDK 1.2 or later, this is `${JAVA_HOME}/jre/lib/rt.jar`. Earlier JDKs used `${JAVA_HOME}/lib/classes.zip`.
HAVE_JIKES | Defined whenever `jikes` is used by the port (see USE_JIKES above).

You may use the `java-debug` make target to get information for debugging your port. It will display the value of many of the forecited variables.

Additionally, the following constants are defined so all Java ports may be installed in a consistent way:

##### Constants defined for ports that use Java

Constant | Value
--- | ---
JAVASHAREDIR | The base directory for everything related to Java. Default: `${PREFIX}/share/java`.
JAVAJARDIR | The directory where JAR files should be installed. Default: `${JAVASHAREDIR}/classes`.
JAVALIBDIR | The directory where JAR files installed by other ports are located. Default: `${LOCALBASE}/share/java/classes`.

The related entries are defined in both PLIST_SUB (documented in ) and SUB_LIST.

#### Building with Ant

When the port is to be built using Apache Ant, it has to define USE_ANT. Ant is thus considered to be the sub-make command. When no `do-build` target is defined by the port, a default one will be set that simply runs Ant according to MAKE_ENV, MAKE_ARGS and ALL_TARGETS. This is similar to the USE_GMAKE mechanism, which is documented in .

If `jikes` is used in place of `javac` (see USE_JIKES in ), then Ant will automatically use it to build the port.

#### Best practices

When porting a Java library, your port should install the JAR file(s) in `${JAVAJARDIR}`, and everything else under `${JAVASHAREDIR}/${PORTNAME}` (except for the documentation, see below). In order to reduce the packing file size, you may reference the JAR file(s) directly in the `Makefile`. Just use the following statement (where `myport.jar` is the name of the JAR file installed as part of the port):

    PLIST_FILES+= %%JAVAJARDIR%%/myport.jar

When porting a Java application, the port usually installs everything under a single directory (including its JAR dependencies). The use of `${JAVASHAREDIR}/${PORTNAME}` is strongly encouraged in this regard. It is up the porter to decide whether the port should install the additional JAR dependencies under this directory or directly use the already installed ones (from `${JAVAJARDIR}`).

Regardless of the type of your port (library or application), the additional documentation should be installed in the same location as for any other port. The JavaDoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list (`pkg-plist`). This is one reason why porters are strongly encouraged to use the PORTDOCS macro. Moreover, even if you can predict the set of files that will be generated by `javadoc`, the size of the resulting `pkg-plist` advocates for the use of PORTDOCS.

The default value for DATADIR is `${PREFIX}/share/${PORTNAME}`. It is a good idea to override DATADIR to `${JAVASHAREDIR}/${PORTNAME}` for Java ports. Indeed, DATADIR is automatically added to PLIST_SUB (documented in ) so you may use `%%DATADIR%%` directly in `pkg-plist`.

As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the &os; Java Project encourage porters to have their ports built from source whenever it is a trivial task.

All the features that have been presented in this section are implemented in `bsd.java.mk`. If you ever think that your port needs more sophisticated Java support, please first have a look at the bsd.java.mk CVS log as it usually takes some time to document the latest features. Then, if you think the support you are lacking would be beneficial to many other Java ports, feel free to discuss it on the &a.java;.

Although there is a `java` category for PRs, it refers to the JDK porting effort from the &os; Java project. Therefore, you should submit your Java port in the `ports` category as for any other port, unless the issue you are trying to resolve is related to either a JDK implementation or `bsd.java.mk`.

Similarly, there is a defined policy regarding the CATEGORIES of a Java port, which is detailed in .

### Using Python

This section is yet to be written.

### Using Emacs

This section is yet to be written.

### Using Ruby

This section is yet to be written.

### Using SDL

The USE_SDL variable is used to autoconfigure the dependencies for ports which use an SDL based library like `devel/sdl12` and `x11-toolkits/sdl_gui`.

The following SDL libraries are recognized at the moment:

- sdl: `devel/sdl12`

- gfx: `graphics/sdl_gfx`

- gui: `x11-toolkits/sdl_gui`

- image: `graphics/sdl_image`

- ldbad: `devel/sdl_ldbad`

- mixer: `audio/sdl_mixer`

- mm: `devel/sdlmm`

- net: `net/sdl_net`

- sound: `audio/sdl_sound`

- ttf: `graphics/sdl_ttf`

Therefore, if a port has a dependency on `net/sdl_net` and `audio/sdl_mixer`, the syntax will be:

    USE_SDL=        net mixer

The dependency `devel/sdl12`, which is required by `net/sdl_net` and `audio/sdl_mixer`, is automatically added as well.

If you use USE_SDL, it will automatically:

- Add a dependency on sdl12-config to BUILD_DEPENDS

- Add the variable SDL_CONFIG to CONFIGURE_ENV

- Add the dependencies of the selected libraries to the LIB_DEPENDS

To check whether an SDL library is available, you can do it with the WANT_SDL variable:

    WANT_SDL=yes

    .include <bsd.port.pre.mk>

    .if ${HAVE_SDL:Mmixer}!=""
    USE_SDL+=   mixer
    .endif

    .include <bsd.port.post.mk>

## MASTERDIR

If your port needs to build slightly different versions of packages by having a variable (for instance, resolution, or paper size) take different values, create one subdirectory per package to make it easier for users to see what to do, but try to share as many files as possible between ports. Typically you only need a very short `Makefile` in all but one of the directories if you use variables cleverly. In the sole `Makefile`, you can use MASTERDIR to specify the directory where the rest of the files are. Also, use a variable as part of PKGNAMESUFFIX so the packages will have different names.

This will be best demonstrated by an example. This is part of `japanese/xdvi300/Makefile`;

    PORTNAME=       xdvi
    PORTVERSION=    17
    PKGNAMEPREFIX=  ja-
    PKGNAMESUFFIX=  ${RESOLUTION}
     :
    # default
    RESOLUTION?=   300
    .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
           ${RESOLUTION} != 300 && ${RESOLUTION} != 400
           @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
           @${ECHO} "Possible values are: 118, 240, 300 (default) and 400."
           @${FALSE}
    .endif

`japanese/xdvi300` also has all the regular patches, package files, etc. If you type `make` there, it will take the default value for the resolution (300) and build the port normally.

As for other resolutions, this is the entire `xdvi118/Makefile`:

    RESOLUTION=     118
    MASTERDIR=      ${.CURDIR}/../xdvi300

    .include "${MASTERDIR}/Makefile"

(`xdvi240/Makefile` and `xdvi400/Makefile` are similar). The MASTERDIR definition tells `bsd.port.mk` that the regular set of subdirectories like FILESDIR and SCRIPTDIR are to be found under `xdvi300`. The `RESOLUTION=118` line will override the `RESOLUTION=300` line in `xdvi300/Makefile` and the port will be built with resolution set to 118.

## Shared library versions

Please read our policy on shared library versioning to understand what to do with shared library versions in general. Do not blindly assume software authors know what they are doing; many of them do not. It is very important that these details are carefully considered, as we have quite a unique situation where we are trying to have dozens of potentially incompatible software pairs co-exist. Careless port imports have caused great trouble regarding shared libraries in the past (ever wondered why the port `jpeg-6b` has a shared library version of 9?). If in doubt, send a message to the &a.ports;. Most of the time, your job ends by determining the right shared library version and making appropriate patches to implement it.

## Manpages

The MAN[1-9LN] variables will automatically add any manpages to `pkg-plist` (this means you must not list manpages in the `pkg-plist`—see generating PLIST for more). It also makes the install stage automatically compress or uncompress manpages depending on the setting of NOMANCOMPRESS in `/etc/make.conf`.

If your port tries to install multiple names for manpages using symlinks or hardlinks, you must use the MLINKS variable to identify these. The link installed by your port will be destroyed and recreated by `bsd.port.mk` to make sure it points to the correct file. Any manpages listed in MLINKS must not be listed in the `pkg-plist`.

To specify whether the manpages are compressed upon installation, use the MANCOMPRESSED variable. This variable can take three values, `yes`, `no` and `maybe`. `yes` means manpages are already installed compressed, `no` means they are not, and `maybe` means the software already respects the value of NOMANCOMPRESS so `bsd.port.mk` does not have to do anything special.

MANCOMPRESSED is automatically set to `yes` if USE_IMAKE is set and NO_INSTALL_MANPAGES is not set, and to `no` otherwise. You do not have to explicitly define it unless the default is not suitable for your port.

If your port anchors its man tree somewhere other than PREFIX, you can use the MANPREFIX to set it. Also, if only manpages in certain sections go in a non-standard place, such as some `perl` modules ports, you can set individual man paths using MANsectPREFIX (where sect is one of `1-9`, `L` or `N`).

If your manpages go to language-specific subdirectories, set the name of the languages to MANLANG. The value of this variable defaults to `""` (i.e., English only).

Here is an example that puts it all together.

    MAN1=          foo.1
    MAN3=          bar.3
    MAN4=          baz.4
    MLINKS=        foo.1 alt-name.8
    MANLANG=       "" ja
    MAN3PREFIX=    ${PREFIX}/share/foobar
    MANCOMPRESSED= yes

This states that six files are installed by this port;

    ${PREFIX}/man/man1/foo.1.gz
    ${PREFIX}/man/ja/man1/foo.1.gz
    ${PREFIX}/share/foobar/man/man3/bar.3.gz
    ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz
    ${PREFIX}/man/man4/baz.4.gz
    ${PREFIX}/man/ja/man4/baz.4.gz

Additionally `${PREFIX}/man/man8/alt-name.8.gz` may or may not be installed by your port. Regardless, a symlink will be made to join the foo(1) manpage and alt-name(8) manpage.

## Ports that require Motif

There are many programs that require a Motif library (available from several commercial vendors, while there is a free clone reported to be able to run many applications in `x11-toolkits/lesstif`) to compile. Since it is a popular toolkit and their licenses usually permit redistribution of statically linked binaries, we have made special provisions for handling ports that require Motif in a way that we can easily compile binaries linked either dynamically (for people who are compiling from the port) or statically (for people who distribute packages).

### USE_MOTIF

If your port requires Motif, define this variable in the `Makefile`. This will prevent people who do not own a copy of Motif from even attempting to build it.

### MOTIFLIB

This variable will be set by `bsd.port.mk` to be the appropriate reference to the Motif library. Please patch the source of your port to reference this wherever the Motif library is referenced in the `Makefile` or `Imakefile`.

There are two common cases:

- If the port refers to the Motif library as `-lXm` in its `Makefile` or `Imakefile`, simply substitute `&dollar;{MOTIFLIB}` for it.

- If the port uses `XmClientLibs` in its `Imakefile`, change it to `&dollar;{MOTIFLIB} &dollar;{XTOOLLIB} &dollar;{XLIB}`.

Note that MOTIFLIB (usually) expands to `-L/usr/X11R6/lib -lXm` or `/usr/X11R6/lib/libXm.a`, so there is no need to add `-L` or `-l` in front.

## X11 fonts

If your port installs fonts for the X Window System, put them in `X11BASE/lib/X11/fonts/local`. This directory was new to XFree86 3.3.3. If it does not exist, please create it, and print out a message urging the user to update their XFree86 to 3.3.3 or newer, or at least add this directory to the font path in `/etc/XF86Config`.

## Info files

If your package needs to install GNU info files, they should be listed in the INFO variable (without the trailing `.info`), and appropriate installation/de-installation code will be automatically added to the temporary `pkg-plist` before package registration.

## The `pkg-*` files

There are some tricks we have not mentioned yet about the `pkg-*` files that come in handy sometimes.

### `pkg-message`

If you need to display a message to the installer, you may place the message in `pkg-message`. This capability is often useful to display additional installation steps to be taken after a &man.pkg.add.1; or to display licensing information.

The `pkg-message` file does not need to be added to `pkg-plist`. Also, it will not get automatically printed if the user is using the port, not the package, so you should probably display it from the post-install target yourself.

### `pkg-install`

If your port needs to execute commands when the binary package is installed with &man.pkg.add.1; you can do this via the `pkg-install` script. This script will automatically be added to the package, and will be run twice by &man.pkg.add.1;: the first time as `&dollar;{SH} pkg-install &dollar;{PKGNAME} PRE-INSTALL` and the second time as `&dollar;{SH} pkg-install &dollar;{PKGNAME} POST-INSTALL`. `&dollar;2` can be tested to determine which mode the script is being run in. The `PKG_PREFIX` environmental variable will be set to the package installation directory. See &man.pkg.add.1; for additional information.

This script is not run automatically if you install the port with `make install`. If you are depending on it being run, you will have to explicitly call it from your port's `Makefile`, with a line like `PKG_PREFIX=&dollar;{PREFIX} &dollar;{SH} &dollar;{PKGINSTALL} &dollar;{PKGNAME} PRE-INSTALL`.

### `pkg-deinstall`

This script executes when a package is removed.

This script will be run twice by &man.pkg.delete.1;. The first time as `&dollar;{SH} pkg-deinstall &dollar;{PKGNAME} DEINSTALL` and the second time as `&dollar;{SH} pkg-deinstall &dollar;{PKGNAME} POST-DEINSTALL`.

### `pkg-req`

If your port needs to determine if it should install or not, you can create a `pkg-req` requirements script. It will be invoked automatically at installation/de-installation time to determine whether or not installation/de-installation should proceed.

The script will be run at installation time by &man.pkg.add.1; as `pkg-req &dollar;{PKGNAME} INSTALL`. At de-installation time it will be run by &man.pkg.delete.1; as `pkg-req &dollar;{PKGNAME} DEINSTALL`.

### Changing `pkg-plist` based on make variables

Some ports, particularly the `p5-` ports, need to change their `pkg-plist` depending on what options they are configured with (or version of `perl`, in the case of `p5-` ports). To make this easy, any instances in the `pkg-plist` of `%%OSREL%%`, `%%PERL_VER%%`, and `%%PERL_VERSION%%` will be substituted for appropriately. The value of `%%OSREL%%` is the numeric revision of the operating system (e.g., `4.9`). `%%PERL_VERSION%%` is the full version number of `perl` (e.g., `5.00502`) and `%%PERL_VER%%` is the `perl` version number minus the patchlevel (e.g., `5.005`). Several other `%%VARS%%` related to port's documentation files are described in the relevant section.

If you need to make other substitutions, you can set the PLIST_SUB variable with a list of `VAR=VALUE` pairs and instances of `%%VAR%%` will be substituted with VALUE in the `pkg-plist`.

For instance, if you have a port that installs many files in a version-specific subdirectory, you can put something like

    OCTAVE_VERSION= 2.0.13
    PLIST_SUB=      OCTAVE_VERSION=${OCTAVE_VERSION}

in the `Makefile` and use `%%OCTAVE_VERSION%%` wherever the version shows up in `pkg-plist`. That way, when you upgrade the port, you will not have to change dozens (or in some cases, hundreds) of lines in the `pkg-plist`.

This substitution (as well as addition of any manual pages) will be done between the pre-install and do-install targets, by reading from `PLIST` and writing to `TMPPLIST` (default: `WRKDIR/.PLIST.mktmp`). So if your port builds `PLIST` on the fly, do so in or before pre-install. Also, if your port needs to edit the resulting file, do so in post-install to a file named `TMPPLIST`.

Another possibility to modify port's packing list is based on setting the variables PLIST_FILES and PLIST_DIRS. The value of each variable is regarded as a list of pathnames to write to `TMPPLIST` along with `PLIST` contents. Names listed in PLIST_FILES and PLIST_DIRS are subject to `%%VAR%%` substitution, as described above. Except for that, names from PLIST_FILES will appear in the final packing list unchanged, while `@dirrm` will be prepended to names from PLIST_DIRS. To take effect, PLIST_FILES and PLIST_DIRS must be set before `TMPPLIST` is written, i.e. in pre-install or earlier.

### Changing the names of `pkg-*` files

All the names of `pkg-*` files are defined using variables so you can change them in your `Makefile` if need be. This is especially useful when you are sharing the same `pkg-*` files among several ports or have to write to one of the above files (see writing to places other than WRKDIR for why it is a bad idea to write directly into the `pkg-*` subdirectory).

Here is a list of variable names and their default values. (PKGDIR defaults to ${MASTERDIR}.)

Variable | Default value
--- | ---
DESCR | `${PKGDIR}/pkg-descr`
PLIST | `${PKGDIR}/pkg-plist`
PKGINSTALL | `${PKGDIR}/pkg-install`
PKGDEINSTALL | `${PKGDIR}/pkg-deinstall`
PKGREQ | `${PKGDIR}/pkg-req`
PKGMESSAGE | `${PKGDIR}/pkg-message`

Please change these variables rather than overriding PKG_ARGS. If you change PKG_ARGS, those files will not correctly be installed in `/var/db/pkg` upon install from a port.

### Making use of SUB_FILES and SUB_LIST

In some cases, it may be necessary to modify port files, i.e.: files not included in the original distribution, to set values; the SUB_FILES and SUB_LIST variables are available.

The SUB_FILES variable specifies a list of files to be automatically modified. Each file in the SUB_FILES list must have a corresponding `file.in` listed in FILESDIR. If you add some files, such as `pkg-message`, `pkg-install`, `pkg-deinstall` or `pkg-reg`, PKG-FILE associated variables will be set to `WRKDIR/pkg-file`.

The SUB_LIST variable is a list of `VAR=VALUE` pairs. The modified version of each file will be created in WRKDIR. For each `VAR=VALUE` in SUB_LIST, `%%VAR%%` will get replaced with `VALUE` in each file listed in SUB_FILES. Some usual pairs are automatically added to SUB_LIST, so you are not required to worry about them : `PREFIX=&dollar;{PREFIX}DOCSDIR=&dollar;{DOCSDIR}`, etc. (see `bsd.port.mk` for the entire list).

The substitution process is almost the same as the PLIST_SUB variable. Any line beginning with `@comment` after variable substitution will be deleted from resulting files.

The following example should be enough for a port to display a custom `pkg-message`, using `%%PREFIX%%`, and to install an rcNG startup script using `%%RC_SUBR%%`.

    SUB_FILES= pkg-message myport.sh
    SUB_LIST= RC_SUBR=${RC_SUBR}

    USE_RC_SUBR=  yes

Note that for this example, the `pkg-message.in` and `myport.sh.in` files must exist in FILESDIR.

## Testing your port

### Running `make describe`

Several of the &os; port maintenance tools, such as &man.portupgrade.1;, rely on a database called `/usr/ports/INDEX` which keeps track of such items as port dependencies. `INDEX` is created by the top-level `ports/Makefile` via `make index`, which descends into each port subdirectory and executes `make describe` there. Thus, if `make describe` fails in any port, no one can generate `INDEX`, and many people will quickly become unhappy.

It is important to be able to generate this file no matter what options are present in `make.conf`, so please avoid doing things such as using `.error` statements when (for instance) a dependency is not satisfied.

#### How to avoid using `.error`

Assume that someone has the line

    USE_POINTYHAT=yes

in `make.conf`. The first of the next two `Makefile` snippets will cause `make index` to fail, while the second one will not:

    .if USE_POINTYHAT
    .error "POINTYHAT is not supported"
    .endif

    .if USE_POINTYHAT
    IGNORE=POINTYHAT is not supported
    .endif

If `make describe` produces a string rather than an error message, you are probably safe. See `bsd.port.mk` for the meaning of the string produced.

Also note that running a recent version of `portlint` (as specified in the next section) will cause `make describe` to be run automatically.

### Portlint

Do check your work with `portlint` before you submit or commit it. `portlint` warns you about many common errors, both functional and stylistic. For a new (or repocopied) port, `portlint -A` is the most thorough; for an existing port, `portlint -C` is sufficient.

Since `portlint` uses heuristics to try to figure out errors, it can produce false positive warnings. In addition, occasionally something that is flagged as a problem really cannot be done in any other way due to limitations in the ports framework. When in doubt, the best thing to do is ask on &a.ports;.

### PREFIX

Do try to make your port install relative to PREFIX. (The value of this variable will be set to LOCALBASE (default `/usr/local`), unless USE_X_PREFIX or USE_IMAKE is set, in which case it will be X11BASE (default `/usr/X11R6`).

Avoiding the hard-coding of `/usr/local` or `/usr/X11R6` anywhere in the source will make the port much more flexible and able to cater to the needs of other sites. For X ports that use `imake`, this is automatic; otherwise, this can often be done by simply replacing the occurrences of `/usr/local` (or `/usr/X11R6` for X ports that do not use imake) in the various `scripts/Makefile`s in the port to read ${PREFIX}, as this variable is automatically passed down to every stage of the build and install processes.

Make sure your application is not installing things in `/usr/local` instead of PREFIX. A quick test for this is to do this is:

    &prompt.root; make clean; make package PREFIX=/var/tmp/port-name

If anything is installed outside of PREFIX, the package creation process will complain that it cannot find the files.

This does not test for the existence of internal references, or correct use of LOCALBASE for references to files from other ports. Testing the installation in `/var/tmp/port-name` to do that while you have it installed would do that.

Do not set USE_X_PREFIX unless your port truly requires it (i.e., it links against X libs or it needs to reference files in X11BASE).

The variable PREFIX can be reassigned in your `Makefile` or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the `Makefile`s.

Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro `PAGER` to be the full pathname of `less`, use the compiler flag:

    -DPAGER=\"&dollar;{PREFIX}/bin/less\"

or

    -DPAGER=\"&dollar;{LOCALBASE}/bin/less\"

if this is an X port, instead of `-DPAGER=\"/usr/local/bin/less\"`. This way it will have a better chance of working if the system administrator has moved the whole `/usr/local` tree somewhere else.

## Upgrading

When you notice that a port is out of date compared to the latest version from the original authors, you should first ensure that you have the latest port. You can find them in the `ports/ports-current` directory of the &os; FTP mirror sites. However, if you are working with more than a few ports, you will probably find it easier to use CVSup to keep your whole ports collection up-to-date, as described in the Handbook. This will have the added benefit of tracking all the ports' dependencies.

The next step is to see if there is an update already pending. To do this, you have two options. There is a searchable interface to the FreeBSD Problem Report (PR) database (also known as `GNATS`). Select `ports` in the dropdown, and enter the name of the port.

However, sometimes people forget to put the name of the port into the Synopsis field in an unambiguous fashion. In that case, you can try the FreeBSD Ports Monitoring System (also known as `portsmon`). This system attempts to classify port PRs by portname. To search for PRs about a particular port, use the Overview of One Port.

If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by `make maintainer`. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version); you would not want to duplicate their work. Note that unmaintained ports are listed with a maintainer of `ports@FreeBSD.org`, which is just the general ports mailing list, so sending mail there probably will not help in this case.

If the maintainer asks you to do the upgrade or there is no maintainer, then you have a chance to help out &os; by preparing the update yourself! Please make the changes and save the result of the recursive `diff` output of the new and old ports directories (e.g., if your modified port directory is called `superedit` and the original is in our tree as `superedit.bak`, then save the result of `diff -ruN superedit.bak superedit`). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the `-N` option—this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. To simplify common operations with patch files, you can use `/usr/ports/Tools/scripts/patchtool.py`. Before using it, please read `/usr/ports/Tools/scripts/README.patchtool`.

If the port is unmaintained, and you are actively using it yourself, please consider volunteering to become its maintainer. &os; has over 2000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section.)

The best way to send us the diff is by including it via &man.send-pr.1; (category `ports`). If you are volunteering to maintain the port, be sure to put `[maintainer update]` at the beginning of your synopsis line and set the Class of your PR to `maintainer-update`. Otherwise, the Class of your PR should be `change-request`. Please mention any added or deleted files in the message, as they have to be explicitly specified to &man.cvs.1; when doing a commit. If the diff is more than about 20KB, please compress and uuencode it; otherwise, just include it in the PR as is.

Before you &man.send-pr.1;, you should review the Writing the problem report section in the Problem Reports article; it contains far more information about how to write useful problem reports.

If your upgrade is motivated by security concerns or a serious fault in the currently committed port, please notify the &a.portmgr; to request immediate rebuilding and redistribution of your port's package. Unsuspecting users of &man.pkg.add.1; will otherwise continue to install the old version via `pkg_add -r` for several weeks.

Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports!

Now that you have done all that, you will want to read about how to keep up-to-date in .

## Ports security

### Why security is so important

Bugs are occasionally introduced to the software. Arguably, the most dangerous of them are those opening security vulnerabilities. From the technical viewpoint, such vulnerabilities are to be closed by exterminating the bugs that caused them. However, the policies for handling mere bugs and security vulnerabilities are very different.

A typical small bug affects only those users who have enabled some combination of options triggering the bug. The developer will eventually release a patch followed by a new version of the software, free of the bug, but the majority of users will not take the trouble of upgrading immediately because the bug has never vexed them. A critical bug that may cause data loss represents a graver issue. Nevertheless, prudent users know that a lot of possible accidents, besides software bugs, are likely to lead to data loss, and so they make backups of important data; in addition, a critical bug will be discovered really soon.

A security vulnerability is all different. First, it may remain unnoticed for years because often it does not cause software malfunction. Second, a malicious party can use it to gain unauthorized access to a vulnerable system, to destroy or alter sensitive data; and in the worst case the user will not even notice the harm caused. Third, exposing a vulnerable system often assists attackers to break into other systems that could not be compromised otherwise. Therefore closing a vulnerability alone is not enough: the audience should be notified of it in most clear and comprehensive manner, which will allow to evaluate the danger and take appropriate actions.

### Fixing security vulnerabilities

While on the subject of ports and packages, a security vulnerability may initially appear in the original distribution or in the port files. In the former case, the original software developer is likely to release a patch or a new version instantly, and you will only need to update the port promptly with respect to the author's fix. If the fix is delayed for some reason, you should either mark the port as FORBIDDEN or introduce a patch file of your own to the port. In the case of a vulnerable port, just fix the port as soon as possible. In either case, the standard procedure for submitting your change should be followed unless you have rights to commit it directly to the ports tree.

Being a ports committer is not enough to commit to an arbitrary port. Remember that ports usually have maintainers, whom you should respect.

Please make sure that the port's revision is bumped as soon as the vulnerability has been closed. That is how the users who upgrade installed packages on a regular basis will see they need to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. PORTREVISION should be bumped unless PORTVERSION has changed in the course of correcting the vulnerability. That is you should bump PORTREVISION if you have added a patch file to the port, but you should not if you have updated the port to the latest software version and thus already touched PORTVERSION. Please refer to the corresponding section for more information.

### Keeping the community informed

#### The VuXML database

A very important and urgent step to take as early as a security vulnerability is discovered is to notify the community of port users about the jeopardy. Such notification serves two purposes. First, should the danger be really severe, it will be wise to apply an instant workaround, e.g., stop the affected network service or even deinstall the port completely, until the vulnerability is closed. Second, a lot of users tend to upgrade installed packages just occasionally. They will know from the notification that they must update the package without delay as soon as a corrected version is available.

Given the huge number of ports in the tree, a security advisory cannot be issued on each incident without creating a flood and losing the attention of the audience by the time it comes to really serious matters. Therefore security vulnerabilities found in ports are recorded in the FreeBSD VuXML database. The Security Officer Team members are monitoring it for issues requiring their intervention.

If you have committer rights, you can update the VuXML database by yourself. So you will both help the Security Officer Team and deliver the crucial information to the community earlier. However, if you are not a committer, or you believe you have found an exceptionally severe vulnerability, or whatever, please do not hesitate to contact the Security Officer Team directly as described on the FreeBSD Security Information page.

All right, you elected the hard way. As it may be obvious from its title, the VuXML database is essentially an XML document. Its source file `vuln.xml` is kept right inside the port `security/vuxml`. Therefore the file's full pathname will be ``PORTSDIR`/security/vuxml/vuln.xml`. Each time you discover a security vulnerability in a port, please add an entry for it to that file. Until you are familiar with VuXML, the best thing you can do is to find an existing entry fitting your case, then copy it and use as a template.

#### A short introduction to VuXML

The full-blown XML is complex and far beyond the scope of this book. However, to gain basic insight on the structure of a VuXML entry, you need only the notion of tags. XML tag names are enclosed in angle brackets. Each opening <tag> must have a matching closing </tag>. Tags may be nested. If nesting, the inner tags must be closed before the outer ones. There is a hierarchy of tags, i.e. more complex rules of nesting them. Sounds very similar to HTML, doesn't it? The major difference is that XML is eXtensible, i.e. based on defining custom tags. Due to its intrinsic structure, XML puts otherwise amorphous data into shape. VuXML is particularly tailored to mark up descriptions of security vulnerabilities.

Now let's consider a realistic VuXML entry:

    <vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9">
      <topic>Several vulnerabilities found in Foo</topic>
      <affects>
        <package>
          <name>foo</name>
          <name>foo-devel</name>
          <name>ja-foo</name>
          <range><ge>1.6</ge><lt>1.9</lt></range>
          <range><ge>2.*</ge><lt>2.4_1</lt></range>
          <range><eq>3.0b1</eq></range>
        </package>
        <package>
          <name>openfoo</name>
          <range><lt>1.10_7</lt></range>
          <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range>
        </package>
      </affects>
      <description>
        <body xmlns="http://www.w3.org/1999/xhtml">
          <p>J. Random Hacker reports:</p>
          <blockquote
            cite="http://j.r.hacker.com/advisories/1">
            <p>Several issues in the Foo software may be exploited
              via carefully crafted QUUX requests.  These requests will
              permit the injection of Bar code, mumble theft, and the
              readability of the Foo administrator account.</p>
          </blockquote>
        </body>
      </description>
      <references>
        <freebsdsa>SA-10:75.foo</freebsdsa>
        <freebsdpr>ports/987654</freebsdpr>
        <cvename>CAN-2010-0201</cvename>
        <cvename>CAN-2010-0466</cvename>
        <bid>96298</bid>
        <certsa>CA-2010-99</certsa>
        <certvu>740169</certvu>
        <uscertsa>SA10-99A</uscertsa>
        <uscertta>SA10-99A</uscertta>
        <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist>
        <url>http://j.r.hacker.com/advisories/1</url>
      </references>
      <dates>
        <discovery>2010-05-25</discovery>
        <entry>2010-07-13</entry>
        <modified>2010-09-17</entry>
      </dates>
    </vuln>

The tag names are supposed to be self-descriptive, so we shall take a closer look only at fields you will need to fill in by yourself:

This is the top-level tag of a VuXML entry. It has a mandatory attribute, `vid`, specifying a universally unique identifier (UUID) for this entry (in quotes). You should generate a UUID for each new VuXML entry (and do not forget to substitute it for the template UUID unless you are writing the entry from scratch). You can use &man.uuidgen.1; in FreeBSD 5.x, or you may install the port `devel/p5-Data-UUID` and issue the following command:

    perl -MData::UUID -le 'print lc new Data::UUID->create_str'

This is a one-line description of the issue found.

The names of packages affected are listed there. Multiple names can be given since several packages may be based on a single master port or software product. This may include stable and development branches, localized versions, and slave ports featuring different choices of important build-time configuration options.

It is your responsibility to find all such related packages when writing a VuXML entry. Keep in mind that `make search name=foo` is your friend. The primary points to look for are as follows:

- the `foo-devel` variant for a `foo` port;

- other variants with a suffix like `-a4` (for print-related packages), `-without-gui` (for packages with X support disabled), or similar;

- `jp-`, `ru-`, `zh-`, and other possible localized variants in the corresponding national categories of the ports collection.

Affected versions of the package(s) are specified there as one or more ranges using a combination of `<lt>`, `<le>`, `<eq>`, `<ge>`, and `<gt>` elements. The version ranges given should not overlap.

In a range specification, `*` (asterisk) denotes the smallest version number. In particular, `2.*` is less than `2.a`. Therefore an asterisk may be used for a range to match all possible `alpha`, `beta`, and `RC` versions. For instance, `<ge>2.*</ge><lt>3.*</lt>` will selectively match every `2.x` version while `<ge>2.0</ge><lt>3.0</lt>` will obviously not since the latter misses `2.r3` and matches `3.b`.

The above example specifies that affected are versions from `1.6` to `1.9` inclusive, versions `2.x` before `2.4_1`, and version `3.0b1`.

Several related package groups (essentially, ports) can be listed in the `<affected>` section. This can be used if several software products (say FooBar, FreeBar and OpenBar) grow from the same code base and still share its bugs and vulnerabilities. Note the difference from listing multiple names within a single <package> section.

The version ranges should allow for PORTEPOCH and PORTREVISION if applicable. Please remember that according to the collation rules, a version with a non-zero PORTEPOCH is greater than any version without PORTEPOCH, e.g., `3.0,1` is greater than `3.1` or even than `8.9`.

This is a summary of the issue. XHTML is used in this field. At least enclosing `<p>` and `</p>` should appear. More complex mark-up may be used, but only for the sake of accuracy and clarity: No eye candy please.

This section contains references to relevant documents. As many references as apply are encouraged.

This is a FreeBSD security advisory.

This is a FreeBSD problem report.

This is a Mitre CVE identifier.

This is a SecurityFocus Bug ID.

This is a US-CERT security advisory.

This is a US-CERT vulnerability note.

This is a US-CERT Cyber Security Alert.

This is a US-CERT Technical Cyber Security Alert.

This is a URL to an archived posting in a mailing list. The attribute `msgid` is optional and may specify the message ID of the posting.

This is a generic URL. It should be used only if none of the other reference categories apply.

This is the date when the issue was disclosed (YYYY-MM-DD).

This is the date when the entry was added (YYYY-MM-DD).

This is the date when any information in the entry was last modified (YYYY-MM-DD). New entries must not include this field. It should be added upon editing an existing entry.

#### Testing your changes to the VuXML database

Assume you just wrote or filled in an entry for a vulnerability in the package `clamav` that has been fixed in version `0.65_7`.

As a prerequisite, you need to install fresh versions of the ports `security/portaudit` and `security/portaudit-db`.

First, check whether there already is an entry for this vulnerability. If there were such entry, it would match the previous version of the package, `0.65_6`:

    &prompt.user; packaudit
    &prompt.user; portaudit clamav-0.65_6

To run `packaudit`, you must have permission to write to its `DATABASEDIR`, typically `/var/db/portaudit`.

If there is none found, you get the green light to add a new entry for this vulnerability. Now you can generate a brand-new UUID (assume it's `74a9541d-5d6c-11d8-80e3-0020ed76ef5a`) and add your new entry to the VuXML database. Please verify its syntax after that as follows:

    &prompt.user; cd ${PORTSDIR}/security/vuxml && make validate

You will need at least one of the following packages installed: `textproc/libxml2`, `textproc/jade`.

Now rebuild the `portaudit` database from the VuXML file:

    &prompt.user; packaudit

To verify that the `<affected>` section of your entry will match correct package(s), issue the following command:

    &prompt.user; portaudit -f /usr/ports/INDEX -r 74a9541d-5d6c-11d8-80e3-0020ed76ef5a

Please refer to &man.portaudit.1; for better understanding of the command syntax.

Make sure that your entry produces no spurious matches in the output.

Now check whether the right package versions are matched by your entry:

    &prompt.user; portaudit clamav-0.65_6 clamav-0.65_7
    Affected package: clamav-0.65_6 (matched by clamav<0.65_7)
    Type of problem: clamav remote denial-of-service.
    Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html>

    1 problem(s) found.

Obviously, the former version should match while the latter one should not.

Finally, verify whether the web page generated from the VuXML database looks like expected:

    &prompt.user; mkdir -p ~/public_html/portaudit
    &prompt.user; packaudit
    &prompt.user; lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html

#### If VuXML still scares you...

As an easy alternative to writing VuXML, you may opt to add a single line to a different file with much simpler syntax, ``PORTSDIR`/security/portaudit-db/database/portaudit.txt`, which resides within the port `security/portaudit-db`, and send a request for review to the Security Officer Team as described on the FreeBSD Security Information page.

A line in that file consists of four fields separated by `|`, a pipe character. The first field is a &man.pkg.version.1; pattern expression matching the vulnerable packages. The second field contains URLs to relevant information, separated by space characters. The third field is a one-line description of the issue. The fourth and last field is the entry's UUID.

You may want take a closer look at existing entries in `portaudit.txt` before adding your first line to that file.

## Dos and Don'ts

### Introduction

Here is a list of common dos and don'ts that you encounter during the porting process. You should check your own port against this list, but you can also check ports in the PR database that others have submitted. Submit any comments on ports you check as described in Bug Reports and General Commentary. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing.

### Stripping Binaries

Do not strip binaries manually unless you have to. All binaries should be stripped, but the INSTALL_PROGRAM macro will install and strip a binary at the same time (see the next section).

If you need to strip a file, but do not wish to use the INSTALL_PROGRAM macro, ${STRIP_CMD} will strip your program. This is typically done within the `post-install` target. For example:

    post-install:
    	${STRIP_CMD} ${PREFIX}/bin/xdl

Use the &man.file.1; command on the installed executable to check whether the binary is stripped or not. If it does not say `not stripped`, it is stripped. Additionally, &man.strip.1; will not strip a previously stripped program; it will instead exit cleanly.

### INSTALL_* macros

Do use the macros provided in `bsd.port.mk` to ensure correct modes and ownership of files in your own *-install targets.

- INSTALL_PROGRAM is a command to install binary executables.

- INSTALL_SCRIPT is a command to install executable scripts.

- INSTALL_DATA is a command to install sharable data.

- INSTALL_MAN is a command to install manpages and other documentation (it does not compress anything).

These are basically the `install` command with all the appropriate flags. See below for an example on how to use them.

### WRKDIR

Do not write anything to files outside WRKDIR. WRKDIR is the only place that is guaranteed to be writable during the port build (see installing ports from a CDROM for an example of building ports from a read-only tree). If you need to modify one of the `pkg-*` files, do so by redefining a variable, not by writing over it.

### WRKDIRPREFIX

Make sure your port honors WRKDIRPREFIX. Most ports do not have to worry about this. In particular, if you are referring to a WRKDIR of another port, note that the correct location is `WRKDIRPREFIXPORTSDIR/subdir/name/work` not `PORTSDIR/subdir/name/work` or `.CURDIR/../../subdir/name/work` or some such.

Also, if you are defining WRKDIR yourself, make sure you prepend `&dollar;{WRKDIRPREFIX}&dollar;{.CURDIR}` in the front.

### Differentiating operating systems and OS versions

You may come across code that needs modifications or conditional compilation based upon what version of Unix it is running under. If you need to make such changes to the code for conditional compilation, make sure you make the changes as general as possible so that we can back-port code to older FreeBSD systems and cross-port to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD.

The preferred way to tell 4.3BSD/Reno (1990) and newer versions of the BSD code apart is by using the `BSD` macro defined in sys/param.h. Hopefully that file is already included; if not, add the code:

    #if (defined(__unix__) || defined(unix)) && !defined(USG)
    #include <sys/param.h>
    #endif

to the proper place in the `.c` file. We believe that every system that defines these two symbols has `sys/param.h`. If you find a system that does not, we would like to know. Please send mail to the &a.ports;.

Another way is to use the GNU Autoconf style of doing this:

    #ifdef HAVE_SYS_PARAM_H
    #include <sys/param.h>
    #endif

Do not forget to add `-DHAVE_SYS_PARAM_H` to the CFLAGS in the `Makefile` for this method.

Once you have `sys/param.h` included, you may use:

    #if (defined(BSD) && (BSD >= 199103))

to detect if the code is being compiled on a 4.3 Net2 code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 1.1 and below).

Use:

    #if (defined(BSD) && (BSD >= 199306))

to detect if the code is being compiled on a 4.4 code base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or above).

The value of the `BSD` macro is `199506` for the 4.4BSD-Lite2 code base. This is stated for informational purposes only. It should not be used to distinguish between versions of FreeBSD based only on 4.4-Lite vs. versions that have merged in changes from 4.4-Lite2. The `__FreeBSD__` macro should be used instead.

Use sparingly:

- `__FreeBSD__` is defined in all versions of FreeBSD. Use it if the change you are making only affects FreeBSD. Porting gotchas like the use of `sys_errlist[]` vs `strerror()` are Berkeley-isms, not FreeBSD changes.

- In FreeBSD 2.x, `__FreeBSD__` is defined to be `2`. In earlier versions, it is `1`. Later versions always bump it to match their major version number.

- If you need to tell the difference between a FreeBSD 1.x system and a FreeBSD 2.x or above system, usually the right answer is to use the `BSD` macros described above. If there actually is a FreeBSD specific change (such as special shared library options when using `ld`) then it is OK to use `__FreeBSD__` and `#if __FreeBSD__ > 1` to detect a FreeBSD 2.x and later system. If you need more granularity in detecting FreeBSD systems since 2.0-RELEASE you can use the following:

      #if __FreeBSD__ >= 2
      #include <osreldate.h>
      #    if __FreeBSD_version >= 199504
      	 /* 2.0.5+ release specific code here */
      #    endif
      #endif

In the hundreds of ports that have been done, there have only been one or two cases where `__FreeBSD__` should have been used. Just because an earlier port screwed up and used it in the wrong place does not mean you should do so too.

### __FreeBSD_version values

Here is a convenient list of `__FreeBSD_version` values as defined in sys/param.h:

#### __FreeBSD_version values

Release | `__FreeBSD_version`
--- | ---
2.0-RELEASE | 119411
2.1-CURRENT | 199501, 199503
2.0.5-RELEASE | 199504
2.2-CURRENT before 2.1 | 199508
2.1.0-RELEASE | 199511
2.2-CURRENT before 2.1.5 | 199512
2.1.5-RELEASE | 199607
2.2-CURRENT before 2.1.6 | 199608
2.1.6-RELEASE | 199612
2.1.7-RELEASE | 199612
2.2-RELEASE | 220000
2.2.1-RELEASE | 220000 (no change)
2.2-STABLE after 2.2.1-RELEASE | 220000 (no change)
2.2-STABLE after texinfo-3.9 | 221001
2.2-STABLE after top | 221002
2.2.2-RELEASE | 222000
2.2-STABLE after 2.2.2-RELEASE | 222001
2.2.5-RELEASE | 225000
2.2-STABLE after 2.2.5-RELEASE | 225001
2.2-STABLE after ldconfig -R merge | 225002
2.2.6-RELEASE | 226000
2.2.7-RELEASE | 227000
2.2-STABLE after 2.2.7-RELEASE | 227001
2.2-STABLE after &man.semctl.2; change | 227002
2.2.8-RELEASE | 228000
2.2-STABLE after 2.2.8-RELEASE | 228001
3.0-CURRENT before &man.mount.2; change | 300000
3.0-CURRENT after &man.mount.2; change | 300001
3.0-CURRENT after &man.semctl.2; change | 300002
3.0-CURRENT after ioctl arg changes | 300003
3.0-CURRENT after ELF conversion | 300004
3.0-RELEASE | 300005
3.0-CURRENT after 3.0-RELEASE | 300006
3.0-STABLE after 3/4 branch | 300007
3.1-RELEASE | 310000
3.1-STABLE after 3.1-RELEASE | 310001
3.1-STABLE after C++ constructor/destructor order change | 310002
3.2-RELEASE | 320000
3.2-STABLE | 320001
3.2-STABLE after binary-incompatible IPFW and socket changes | 320002
3.3-RELEASE | 330000
3.3-STABLE | 330001
3.3-STABLE after adding &man.mkstemp.3; to libc | 330002
3.4-RELEASE | 340000
3.4-STABLE | 340001
3.5-RELEASE | 350000
3.5-STABLE | 350001
4.0-CURRENT after 3.4 branch | 400000
4.0-CURRENT after change in dynamic linker handling | 400001
4.0-CURRENT after C++ constructor/destructor order change | 400002
4.0-CURRENT after functioning &man.dladdr.3; | 400003
4.0-CURRENT after __deregister_frame_info dynamic linker bug fix (also 4.0-CURRENT after EGCS 1.1.2 integration) | 400004
4.0-CURRENT after &man.suser.9; API change (also 4.0-CURRENT after newbus) | 400005
4.0-CURRENT after cdevsw registration change | 400006
4.0-CURRENT after the addition of so_cred for socket level credentials | 400007
4.0-CURRENT after the addition of a poll syscall wrapper to libc_r | 400008
4.0-CURRENT after the change of the kernel's `dev_t` type to `struct specinfo` pointer | 400009
4.0-CURRENT after fixing a hole in &man.jail.2; | 400010
4.0-CURRENT after the `sigset_t` datatype change | 400011
4.0-CURRENT after the cutover to the GCC 2.95.2 compiler | 400012
4.0-CURRENT after adding pluggable linux-mode ioctl handlers | 400013
4.0-CURRENT after importing OpenSSL | 400014
4.0-CURRENT after the C++ ABI change in GCC 2.95.2 from -fvtable-thunks to -fno-vtable-thunks by default | 400015
4.0-CURRENT after importing OpenSSH | 400016
4.0-RELEASE | 400017
4.0-STABLE after 4.0-RELEASE | 400018
4.0-STABLE after the introduction of delayed checksums. | 400019
4.0-STABLE after merging libxpg4 code into libc. | 400020
4.0-STABLE after upgrading Binutils to 2.10.0, ELF branding changes, and tcsh in the base system. | 400021
4.1-RELEASE | 410000
4.1-STABLE after 4.1-RELEASE | 410001
4.1-STABLE after &man.setproctitle.3; moved from libutil to libc. | 410002
4.1.1-RELEASE | 411000
4.1.1-STABLE after 4.1.1-RELEASE | 411001
4.2-RELEASE | 420000
4.2-STABLE after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. | 420001
4.3-RELEASE | 430000
4.3-STABLE after wint_t introduction. | 430001
4.3-STABLE after PCI powerstate API merge. | 430002
4.4-RELEASE | 440000
4.4-STABLE after d_thread_t introduction. | 440001
4.4-STABLE after mount structure changes (affects filesystem klds). | 440002
4.4-STABLE after the userland components of smbfs were imported. | 440003
4.5-RELEASE | 450000
4.5-STABLE after the usb structure element rename. | 450001
4.5-STABLE after the `sendmail_enable` &man.rc.conf.5; variable was made to take the value `NONE`. | 450004
4.5-STABLE after moving to XFree86 4 by default for package builds. | 450005
4.5-STABLE after accept filtering was fixed so that is no longer susceptible to an easy DoS. | 450006
4.6-RELEASE | 460000
4.6-STABLE &man.sendfile.2; fixed to comply with documentation, not to count any headers sent against the amount of data to be sent from the file. | 460001
4.6.2-RELEASE | 460002
4.6-STABLE | 460100
4.6-STABLE after MFC of `sed -i'. | 460101
4.6-STABLE after MFC of many new pkg_install features from the HEAD. | 460102
4.7-RELEASE | 470000
4.7-STABLE | 470100
Start generated __std{in,out,err}p references rather than __sF. This changes std{in,out,err} from a compile time expression to a runtime one. | 470101
4.7-STABLE after MFC of mbuf changes to replace m_aux mbufs by m_tag's | 470102
4.7-STABLE gets OpenSSL 0.9.7 | 470103
4.8-RELEASE | 480000
4.8-STABLE | 480100
4.8-STABLE after &man.realpath.3; has been made thread-safe | 480101
4.8-STABLE 3ware API changes to twe. | 480102
4.9-RELEASE | 490000
4.9-STABLE | 490100
4.9-STABLE after e_sid was added to struct kinfo_eproc. | 490101
4.9-STABLE after MFC of libmap functionality for rtld. | 490102
4.10-RELEASE | 491000
4.10-STABLE | 491100
4.10-STABLE after MFC of revision 20040629 of the package tools | 491101
4.10-STABLE after VM fix dealing with unwiring of fictitious pages | 491102
4.11-RELEASE | 492000
4.11-STABLE | 492100
5.0-CURRENT | 500000
5.0-CURRENT after adding addition ELF header fields, and changing our ELF binary branding method. | 500001
5.0-CURRENT after kld metadata changes. | 500002
5.0-CURRENT after buf/bio changes. | 500003
5.0-CURRENT after binutils upgrade. | 500004
5.0-CURRENT after merging libxpg4 code into libc and after TASKQ interface introduction. | 500005
5.0-CURRENT after the addition of AGP interfaces. | 500006
5.0-CURRENT after Perl upgrade to 5.6.0 | 500007
5.0-CURRENT after the update of KAME code to 2000/07 sources. | 500008
5.0-CURRENT after ether_ifattach() and ether_ifdetach() changes. | 500009
5.0-CURRENT after changing mtree defaults back to original variant, adding -L to follow symlinks. | 500010
5.0-CURRENT after kqueue API changed. | 500011
5.0-CURRENT after &man.setproctitle.3; moved from libutil to libc. | 500012
5.0-CURRENT after the first SMPng commit. | 500013
5.0-CURRENT after <sys/select.h> moved to <sys/selinfo.h>. | 500014
5.0-CURRENT after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. | 500015
5.0-CURRENT after change allowing libc and libc_r to be linked together, deprecating -pthread option. | 500016
5.0-CURRENT after switch from struct ucred to struct xucred to stabilize kernel-exported API for mountd et al. | 500017
5.0-CURRENT after addition of CPUTYPE make variable for controlling CPU-specific optimizations. | 500018
5.0-CURRENT after moving machine/ioctl_fd.h to sys/fdcio.h | 500019
5.0-CURRENT after locale names renaming. | 500020
5.0-CURRENT after Bzip2 import. Also signifies removal of S/Key. | 500021
5.0-CURRENT after SSE support. | 500022
5.0-CURRENT after KSE Milestone 2. | 500023
5.0-CURRENT after d_thread_t, and moving UUCP to ports. | 500024
5.0-CURRENT after ABI change for descriptor and creds passing on 64 bit platforms. | 500025
5.0-CURRENT after moving to XFree86 4 by default for package builds, and after the new libc strnstr() function was added. | 500026
5.0-CURRENT after the new libc strcasestr() function was added. | 500027
5.0-CURRENT after the userland components of smbfs were imported. | 500028
5.0-CURRENT after the new C99 specific-width integer types were added. | (Not incremented.)
5.0-CURRENT after a change was made in the return value of &man.sendfile.2;. | 500029
5.0-CURRENT after the introduction of the type `fflags_t`, which is the appropriate size for file flags. | 500030
5.0-CURRENT after the usb structure element rename. | 500031
5.0-CURRENT after the introduction of Perl 5.6.1. | 500032
5.0-CURRENT after the `sendmail_enable` &man.rc.conf.5; variable was made to take the value `NONE`. | 500033
5.0-CURRENT after mtx_init() grew a third argument. | 500034
5.0-CURRENT with Gcc 3.1. | 500035
5.0-CURRENT without Perl in /usr/src | 500036
5.0-CURRENT after the addition of &man.dlfunc.3; | 500037
5.0-CURRENT after the types of some struct sockbuf members were changed and the structure was reordered. | 500038
5.0-CURRENT after GCC 3.2.1 import. Also after headers stopped using _BSD_FOO_T_ and started using _FOO_T_DECLARED. This value can also be used as a conservative estimate of the start of &man.bzip2.1; package support. | 500039
5.0-CURRENT after various changes to disk functions were made in the name of removing dependency on disklabel structure internals. | 500040
5.0-CURRENT after the addition of &man.getopt.long.3; to libc. | 500041
5.0-CURRENT after Binutils 2.13 upgrade, which included new FreeBSD emulation, vec, and output format. | 500042
5.0-CURRENT after adding weak pthread_XXX stubs to libc, obsoleting libXThrStub.so. 5.0-RELEASE. | 500043
5.0-CURRENT after branching for RELENG_5_0 | 500100
<sys/dkstat.h> is empty and should not be included. | 500101
5.0-CURRENT after the d_mmap_t interface change. | 500102
5.0-CURRENT after taskqueue_swi changed to run without Giant, and taskqueue_swi_giant added to run with Giant. | 500103
cdevsw_add() and cdevsw_remove() no longer exists. Appearance of MAJOR_AUTO allocation facility. | 500104
5.0-CURRENT after new cdevsw initialization method. | 500105
devstat_add_entry() has been replaced by devstat_new_entry() | 500106
Devstat interface change; see sys/sys/param.h 1.149 | 500107
Token-Ring interface changes. | 500108
Addition of vm_paddr_t. | 500109
5.0-CURRENT after &man.realpath.3; has been made thread-safe | 500110
5.0-CURRENT after &man.usbhid.3; has been synced with NetBSD | 500111
5.0-CURRENT after new NSS implementation and addition of POSIX.1 getpw*_r, getgr*_r functions | 500112
5.0-CURRENT after removal of the old rc system. | 500113
5.1-RELEASE. | 501000
5.1-CURRENT after branching for RELENG_5_1. | 501100
5.1-CURRENT after correcting the semantics of sigtimedwait(2) and sigwaitinfo(2). | 501101
5.1-CURRENT after adding the lockfunc and lockfuncarg fields to &man.bus.dma.tag.create.9;. | 501102
5.1-CURRENT after GCC 3.3.1-pre 20030711 snapshot integration. | 501103
5.1-CURRENT 3ware API changes to twe. | 501104
5.1-CURRENT dynamically-linked /bin and /sbin support and movement of libraries to /lib. | 501105
5.1-CURRENT after adding kernel support for Coda 6.x. | 501106
5.1-CURRENT after 16550 UART constants moved from `<dev/sio/sioreg.h>` to `<dev/ic/ns16550.h>`. Also when libmap functionality was unconditionally supported by rtld. | 501107
5.1-CURRENT after PFIL_HOOKS API update | 501108
5.1-CURRENT after adding kiconv(3) | 501109
5.1-CURRENT after changing default operations for open and close in cdevsw | 501110
5.1-CURRENT after changed layout of cdevsw | 501111
5.1-CURRENT after adding kobj multiple inheritance | 501112
5.1-CURRENT after the if_xname change in struct ifnet | 501113
5.1-CURRENT after changing /bin and /sbin to be dynamically linked | 501114
5.2-RELEASE | 502000
5.2.1-RELEASE | 502010
5.2-CURRENT after branching for RELENG_5_2 | 502100
5.2-CURRENT after __cxa_atexit/__cxa_finalize functions were added to libc. | 502101
5.2-CURRENT after change of default thread library from libc_r to libpthread. | 502102
5.2-CURRENT after device driver API megapatch. | 502103
5.2-CURRENT after getopt_long_only() addition. | 502104
5.2-CURRENT after NULL is made into ((void *)0) for C, creating more warnings. | 502105
5.2-CURRENT after pf is linked to the build and install. | 502106
5.2-CURRENT after time_t is changed to a 64-bit value on sparc64. | 502107
5.2-CURRENT after Intel C/C++ compiler support in some headers and execve(2) changes to be more strictly conforming to POSIX. | 502108
5.2-CURRENT after the introduction of the bus_alloc_resource_any API | 502109
5.2-CURRENT after the addition of UTF-8 locales | 502110
5.2-CURRENT after the removal of the getvfsent(3) API | 502111
5.2-CURRENT after the addition of the .warning directive for make. | 502112
5.2-CURRENT after ttyioctl() was made mandatory for serial drivers. | 502113
5.2-CURRENT after import of the ALTQ framework. | 502114
5.2-CURRENT after changing sema_timedwait(9) to return 0 on success and a non-zero error code on failure. | 502115
5.2-CURRENT after changing kernel dev_t to be pointer to struct cdev *. | 502116
5.2-CURRENT after changing kernel udev_t to dev_t. | 502117
5.2-CURRENT after adding support for CLOCK_VIRTUAL and CLOCK_PROF to clock_gettime(2) and clock_getres(2). | 502118
5.2-CURRENT after changing network interface cloning overhaul. | 502119
5.2-CURRENT after the update of the package tools to revision 20040629. | 502120
5.2-CURRENT after marking Bluetooth code as non-i386 specific. | 502121
5.2-CURRENT after the introduction of the KDB debugger framework, the conversion of DDB into a backend and the introduction of the GDB backend. | 502122
5.2-CURRENT after change to make VFS_ROOT take a struct thread argument as does vflush. Struct kinfo_proc now has a user data pointer. The switch of the default X implementation to `xorg` was also made at this time. | 502123
5.2-CURRENT after the change to separate the way ports rc.d and legacy scripts are started. | 502124
5.2-CURRENT after the backout of the previous change. | 502125
5.2-CURRENT after the removal of kmem_alloc_pageable() and the import of gcc 3.4.2. | 502126
5.2-CURRENT after changing the UMA kernel API to allow ctors/inits to fail. | 502127
5.2-CURRENT after the change of the vfs_mount signature as well as global replacement of PRISON_ROOT with SUSER_ALLOWJAIL for the suser(9) API. | 502128
5.3-BETA/RC before the pfil API change | 503000
5.3-RELEASE | 503001
5.3-STABLE after branching for RELENG_5_3 | 503100
5.3-STABLE after addition of glibc style &man.strftime.3; padding options. | 503101
5.3-STABLE after OpenBSD's nc(1) import MFC. | 503102
5.4-PRERELEASE after the MFC of the fixes in `<src/include/stdbool.h>` and `<src/sys/i386/include/_types.h>` for using the GCC-compatibility of the Intel C/C++ compiler. | 503103
5.4-PRERELEASE after the MFC of the change of ifi_epoch from wall clock time to uptime. | 503104
5.4-PRERELEASE after the MFC of the fix of EOVERFLOW check in vswprintf(3). | 503105
5.4-RELEASE. | 504000
5.4-STABLE after branching for RELENG_5_4 | 504100
5.4-STABLE after increasing the default thread stacksizes | 504101
6.0-CURRENT | 600000
6.0-CURRENT after permanently enabling PFIL_HOOKS in the kernel. | 600001
6.0-CURRENT after initial addition of ifi_epoch to struct if_data. Backed out after a few days. Do not use this value. | 600002
6.0-CURRENT after the re-addition of the ifi_epoch member of struct if_data. | 600003
6.0-CURRENT after addition of the struct inpcb argument to the pfil API. | 600004
6.0-CURRENT after addition of the "-d DESTDIR" argument to newsyslog. | 600005
6.0-CURRENT after addition of glibc style &man.strftime.3; padding options. | 600006
6.0-CURRENT after addition of 802.11 framework updates. | 600007
6.0-CURRENT after changes to VOP_*VOBJECT() functions and introduction of MNTK_MPSAFE flag for Giantfree filesystems. | 600008
6.0-CURRENT after addition of the cpufreq framework and drivers. | 600009
6.0-CURRENT after importing OpenBSD's nc(1). | 600010
6.0-CURRENT after removing semblance of SVID2 `matherr()` support. | 600011
6.0-CURRENT after increase of default thread stacks' size. | 600012
6.0-CURRENT after fixes in `<src/include/stdbool.h>` and `<src/sys/i386/include/_types.h>` for using the GCC-compatibility of the Intel C/C++ compiler. | 600013
6.0-CURRENT after EOVERFLOW checks in vswprintf(3) fixed. | 600014
6.0-CURRENT after changing the struct if_data member, ifi_epoch, from wall clock time to uptime. | 600015
6.0-CURRENT after LC_CTYPE disk format changed. | 600016
6.0-CURRENT after NLS catalogs disk format changed. | 600017
6.0-CURRENT after LC_COLLATE disk format changed. | 600018
Installation of acpica includes into /usr/include. | 600019
Addition of MSG_NOSIGNAL flag to send(2) API. | 600020
Addition of fields to cdevsw | 600021
Removed gtar from base system. | 600022
LOCAL_CREDS, LOCAL_CONNWAIT socket options added to unix(4). | 600023
&man.hwpmc.4; and related tools added to 6.0-CURRENT. | 600024
struct icmphdr added to 6.0-CURRENT. | 600025
pf updated to 3.7. | 600026
Kernel libalias and ng_nat introduced. | 600027

Note that 2.2-STABLE sometimes identifies itself as 2.2.5-STABLE after the 2.2.5-RELEASE. The pattern used to be year followed by the month, but we decided to change it to a more straightforward major/minor system starting from 2.2. This is because the parallel development on several branches made it infeasible to classify the releases simply by their real release dates. If you are making a port now, you do not have to worry about old -CURRENTs; they are listed here just for your reference.

### Writing something after `bsd.port.mk`

Do not write anything after the `.include <bsd.port.mk>` line. It usually can be avoided by including `bsd.port.pre.mk` somewhere in the middle of your `Makefile` and `bsd.port.post.mk` at the end.

You need to include either the `bsd.port.pre.mk`/`bsd.port.post.mk` pair or `bsd.port.mk` only; do not mix these two usages.

`bsd.port.pre.mk` only defines a few variables, which can be used in tests in the `Makefile`, `bsd.port.post.mk` defines the rest.

Here are some important variables defined in `bsd.port.pre.mk` (this is not the complete list, please read `bsd.port.mk` for the complete list).

Variable | Description
--- | ---
ARCH | The architecture as returned by `uname -m` (e.g., `i386`)
OPSYS | The operating system type, as returned by `uname -s` (e.g., `FreeBSD`)
OSREL | The release version of the operating system (e.g., `2.1.5` or `2.2.7`)
OSVERSION | The numeric version of the operating system; the same as `__FreeBSD_version`.
PORTOBJFORMAT | The object format of the system (`elf` or `aout`; note that for modern versions of FreeBSD, `aout` is deprecated.)
LOCALBASE | The base of the local tree (e.g., `/usr/local/`)
X11BASE | The base of the X11 tree (e.g., `/usr/X11R6`)
PREFIX | Where the port installs itself (see more on PREFIX).

If you have to define the variables USE_IMAKE, USE_X_PREFIX, or MASTERDIR, do so before including `bsd.port.pre.mk`.

Here are some examples of things you can write after `bsd.port.pre.mk`:

    # no need to compile lang/perl5 if perl5 is already in system
    .if ${OSVERSION} > 300003
    BROKEN= perl is in system
    .endif

    # only one shlib version number for ELF
    .if ${PORTOBJFORMAT} == "elf"
    TCL_LIB_FILE=  ${TCL_LIB}.${SHLIB_MAJOR}
    .else
    TCL_LIB_FILE=  ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
    .endif

    # software already makes link for ELF, but not for a.out
    post-install:
    .if ${PORTOBJFORMAT} == "aout"
           ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
    .endif

You did remember to use tab instead of spaces after `BROKEN=` and `TCL_LIB_FILE=`, did you not? :-).

### Install additional documentation

If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under `PREFIX/share/doc`. This can be done, like the previous item, in the post-install target.

Create a new directory for your port. The directory name should reflect what the port is. This usually means PORTNAME. However, if you think the user might want different versions of the port to be installed at the same time, you can use the whole PKGNAME.

Make the installation dependent on the variable NOPORTDOCS so that users can disable it in `/etc/make.conf`, like this:

    post-install:
    .if !defined(NOPORTDOCS)
    	${MKDIR} ${DOCSDIR}
    	${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR}
    .endif

Here are some handy variables and how they are expanded by default when used in the `Makefile`:

- DATADIR gets expanded to `PREFIX/share/PORTNAME`.

- DOCSDIR gets expanded to `PREFIX/share/doc/PORTNAME`.

- EXAMPLESDIR gets expanded to `PREFIX/share/examples/PORTNAME`.

These variables are exported to PLIST_SUB. Their values will appear there as pathnames relative to `PREFIX` if possible. That is, `share/doc/PORTNAME` will be substituted for `%%DOCSDIR%%` in the packing list by default, and so on. (See more on `pkg-plist` substitution here.)

All documentation files and directories installed should be included in `pkg-plist` with the `%%PORTDOCS%%` prefix, for example:

    %%PORTDOCS%%%%DOCSDIR%%/AUTHORS
    %%PORTDOCS%%%%DOCSDIR%%/CONTACT
    %%PORTDOCS%%@dirrm %%DOCSDIR%%

As an alternative to enumerating the documentation files in `pkg-plist`, a port can set the variable PORTDOCS to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to DOCSDIR. Therefore, a port that utilizes PORTDOCS and uses a non-default location for its documentation should set DOCSDIR accordingly. If a directory is listed in PORTDOCS or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. PORTDOCS should not be set if NOPORTDOCS is in effect. Installing the documentation at PORTDOCS as shown above remains up to the port itself. A typical example of utilizing PORTDOCS looks as follows:

    .if !defined(NOPORTDOCS)
            PORTDOCS=       *
    .endif

You can also use the `pkg-message` file to display messages upon installation. See the section on using `pkg-message` for details. The `pkg-message` file does not need to be added to `pkg-plist`.

### Subdirectories

Try to let the port put things in the right subdirectories of PREFIX. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in the a subdirectory of `lib`, which does not work well with the BSD paradigm. Many of the files should be moved to one of the following: `etc` (setup/configuration files), `libexec` (executables started internally), `sbin` (executables for superusers/managers), `info` (documentation for info browser) or `share` (architecture independent files). See &man.hier.7; for details; the rules governing `/usr` pretty much apply to `/usr/local` too. The exception are ports dealing with USENET news. They may use `PREFIX/news` as a destination for their files.

### Cleaning up empty directories

Do make your ports clean up after themselves when they are de-installed. This is usually accomplished by adding `@dirrm` lines for all directories that are specifically created by the port. You need to delete subdirectories before you can delete parent directories.

     :
    lib/X11/oneko/pixmaps/cat.xpm
    lib/X11/oneko/sounds/cat.au
     :
    @dirrm lib/X11/oneko/pixmaps
    @dirrm lib/X11/oneko/sounds
    @dirrm lib/X11/oneko

However, sometimes `@dirrm` will give you errors because other ports also share the same subdirectory. You can call `rmdir` from `@unexec` to remove only empty directories without warning.

    @unexec rmdir %D/share/doc/gimp 2>/dev/null || true

This will neither print any error messages nor cause &man.pkg.delete.1; to exit abnormally even if `PREFIX/share/doc/gimp` is not empty due to other ports installing some files in there.

### UIDs and GIDs

If your port requires a certain user to be on the installed system, let the `pkg-install` script call `pw` to create it automatically. Look at `net/cvsup-mirror` for an example.

If your port must use the same user/group ID number when it is installed as a binary package as when it was compiled, then you must choose a free UID from 50 to 999 and register it below. Look at `japanese/Wnn6` for an example.

Make sure you do not use a UID already used by the system or other ports.

This is the current list of UIDs between 50 and 999.

    bind:*:53:53:Bind Sandbox:/:/sbin/nologin
    majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
    rdfdb:*:55:55:rdfDB Daemon:/var/db/rdfdb:/bin/sh
    spamd:*:58:58:SpamAssassin user:/var/spool/spamd:/sbin/nologin
    cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
    gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
    proxy:*:62:62:Packet Filter pseudo-user:/nonexistent:/nonexistent
    uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
    xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent
    pop:*:68:6:Post Office Owner (popper):/nonexistent:/sbin/nologin
    wnn:*:69:7:Wnn:/nonexistent:/nonexistent
    pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
    oracle:*:71:71::0:0:Oracle:/usr/local/oracle7:/sbin/nologin
    ircd:*:72:72:IRC daemon:/nonexistent:/nonexistent
    ircservices:*:73:73:IRC services:/nonexistent:/nonexistent
    ifmail:*:75:66:Ifmail user:/nonexistent:/nonexistent
    www:*:80:80:World Wide Web Owner:/nonexistent:/sbin/nologin
    alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
    qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
    qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
    qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
    qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
    qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
    qmails:*:87:82:QMail user:/var/qmail:/nonexistent
    mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin
    vpopmail:*:89:89:VPop Mail User:/usr/local/vpopmail:/nonexistent
    firebird:*:90:90:Firebird Database Administrator:/usr/local/firebird:/bin/sh
    mailman:*:91:91:Mailman User:/usr/local/mailman:/sbin/nologin
    gdm:*:92:92:GDM Sandbox:/:/sbin/nologin
    jabber:*:93:93:Jabber Daemon:/nonexistent:/nonexistent
    p4admin:*:94:94:Perforce admin:/usr/local/perforce:/sbin/nologin
    interch:*:95:95:Interchange user:/usr/local/interchange:/sbin/nologin
    squeuer:*:96:96:SQueuer Owner:/nonexistent:/bin/sh
    mud:*:97:97:MUD Owner:/nonexistent:/bin/sh
    msql:*:98:98:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh
    rscsi:*:99:99:Remote SCSI:/usr/local/rscsi:/usr/local/sbin/rscsi
    squid:*:100:100:squid caching-proxy pseudo user:/usr/local/squid:/sbin/nologin
    quagga:*:101:101:Quagga route daemon pseudo user:/usr/local/etc/quagga:/sbin/nologin
    ganglia:*:102:102:Ganglia User:/nonexistent:/sbin/nologin
    sgeadmin:*:103:103:Sun Grid Engine Admin:/nonexistent:/sbin/nologin
    slimserv:*:104:104:Slim Devices SlimServer pseudo-user:/nonexistent:/sbin/nologin
    dnetc:*:105:105:distributed.net client and proxy pseudo-user:/nonexistent:/sbin/nologin
    clamav:*:106:106:Clamav Antivirus:/nonexistent:/sbin/nologin
    cacti:*:107:107:Cacti Sandbox:/nonexistent:/sbin/nologin
    webkit:*:108:108:WebKit Default User:/usr/local/www/webkit:/bin/sh
    quickml:*:109:109:quickml Server:/nonexistent:/sbin/nologin
    vscan:*:110:110:Scanning Virus Account:/var/amavis:/bin/sh
    fido:*:111:111:Fido System:/usr/local/fido:/bin/sh
    dcc:*:112:112:Distributed Checksum Clearinghouse:/nonexistent:/sbin/nologin
    amavis:*:113:113:Amavis-stats Account:/nonexistent:/sbin/nologin
    dhis:*:114:114:DHIS Daemon:/nonexistent:/sbin/nologin
    _symon:*:115:115:Symon Account:/var/empty:/sbin/nologin
    postfix:*:125:125:Postfix Mail System:/var/spool/postfix:/sbin/nologin
    rbldns:*:153:153:rbldnsd pseudo-user:/nonexistent:/sbin/nologin
    sfs:*:171:171:Self-Certifying File System:/nonexistent:/sbin/nologin
    agk:*:172:172:AquaGateKeeper:/nonexistent:/nonexistent
    polipo:*:173:173:polipo web cache:/nonexistent:/sbin/nologin
    moinmoin:*:192:192:MoinMoin User:/nonexistent:/sbin/nologin
    sympa:*:200:200:Sympa Owner:/nonexistent:/sbin/nologin
    dspam:*:202:202:Dspam:/nonexistent:/sbin/nologin
    _tor:*:256:256:Tor anonymising router:/var/db/tor:/bin/sh
    ldap:*:389:389:OpenLDAP Server:/nonexistent:/sbin/nologin
    drweb:*:426:426:Dr.Web Mail Scanner:/nonexistent:/sbin/nologin
    courier:*:465:465:Courier Mail Server:/nonexistent:/sbin/nologin
    _bbstored:*:505:505::0:0:BoxBackup Store Daemon:/nonexistent:/bin/sh
    qtss:*:554:554:Darwin Streaming Server:/nonexistent:/sbin/nologin
    ircdru:*:555:555:Russian hybrid IRC server:/nonexistent:/bin/sh
    messagebus:*:556:556:D-BUS Daemon User:/nonexistent:/sbin/nologin
    bnetd:*:700:700:Bnetd user:/nonexistent:/sbin/nologin
    bopm:*:717:717:Blitzed Open Proxy Monitor:/nonexistent:/bin/sh
    bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologin

This is the current list of reserved GIDs.

    bind:*:53:
    rdfdb:*:55:
    spamd:*:58:
    cyrus:*:60:
    proxy:*:62:
    authpf:*:63:
    uucp:*:66:
    xten:*:67:
    dialer:*:68:
    network:*:69:
    pgsql:*:70:
    www:*:80:
    qnofiles:*:81:
    qmail:*:82:
    mysql:*:88:
    vpopmail:*:89:
    firebird:*:90:
    mailman:*:91:
    gdm:*:92:
    jabber:*:93:
    p4admin:*:94:
    interch:*:95:
    squeuer:*:96:
    mud:*:97:
    msql:*:98:
    rscsi:*:99:
    squid:*:100:
    quagga:*:101:
    ganglia:*:102:
    sgeadmin:*:103:
    slimserv:*:104:
    dnetc:*:105:
    clamav:*:106:
    cacti:*:107:
    webkit:*:108:
    quickml:*:109:
    vscan:*:110:
    fido:*:111:
    dcc:*:112:
    amavis:*:113:
    dhis:*:114:
    _symon:*:115:
    postfix:*:125:
    maildrop:*:126:
    rbldns:*:153:
    sfs:*:171:
    agk:*:172:
    polipo:*:173:
    moinmoin:*:192:
    sympa:*:200:
    dspam:*:202:
    _tor:*:256:
    ldap:*:389:
    drweb:*:426:
    courier:*:465:
    _bbstored:*:505:
    qtss:*:554:
    ircdru:*:555:
    messagebus:*:556:
    realtime:*:557:
    bnetd:*:700:
    bopm:*:717:
    bacula:*:910:

Please include a notice when you submit a port (or an upgrade) that reserves a new UID or GID in this range. This allows us to keep the list of reserved IDs up to date.

### Do things rationally

The `Makefile` should do things simply and reasonably. If you can make it a couple of lines shorter or more readable, then do so. Examples include using a make `.if` construct instead of a shell `if` construct, not redefining do-extract if you can redefine EXTRACT* instead, and using GNU_CONFIGURE instead of `CONFIGURE_ARGS += --prefix=&dollar;{PREFIX}`.

If you find yourself having to write a lot of new code to try to do something, please go back and review `bsd.port.mk` to see if it contains an existing implementation of what you are trying to do. While hard to read, there are a great many seemingly-hard problems for which `bsd.port.mk` already provides a shorthand solution.

### Respect both CC and CXX

The port should respect both CC and CXX variables. What we mean by this is that the port should not set the values of these variables absolutely, overriding existing values; instead, it should append whatever values it needs to the existing values. This is so that build options that affect all ports can be set globally.

If the port does not respect these variables, please add `NO_PACKAGE=ignores either cc or cxx` to the `Makefile`.

An example of a `Makefile` respecting both CC and CXX variables follows. Note the ?=:

    CC?= gcc

    CXX?= g++

Here is an example which respects neither CC nor CXX variables:

    CC= gcc

    CXX= g++

Both CC and CFLAGS variables can be defined on FreeBSD systems in `/etc/make.conf`. The first example defines a value if it was not previously set in `/etc/make.conf`, preserving any system-wide definitions. The second example clobbers anything previously defined.

### Respect CFLAGS

The port should respect the CFLAGS variable. What we mean by this is that the port should not set the value of this variable absolutely, overriding the existing value; instead, it should append whatever values it needs to the existing value. This is so that build options that affect all ports can be set globally.

If it does not, please add `NO_PACKAGE=ignores cflags` to the `Makefile`.

An example of a `Makefile` respecting the CFLAGS variable follows. Note the +=:

    CFLAGS+= -Wall -Werror

Here is an example which does not respect the CFLAGS variable:

    CFLAGS= -Wall -Werror

The CFLAGS variable is defined on FreeBSD systems in `/etc/make.conf`. The first example appends additional flags to the CFLAGS variable, preserving any system-wide definitions. The second example clobbers anything previously defined.

You should remove optimization flags from the third party `Makefile`s. System CFLAGS contains system-wide optimization flags. An example from an unmodified `Makefile`:

    CFLAGS= -O3 -funroll-loops -DHAVE_SOUND

Using system optimization flags, the `Makefile` would look similar to the following example:

    CFLAGS+= -DHAVE_SOUND

### Configuration files

If your port requires some configuration files in `PREFIX/etc`, do not just install them and list them in `pkg-plist`. That will cause &man.pkg.delete.1; to delete files carefully edited by the user and a new installation to wipe them out.

Instead, install sample files with a suffix (`filename.sample` will work well) and print out a message pointing out that the user has to copy and edit the file before the software can be made to work.

### Feedback

Do send applicable changes/patches to the original author/maintainer for inclusion in next release of the code. This will only make your job that much easier for the next release.

### `README.html`

Do not include the `README.html` file. This file is not part of the cvs collection but is generated using the `make readme` command.

### Marking a port BROKEN, FORBIDDEN, or otherwise not installable

In certain cases users should be prevented from installing a port. For instance, there may come a time when a particular port will contain a security vulnerability, will be radically broken and needs many hours of tender loving care, or is generally obsoleted, but for one reason or another should remain in the tree (and get fixed, right?). To tell a user that a port should not be installed, there are several `make` variables that can be used in a port's `Makefile`. The value of the following `make` variables will be the reason that is given back to users for why the port refuses to install itself. Please use the correct `make` variable as each make variable conveys radically different meanings to both users, and to automated systems that depend on the `Makefile`s, such as the ports build cluster, FreshPorts, and portsmon.

- BROKEN is reserved for ports that do not compile or install. This will prevent users from wasting their time trying to install the port. The build cluster will still attempt to try to build them to see if the underlying problem has been resolved.

- FORBIDDEN is used for ports that do contain a security vulnerability or induce grave concern regarding the security of a FreeBSD system with a given port installed (ex: a reputably insecure program or a program that provides easily exploitable services). Ports should be marked as FORBIDDEN as soon as a particular piece of software has a vulnerability and there is no released upgrade. Ideally ports should be upgraded as soon as possible when a security vulnerability is discovered so as to reduce the number of vulnerable FreeBSD hosts (we like being known for being secure), however sometimes there is a noticeable time gap between disclosure of a vulnerability and an updated release of the vulnerable software. Do not mark a port FORBIDDEN for any reason other than security.

- IGNORE is reserved for ports that should not be built for some other reason. The build cluster will not, under any circumstances, build ports marked as IGNORE. For instance, use IGNORE when a port:

  - compiles but does not run properly

  - does not work on the installed version of &os;

  - requires &os; kernel sources to build, but the user does not have them installed

  - has a distfile which may not be automatically fetched due to licensing restrictions

  - does not work with a currently installed port

  If a port would conflict with a currently installed port, use CONFLICTS instead. CONFLICTS will set IGNORE by itself.

  If a port sould be marked IGNORE only on certain architectures, there are two other convenience variables that will automatically set IGNORE for you: ONLY_FOR_ARCHS and NOT_FOR_ARCHS. Examples:

      ONLY_FOR_ARCHS= i386 amd64

      NOT_FOR_ARCHS= alpha ia64 sparc64

Do remember that BROKEN and FORBIDDEN are to be used as a last resort if a port is not upgradeable. Permanently broken ports should be removed from the tree entirely.

When it makes sense to do so, users can be warned about a pending port removal with DEPRECATED and EXPIRATION_DATE. The former is simply a string stating why the port is scheduled for removal; the latter is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown to the user.

It is possible to set DEPRECATED without an EXPIRATION_DATE (for instance, recommending a newer version of the port), but the converse does not make any sense.

There is no set policy on how much notice to give. Current practice seems to be one month for security-related issues and two months for build issues. This also gives any interested committers a little time to fix the problems.

### Necessary workarounds

Sometimes it is necessary to work around bugs in software included with older versions of &os;.

- Some versions of &man.make.1; were broken on at least 4.8 and 5.0 with respect to handling comparisons based on OSVERSION. This would often lead to failures during `make describe` (and thus, the overall ports `make index`). The workaround is to enclose the conditional comparison in spaces, e.g.:

      if ( ${OSVERSION} > 500023 )

  Be aware that test-installing a port on 4.9 or 5.2 will not detect this problem.

### Miscellanea

The files `pkg-descr` and `pkg-plist` should each be double-checked. If you are reviewing a port and feel they can be worded better, do so.

Do not copy more copies of the GNU General Public License into our system, please.

Please be careful to note any legal issues! Do not let us illegally distribute software!

### If you are stuck…

Do look at existing examples and the `bsd.port.mk` file before asking us questions! ;-)

Do ask us questions if you have any trouble! Do not just beat your head against a wall! :-)

## A Sample `Makefile`

Here is a sample `Makefile` that you can use to create a new port. Make sure you remove all the extra comments (ones between brackets)!

It is recommended that you follow this format (ordering of variables, empty lines between sections, etc.). This format is designed so that the most important information is easy to locate. We recommend that you use portlint to check the `Makefile`.

    [the header...just to make it easier for us to identify the ports.]
    # New ports collection makefile for:   xdvi
    [the "version required" line is only needed when the PORTVERSION
     variable is not specific enough to describe the port.]
    # Date created:                26 May 1995
    [this is the person who did the original port to FreeBSD, in particular, the
    person who wrote the first version of this Makefile.  Remember, this should
    not be changed when upgrading the port later.]
    # Whom:                        Satoshi Asami <asami@FreeBSD.org>
    #
    # &dollar;FreeBSD&dollar;
    [ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS
    when it is committed to our repository.  If upgrading a port, do not alter
    this line back to "&dollar;FreeBSD&dollar;".  CVS deals with it automatically.]
    #

    [section to describe the port itself and the master site - PORTNAME
     and PORTVERSION are always first, followed by CATEGORIES,
     and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
     PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that.
     Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then
     EXTRACT_ONLY, as necessary.]
    PORTNAME=      xdvi
    PORTVERSION=   18.2
    CATEGORIES=    print
    [do not forget the trailing slash ("/")!
     if you are not using MASTER_SITE_* macros]
    MASTER_SITES=  ${MASTER_SITE_XCONTRIB}
    MASTER_SITE_SUBDIR= applications
    PKGNAMEPREFIX= ja-
    DISTNAME=      xdvi-pl18
    [set this if the source is not in the standard ".tar.gz" form]
    EXTRACT_SUFX=  .tar.Z

    [section for distributed patches -- can be empty]
    PATCH_SITES=   ftp://ftp.sra.co.jp/pub/X11/japanese/
    PATCHFILES=    xdvi-18.patch1.gz xdvi-18.patch2.gz

    [maintainer; *mandatory*!  This is the person (preferably with commit
     privileges) whom a user can contact for questions and bug reports - this
     person should be the porter or someone who can forward questions to the
     original porter reasonably promptly.  If you really do not want to have
     your address here, set it to "ports@FreeBSD.org".]
    MAINTAINER=    asami@FreeBSD.org
    COMMENT=       A DVI Previewer for the X Window System

    [dependencies -- can be empty]
    RUN_DEPENDS=   gs:${PORTSDIR}/print/ghostscript
    LIB_DEPENDS=   Xpm.5:${PORTSDIR}/graphics/xpm

    [this section is for other standard bsd.port.mk variables that do not
     belong to any of the above]
    [If it asks questions during configure, build, install...]
    IS_INTERACTIVE=        yes
    [If it extracts to a directory other than ${DISTNAME}...]
    WRKSRC=                ${WRKDIR}/xdvi-new
    [If the distributed patches were not made relative to ${WRKSRC}, you
     may need to tweak this]
    PATCH_DIST_STRIP=      -p1
    [If it requires a "configure" script generated by GNU autoconf to be run]
    GNU_CONFIGURE= yes
    [If it requires GNU make, not /usr/bin/make, to build...]
    USE_GMAKE=     yes
    [If it is an X application and requires "xmkmf -a" to be run...]
    USE_IMAKE=     yes
    [et cetera.]

    [non-standard variables to be used in the rules below]
    MY_FAVORITE_RESPONSE=  "yeah, right"

    [then the special rules, in the order they are called]
    pre-fetch:
    	i go fetch something, yeah

    post-patch:
    	i need to do something after patch, great

    pre-install:
    	and then some more stuff before installing, wow

    [and then the epilogue]
    .include <bsd.port.mk>

## Automated package list creation

First, make sure your port is almost complete, with only `pkg-plist` missing.

Next, create a temporary directory tree into which your port can be installed, and install any dependencies. port-type should be `local` for non-X ports and `x11-4` or `x11` for ports which install into the directory hierarchy of XFree86 4 or an earlier XFree86 release, respectively.

    &prompt.root; mkdir /var/tmp/port-name
    &prompt.root; mtree -U -f /etc/mtree/BSD.port-type.dist -d -e -p /var/tmp/port-name
    &prompt.root; make depends PREFIX=/var/tmp/port-name

Store the directory structure in a new file.

    &prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort > OLD-DIRS

Create an empty `pkg-plist` file:

    &prompt.root; touch pkg-plist

If your port honors PREFIX (which it should) you can then install the port and create the package list.

    &prompt.root; make install PREFIX=/var/tmp/port-name
    &prompt.root; (cd /var/tmp/port-name && find -d * \! -type d) | sort > pkg-plist

You must also add any newly created directories to the packing list.

    &prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort | comm -13 OLD-DIRS - | sort -r | sed -e 's#^#@dirrm #' >> pkg-plist

Finally, you need to tidy up the packing list by hand; it is not all automated. Manual pages should be listed in the port's `Makefile` under MANn, and not in the package list. User configuration files should be removed, or installed as `filename.sample`. The `info/dir` file should not be listed and appropriate `install-info` lines should be added as noted in the info files section. Any libraries installed by the port should be listed as specified in the shared libraries section.

Alternatively, use the `plist` script in `/usr/ports/Tools/scripts/` to build the package list automatically. The first step is the same as above: take the first three lines, that is, `mkdir`, `mtree` and `make depends`. Then build and install the port:

    &prompt.root; make install PREFIX=/var/tmp/port-name

And let `plist` create the `pkg-plist` file:

    &prompt.root; /usr/ports/Tools/scripts/plist -Md -m /etc/mtree/BSD.port-type.dist /var/tmp/port-name > pkg-plist

The packing list still have to tidied up the by hand as stated above.

## Keeping Up

The &os; Ports Collection is constantly changing. Here is some information on how to keep up.

### FreshPorts

One of the easiest ways to learn about updates that have already been committed is by subscribing to FreshPorts. You can select multiple ports to monitor. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other &os; committer has made. (These are often necessary to keep up with changes in the underlying ports framework—although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or just simply impractical. Also, in some cases, the changes are very minor in nature. We expect everyone to use their best judgement in these cases.)

If you wish to use FreshPorts, all you need is an account. If your registered email address is `@FreeBSD.org`, you will see the opt-in link on the right hand side of the webpages. For those of you who already have a FreshPorts account, but are not using your `@FreeBSD.org` email address, just change your email to `@FreeBSD.org`, subscribe, then change it back again.

FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, you will be notified of any errors which FreshPorts detects during sanity testing of your commits.

### The Web Interface to the Source Repository

It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the CHANGES file. Changes that affect individual ports are now documented in the UPDATING file. However, the definitive answer to any question is undoubtedly to read the source code of bsd.port.mk, and associated files.

### The &os; Ports Mailing List

If you maintain ports, you should consider following the &a.ports;. Important changes to the way ports work will be announced there, and then committed to `CHANGES`.

### The &os; Port Building Cluster on pointyhat.FreeBSD.org

One of the least-publicized strengths of &os; is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. You can find the results of these builds at package building logs and errors.

Individual ports are built unless they are specifically marked with IGNORE. Ports that are marked with BROKEN will still be attempted, to see if the underlying problem has been resolved. (This is done by passing TRYBROKEN to the port's `Makefile`.)

### The &os; Port Distfile Survey

The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. The FreeBSD Ports distfiles survey attempts to query every download site for every port to find out if each distfile is still currently available. Maintainers are asked to check this report periodically, not only to speed up the building process for users, but to help avoid wasting bandwidth of the sites that volunteer to host all these distfiles.

### The &os; Ports Monitoring System

Another handy resource is the FreeBSD Ports Monitoring System (also known as `portsmon`). This system comprises a database that processes information from several sources and allows its to be browsed via a web interface. Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. In the future, this will be expanded to include the distfile survey, as well as other sources.

To get started, you can view all information about a particular port by using the Overview of One Port.

As of this writing, this is the only resource available that maps GNATS PR entries to portnames. (PR submitters do not always include the portname in their Synopsis, although we would prefer that they did.) So, `portsmon`) is a good place to start if you want to find out whether an existing port has any PRs filed against it and/or any build errors; or, to find out if a new port that you may be thinking about creating has already been submitted.