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

A well-written pkg-descr describes the port completely enough that users would not have to consult the documentation or visit the website to understand what the software does, how it can be useful, or what particularly nice features it has. Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime environment, or implementation languages help users decide whether this port will work for them.

Include a URL to the official WWW homepage. Prepend one of the websites (pick the most common one) with WWW: (followed by single space) so that automated tools will work correctly. If the URI is the root of the website or directory, it should be terminated with a slash.

The following example shows how your pkg-descr should look:

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. If the port creates directories during installation, make sure to add @dirrm lines to remove them when the package is deleted.

Here is a small example:

Refer to the pkg-create(8) manual page for details on the packing list.

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:

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 pkg-create(8). 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 fulfill more sophisticated tasks.

When all the files have been modified, use make makepatch from the port directory to write updated patch files to the files directory of the port.

Patches are saved into files named patch-* where * indicates the pathname of the file that is patched, such as patch-Imakefile or patch-src-config.h.

After the file has been modified, diff(1) is used to record the differences between the original and the modified version. -u causes diff(1) to produce “unified” diffs, the preferred form.

When generating patches for new, added files, -N is added to tell diff(1) to treat the non-existent original file as if it existed but was empty:

Patch files are stored in PATCHDIR (usually files/, from where they will be automatically applied. All patches must be relative to WRKSRC (generally the directory the port's tarball unpacks itself into, that being where the build is done). To make fixes and upgrades easier, avoid having more than one patch fix the same file (that is, patch-file and patch-file2 both changing WRKSRC/foobar.c). Note that in the path of a patched file the / are to be replaced with two underscores __. For example, to patch a file named src/freeglut_joystick.c, the corresponding patch should be named patch-src__freeglut_joystick.c.

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

Do not put RCS strings in patches. Subversion 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 ($) signs, and typically start with $Id or $RCS.

Using the recurse (-r) option to diff(1) to generate patches is fine, but please look at the resulting patches to make sure there is no unnecessary junk in there. In particular, diffs between two backup files, Makefiles when the port uses Imake or GNU configure, etc., are unnecessary and should be deleted. If it was necessary 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!). Instead, define USE_AUTOTOOLS=autoconf:261 and take the diffs of configure.in.

Try to minimize the amount of non-functional whitespace changes in patches. It is common in the Open Source world for projects to share large amounts of a code base, but obey different style and indenting rules. When taking a working piece of functionality from one project to fix similar areas in another, please be careful: the resulting line patch may be full of non-functional changes. It not only increases the size of the Subversion repository but makes it hard to find out what exactly caused the problem and what was changed at all.

If a file must be deleted, do it in the post-extract target rather than as part of the patch.

Simple replacements can be performed directly from the port Makefile using the in-place mode of sed(1). This is useful when changes use the value of a variable:

Quite often, software being ported uses the CR/LF convention in source files. This may cause problems with further patching, compiler warnings, or script execution (like /bin/sh^M not found.) To quickly convert all files from CR/LF to just LF, add this entry to the port Makefile:

A list of specific files to convert can be given:

Use DOS2UNIX_REGEX to convert a group of files across subdirectories. Its argument is a find(1)-compatible regular expression. More on the format is in re_format(7). This option is useful for converting all files of a given extension. For example, convert all source code files, leaving binary files intact:

A similar option is DOS2UNIX_GLOB, which invokes find for each element listed in it.

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

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.

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.

Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name:

If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to 1.0 (like the piewm example above). Otherwise, ask the original author or use the date string (0.0.yyyy.mm.dd) as the version.

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.

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.

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:

If you are not sure about the category, please put a comment to that effect in your send-pr(1) submission so we can discuss it before we import it. If you are a committer, send a note to the FreeBSD ports mailing list 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.

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:

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 CATEGORIES of the affected ports.

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.

DISTNAME is the name of the port as called by the authors of the software. DISTNAME defaults to ${PORTNAME}-${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}, and DISTVERSION defaults to ${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}.

Some vendor's distribution names which do not fit into the ${PORTNAME}-${PORTVERSION}-scheme can be handled automatically by setting DISTVERSION. PORTVERSION will be derived from it automatically.

The following table lists some examples of DISTVERSION and the derived PORTVERSION:

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 SourceForge, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using predefined macros (e.g., SF, GNU or CPAN). Simply set MASTER_SITES to one of these values. Here is an example:

Or you can use the older expanded format, though there really are no reason to do so:

These values and 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.

Several magic macros exist for popular sites with a predictable directory structure. For these, just use the abbreviation and the system will try to guess the correct subdirectory for you.

If the guess is incorrect, it can be overridden as follows.

This can also be written as

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:

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

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.

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

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.

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

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 .Z, .gz, .bz2 or .xz.

If the patch is distributed with some other files, such as documentation, in a gzipped 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.

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

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

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

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

If your port uses binary distfiles and has a license that requires that the source code is provided with packages distributed in binary form, e.g., GPL, ALWAYS_KEEP_DISTFILES will instruct the FreeBSD build cluster to keep a copy of the files specified in DISTFILES. Users of these ports will generally not need these files, so it is a good idea to only add the source distfiles to DISTFILES when PACKAGE_BUILDING is defined.

When adding extra files to DISTFILES, make sure you also add them to distinfo. Also, the additional files will normally be extracted into WRKDIR as well, which for some ports may lead to undesirable side effects and require special handling.

This variable specifies the shared libraries this port depends on. It is a list of lib:dir 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. For example,

will check for a shared jpeg library with any version, and descend into the graphics/jpeg subdirectory of your ports tree to build and install it if it is not found.

The dependency is checked twice, once from within the build target and then from within the install target. Also, the name of the dependency is put into the package so that pkg install (see pkg-install(8)) will automatically install it if it is not on the user's system.

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,

will check if the file or directory /usr/local/news/bin/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 xmlcatmgr is in the search path, and descend into the textproc/xmlcatmgr subdirectory of your ports tree to build and install it if it is not found.

The dependency is checked from within the install target. Also, the name of the dependency is put into the package so that pkg install (see pkg-install(8)) 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.

A quite common situation is when RUN_DEPENDS is literally the same as BUILD_DEPENDS, especially if ported software is written in a scripted language or if it requires the same build and run-time environment. In this case, it is both tempting and intuitive to directly assign one to the other:

However, such assignment can pollute run-time dependencies with entries not defined in the port's original BUILD_DEPENDS. This happens because of make(1)'s lazy evaluation of variable assignment. Consider a Makefile with USE_* variables, which are processed by ports/Mk/bsd.*.mk to augment initial build dependencies. For example, USES= gmake adds devel/gmake to BUILD_DEPENDS. To prevent such additional dependencies from polluting RUN_DEPENDS, take care to assign with expansion, i.e., expand the value before assigning it to the variable:

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,

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.

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,

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.

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,

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.

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,

will descend into the java/jfc subdirectory of your ports tree to extract it.

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

Parameters can be added to define different features and dependencies used by the port. They are specified by adding this line to the Makefile:

For the complete list of values, please see Section 15.1, “Values of USES”.

Several variables exist to define common dependencies shared by many ports. Their use is optional, but helps to reduce the verbosity of the port Makefiles. Each of them is styled as USE_*. These variables may be used only in the port Makefiles and ports/Mk/bsd.*.mk. They are not meant for user-settable options — use PORT_OPTIONS for that purpose.

Variables related to gmake and the configure script are described in Section 6.4, “Building Mechanisms”, while autoconf, automake and libtool are described in Section 6.5, “Using GNU Autotools”. Perl related variables are described in Section 6.7, “Using Perl”. X11 variables are listed in Section 6.8, “Using X11”. Section 6.9, “Using GNOME” deals with GNOME and Section 6.11, “Using KDE” with KDE related variables. Section 6.12, “Using Java” documents Java variables, while Section 6.13, “Web Applications, Apache and PHP” contains information on Apache, PHP and PEAR modules. Python is discussed in Section 6.14, “Using Python”, while Ruby in Section 6.17, “Using Ruby”. Section 6.18, “Using SDL” provides variables used for SDL applications and finally, Section 6.22, “Using Xfce” contains information on Xfce.

A minimal version of a dependency can be specified in any *_DEPENDS variable except LIB_DEPENDS using the following syntax:

The first field contains a dependent package name, which must match the entry in the package database, a comparison sign, and a package version. The dependency is satisfied if p5-Spiffy-0.26 or newer is installed on the machine.

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

will always descend to the jpeg port and extract it.

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.

Dependencies must be declared either explicitly or by using the OPTIONS framework. Using other methods like automatic detection complicates indexing, which causes problems for port and package management.

The problem with trying to automatically add dependencies is that files and settings outside an individual port can change at any time. For example: an index is built, then a batch of ports are installed. But one of the ports installs the tested file. The index is now incorrect, because an installed port unexpectedly has a new dependency. The index may still be wrong even after rebuilding if other ports also determine their need for dependencies based on the existence of other files.

Testing option variables is the correct method. It will not cause inconsistencies in the index of a batch of ports, provided the options were defined prior to the index build. Simple scripts can then be used to automate the building, installation, and updating of these ports and their packages.

USE_ variables are set by the port maintainer to define software on which this port depends. A port that needs Firefox would set

Some USE_ variables can accept version numbers or other parameters. For example, a port that requires Apache 2.2 would set

For more control over dependencies in some cases, WANT_ variables are available to more precisely specify what is needed. For example, consider the mail/squirrelmail port. This port needs some PHP modules, which are listed in the USE_PHP variable:

Those modules may be available in CLI or web versions, so the web version is selected with a WANT_ variable:

Available USE_ and WANT_ variables are defined in the files in /usr/ports/Mk.

When using a GNU configure script, keep an eye on which optional features are activated by auto-detection. Explicitly disable optional features you do not wish to be used by passing respective --without-xxx or --disable-xxx in CONFIGURE_ARGS.

In the example above, imagine a library libfoo is installed on the system. The user does not want this application to use libfoo, so he toggled the option off in the make config dialog. But the application's configure script detects the library present in the system and includes its support in the resulting executable. Now when the user decides to remove libfoo from the system, the ports system does not protest (no dependency on libfoo was recorded) but the application breaks.

In the second example, the library libfoo is explicitly disabled. The configure script does not enable related features in the application, despite library's presence in the system.

There are some macros to help simplify conditional values which differ based on the options set.

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:

or possibly

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

If your package cannot coexist with other packages (because of file conflicts, runtime incompatibilities, etc.), list the other package names in the CONFLICTS_INSTALL variable. You can use shell globs like * and ? here. Package names should be enumerated the same way they appear in /var/db/pkg. Please make sure that CONFLICTS_INSTALL does not match this port's package itself. Otherwise enforcing its installation with FORCE_PKG_REGISTER will no longer work. The CONFLICTS_INSTALL check is done after the build stage and prior to the install stage.

If your port cannot be built if a certain port is already installed, list the other port names in the CONFLICTS_BUILD variable. You can use shell globs like * and ? here. Package names should be enumerated the same way they appear in /var/db/pkg. The CONFLICTS_BUILD check is done prior to the build stage. Build conflicts are not recorded in the resulting package.

If your port cannot be built if a certain port is already installed and the resulting package cannot coexist with the other package, list the other package name 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_INSTALL does not match this port's package itself. Otherwise enforcing its installation with FORCE_PKG_REGISTER will no longer work. The CONFLICTS check is done prior to the build stage and prior to the install stage.

Use the macros provided in bsd.port.mk to ensure correct modes of files in the port's *-install targets. Set ownership directly in pkg-plist with the corresponding entries, such as @owner owner and @group group. These operators work until being overridden, or until the end of pkg-plist, so do not forget to reset them after they are no longer needed. The default ownership is root:wheel.

These are basically the install command with all the appropriate flags.

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). The INSTALL_LIB macro does the same thing to shared libraries.

If you need to strip a file, but wish to use neither INSTALL_PROGRAM nor INSTALL_LIB macros, ${STRIP_CMD} will strip your program or shared library. This is typically done within the post-install target. For example:

When multiple files need to be stripped:

Use file(1) on a file to determine if it has been stripped. Binaries are reported by file(1) as stripped, or not stripped. Additionally, strip(1) will detect programs that have already been stripped and exit cleanly.

Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from WRKSRC to a target directory under PREFIX. Note that PREFIX, EXAMPLESDIR, DATADIR, and other path variables must always be prepended with STAGEDIR to respect staging (see Section 6.1, “Staging”).

Two macros exist for this situation. The advantage of using these macros instead of cp is that they guarantee proper file ownership and permissions on target files. The first macro, COPYTREE_BIN, will set all the installed files to be executable, thus being suitable for installing into PREFIX/bin. The second macro, COPYTREE_SHARE, does not set executable permissions on files, and is therefore suitable for installing files under PREFIX/share target.

This example will install the contents of examples directory in the vendor distfile to the proper examples location of your port.

And this example will install the data of summer months to the summer subdirectory of a DATADIR.

Additional find arguments can be passed via the third argument to the COPYTREE_* macros. For example, to install all files from the first example except Makefiles, one can use the following command.

These macros do not add the installed files to pkg-plist. They must be added manually. For optional documentation (PORTDOCS, see Section 5.15.4, “Install Additional Documentation”) and examples (PORTEXAMPLES), the %%PORTDOCS%% or %%PORTEXAMPLES%% prefixes must be prepended in pkg-plist.

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.

Since only the files listed in pkg-plist are installed, it is safe to always install documentation to STAGEDIR (see Section 6.1, “Staging”). Hence .if blocks are only needed when the installed files are large enough to cause significant I/O overhead.

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

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 conditionally installed documentation files and directories should be included in pkg-plist with the %%PORTDOCS%% prefix, for example:

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. If the DOCS option has been unset then files and directories listed in PORTDOCS would not be installed or added to port packing list. Installing the documentation at PORTDOCS as shown above remains up to the port itself. A typical example of utilizing PORTDOCS looks as follows:

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

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.

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.

Files defined in the NOFETCHFILES variable are not fetchable from any of the MASTER_SITES. An example of such a file is when the file is supplied on CD-ROM by the vendor.

Tools which check for the availability of these files on the MASTER_SITES should ignore these files and not report about them.

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.

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.

If the port has legal concerns not addressed by the above variables, the variable LEGAL_TEXT should be set to a string explaining the concern. For example, if special permission was obtained for FreeBSD to redistribute the binary, this variable should indicate so.

A port which sets any of the above variables must also be added to /usr/ports/LEGAL. The first column is a glob which matches the restricted distfiles. The second column is the port's origin. The third column is the output of make -VLEGAL.

The preferred way to state "the distfiles for this port must be fetched manually" is as follows:

This both informs the user, and sets the proper metadata on the user's machine for use by automated programs.

Note that this stanza must be preceded by an inclusion of bsd.port.pre.mk.

The FreeBSD ports framework supports parallel building using multiple make sub-processes, which allows SMP systems to utilize all of their available CPU power, allowing port builds to be faster and more effective.

This is achieved by passing -jX flag to make(1) running on vendor code. This is the default build behavior of ports. Unfortunately, not all ports handle parallel building well and it may be required to explicitly disable this feature by adding the MAKE_JOBS_UNSAFE=yes variable. It is used when a port is known to be broken with -jX.

Several differing make implementations exist. Ported software often requires a particular implementation, like GNU make, known in FreeBSD as gmake, or fmake, the legacy FreeBSD make.

If the port uses GNU make, add gmake to USES. If the legacy FreeBSD make is needed, add fmake there.

MAKE_CMD can be used to reference the specific command configured by the USES setting in the port's Makefile. In rare cases when more than one make implementation is listed in USES, the variables GMAKE (for the GNU version) or FMAKE (for the legacy FreeBSD version) are available. Most ports should only use MAKE_CMD within the application Makefiles in WRKSRC to call the make implementation expected by the ported software.

If your port is an X application that creates Makefile files from Imakefile files using imake, then set USES= imake. 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.

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.

If your port uses the configure script to generate Makefile files from Makefile.in files, set GNU_CONFIGURE=yes. If you want to give extra arguments to the configure script (the default argument is --prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}), set those extra arguments in CONFIGURE_ARGS. Extra environment variables can be passed using CONFIGURE_ENV variable.

For ports that use CMake, define USES= cmake, or USES= cmake:outsource to build in a separate directory (see below).

CMake supports the following build profiles: Debug, Release, RelWithDebInfo and MinSizeRel. Debug and Release profiles respect system *FLAGS, RelWithDebInfo and MinSizeRel will set CFLAGS to -O2 -g and -Os -DNDEBUG correspondingly. The lower-cased value of CMAKE_BUILD_TYPE is exported to the PLIST_SUB and should be used if port installs *.cmake files depending on the build type (see deskutils/strigi for an example). Please note that some projects may define their own build profiles and/or force particular build type by setting CMAKE_BUILD_TYPE in CMakeLists.txt files. In order to make a port for such a project respect CFLAGS and WITH_DEBUG, the CMAKE_BUILD_TYPE definitions must be removed from those files.

Most CMake-based projects support an out-of-source method of building. The out-of-source build for a port can be requested by using the :outsource suffix. When enabled, CONFIGURE_WRKSRC, BUILD_WRKSRC and INSTALL_WRKSRC will be set to ${WRKDIR}/.build and this directory will be used to keep all files generated during configuration and build stages, leaving the source directory intact.

If your port uses SCons, define USE_SCONS=yes.

To make third party SConstruct respect everything that is passed to SCons in SCONS_ENV (that is, most importantly, CC/CXX/CFLAGS/CXXFLAGS), patch the SConstruct so build Environment is constructed like this:

It may be then modified with env.Append and env.Replace.

The various GNU autotools provide an abstraction mechanism for building a piece of software over a wide variety of operating systems and machine architectures. Within the Ports Collection, an individual port can make use of these tools via a simple construct:

At the time of writing, tool can be one of autoconf, autoheader, automake, aclocal, libtool (deprecated), libtoolize, libltdl. It can also be one the older legacy of autoconf213, autoheader213, automake14, aclocal14.

env is used to specify that the environmental variables are needed. It also adds a build dependency on the tool. The relevant tool is not ran as part of the run-autotools target.

Multiple tools can be specified at once, either by including them all on a single line, or using the += Makefile construct.

The use of USE_AUTOTOOLS=libtool is deprecated. Now all ports that ship with their own copy of libtool (search for a file named ltmain.sh) need to have USES=libtool. Also, if a port has USE_AUTOTOOLS=libtoolize it probably also needs USES=libtool.

Some ports do not ship with their own copy of libtool and expect libtool to be provided by the build system. In that case simply add:

Some ports make use of the libltdl library package, which is part of the libtool suite. Use of this library does not automatically necessitate the use of libtool itself, so a separate construct is provided.

Currently, all this does is to bring in a LIB_DEPENDS on the appropriate libltdl port, and is provided as a convenience function to help eliminate any dependencies on the autotools ports outside of the USE_AUTOTOOLS framework. There are no optional operations for this tool.

Some ports do not contain a configure script, but do contain an autoconf template in the configure.ac file. You can use the following assignments to let autoconf create the configure script, and also have autoheader create template headers for use by the configure script.

and

which also implies the use of autoconf.

The additional optional variables AUTOCONF_ARGS and AUTOHEADER_ARGS can be overridden by the port Makefile if specifically requested. Most ports are unlikely to need this. See bsd.autotools.mk for further details.

Some packages only contain Makefile.am files. These have to be converted into Makefile.in files using automake, and the further processed by configure to generate an actual Makefile.

Similarly, packages occasionally do not ship with included aclocal.m4 files, again required to build the software. This can be achieved with aclocal, which scans configure.ac or configure.in.

aclocal has a similar relationship to automake as autoheader does to autoconf, described in the previous section. aclocal implies the use of automake, thus we have:

and

As with autoconf and autoheader, both automake and aclocal have optional argument variables, AUTOMAKE_ARGS and ACLOCAL_ARGS respectively, which may be overridden by the port Makefile if required.

If your port requires gettext, set USES= gettext, and your port will inherit a dependency on libintl.so from devel/gettext. Other values for gettext usage are listed in USES=gettext.

A rather common case is a port using gettext and configure. Generally, GNU configure should be able to locate gettext automatically.

If it ever fails to, hints at the location of gettext can be passed in CPPFLAGS and LDFLAGS as follows:

Some software products allow for disabling NLS, e.g., through passing --disable-nls to configure. In that case, your port should use gettext conditionally, depending on the status of the NLS option. For ports of low to medium complexity, you can rely on the following idiom:

Or using the older way of using options:

The next item on your to-do list is to arrange so that the message catalog files are included in the packing list conditionally. The Makefile part of this task is already provided by the idiom. It is explained in the section on advanced pkg-plist practices. In a nutshell, each occurrence of %%NLS%% in pkg-plist will be replaced by “@comment ” if NLS is disabled, or by a null string if NLS is enabled. Consequently, the lines prefixed by %%NLS%% will become mere comments in the final packing list if NLS is off; otherwise the prefix will be just left out. All you need to do now is insert %%NLS%% before each path to a message catalog file in pkg-plist. For example:

In high complexity cases, you may need to use more advanced techniques than the recipe given here, such as dynamic packing list generation.

There is a point to note about installing message catalog files. The target directories for them, which reside under LOCALBASE/share/locale, should rarely be created and removed by a port. The most popular languages have their respective directories listed in PORTSDIR/Templates/BSD.local.dist. The directories for many other languages are governed by the devel/gettext port. Consult its pkg-plist and see whether the port is going to install a message catalog file for a unique language.

The X11 implementation available in The Ports Collection is X.Org. If your application depends on X components, set USE_XORG to the list of required components. Available components, at the time of writing, are:

bigreqsproto compositeproto damageproto dmx dmxproto dri2proto evieproto fixesproto fontcacheproto fontenc fontsproto fontutil glproto ice inputproto kbproto libfs oldx pciaccess pixman printproto randrproto recordproto renderproto resourceproto scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7 xbitmaps xcmiscproto xcomposite xcursor xdamage xdmcp xevie xext xextproto xf86bigfontproto xf86dgaproto xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto xfixes xfont xfontcache xft xi xinerama xineramaproto xkbfile xkbui xmu xmuu xorg-server xp xpm xprintapputil xprintutil xproto xproxymngproto xrandr xrender xres xscrnsaver xt xtrans xtrap xtst xv xvmc xxf86dga xxf86misc xxf86vm.

Always up-to-date list can be found in /usr/ports/Mk/bsd.xorg.mk.

The Mesa Project is an effort to provide free OpenGL implementation. You can specify a dependency on various components of this project with USE_GL variable. Valid options are: glut, glu, glw, glew, gl and linux. For backwards compatibility, the value of yes maps to glu.

If your port requires a Motif library, define USES= motif in the Makefile. Default Motif implementation is x11-toolkits/open-motif. Users can choose x11-toolkits/lesstif instead by setting WANT_LESSTIF variable.

The MOTIFLIB variable will be set by bsd.port.mk to reference the appropriate Motif library. Please patch the source of your port to use ${MOTIFLIB} wherever the Motif library is referenced in the original Makefile or Imakefile.

There are two common cases:

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

If your port installs fonts for the X Window System, put them in LOCALBASE/lib/X11/fonts/local.

Some applications require a working X11 display for compilation to succeed. This pose a problem for machines that operate headless. When the following variable is used, the build infrastructure will start the virtual framebuffer X server. The working DISPLAY is then passed to the build.

Desktop entries (a Freedesktop standard) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. For example, newly-installed programs automatically appear in the application menus of compatible desktop environments. Desktop entries originated in the GNOME desktop environment, but are now a standard and also work with KDE and Xfce. This bit of automation provides a real benefit to the user, and desktop entries are encouraged for applications which can be used in a desktop environment.

When USE_QT4 is set, the following settings are deployed:

Individual Qt 4 tool and library dependencies must be specified in the USE_QT4 variable. Every component can be suffixed by either _build or _run, the suffix indicating whether the component should be depended on at buildtime or runtime, respectively. If unsuffixed, the component will be depended on at both build- and runtime. Usually, library components should be specified unsuffixed, tool components should be specified with the _build suffix and plugin components should be specified with the _run suffix. The most commonly used components are listed below (all available components are listed in _USE_QT4_ALL in /usr/ports/Mk/bsd.qt.mk):

You can determine which libraries the application depends on, by running ldd on the main executable after a successful compilation.

If the application does not provide a configure script but a .pro file, you can use the following:

USES=qmake instructs the port to use qmake for configuring. Note that USES=qmake does not imply a dependency on Qt 4 qmake, thus USE_QT4 has to be populated with the qmake_build component.

Qt applications often are written to be cross-platform and often X11/Unix is not the platform they are developed on, which in turn often leads to certain loose ends, like:

If your application depends on KDE 4.x, set USE_KDE4 to the list of required components. _build and _run suffixes can be used to force components dependency type (e.g., baseapps_run). If no suffix is set, a default dependency type will be used. If you want to force both types, add the component twice with both suffixes (e.g., automoc4_build automoc4_run). The most commonly used components are listed below (up-to-date components are documented at the top of /usr/ports/Mk/bsd.kde4.mk):

KDE 4.x ports are installed into KDE4_PREFIX, which is /usr/local/kde4 currently. This is achieved by specifying the kdeprefix component, which overrides the default PREFIX. The ports however respect any PREFIX set via MAKEFLAGS environment variable and/or make arguments.

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, and FreeBSD default is java/openjdk6.

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

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:

The related entries are defined in both PLIST_SUB (documented in Section 7.1, “Changing pkg-plist Based on Make Variables”) and SUB_LIST.

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_TARGET. This is similar to the USES= gmake mechanism, which is documented in Section 6.4, “Building Mechanisms”.

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):

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

When porting a Java™ application that requires an application server such as www/tomcat7 to run the service, it is quite common for a vendor to distribute a .war file. A .war file is a Web application ARchive and is extracted when called by the application. Avoid adding a .war file to the pkg-plist. It is not considered best practice. An application server will expand the war archive, but not clean it up properly if the port is removed. A more desirable way of working with this file is to extract the archive, then install the files, and lastly add these files to pkg-plist.

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 Section 7.1, “Changing pkg-plist Based on Make Variables”) 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 FreeBSD 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 Subversion 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 FreeBSD Java Language mailing list.

Although there is a java category for PRs, it refers to the JDK porting effort from the FreeBSD 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 Section 5.3, “Categorization”.

Web applications should be installed into PREFIX/www/appname. For your convenience, this path is available both in Makefile and in pkg-plist as WWWDIR, and the path relative to PREFIX is available in Makefile as WWWDIR_REL.

The user and group of web server process are available as WWWOWN and WWWGRP, in case you need to change the ownership of some files. The default values of both are www. If you want different values for your port, use WWWOWN?= myuser notation, to allow user to override it easily.

Do not depend on Apache unless the web app explicitly needs Apache. Respect that users may wish to run your web app on different web server than Apache.

Porting PEAR modules is a very simple process.

Use the variables FILES, TESTS, DATA, SQLS, SCRIPTFILES, DOCS and EXAMPLES to list the files you want to install. All listed files will be automatically installed into the appropriate locations and added to pkg-plist.

Include ${PORTSDIR}/devel/pear/bsd.pear.mk on the last line of the Makefile.

There are many versions of the wxWidgets libraries which conflict between them (install files under the same name). In the ports tree this problem has been solved by installing each version under a different name using version number suffixes.

The obvious disadvantage of this is that each application has to be modified to find the expected version. Fortunately, most of the applications call the wx-config script to determine the necessary compiler and linker flags. The script is named differently for every available version. Majority of applications respect an environment variable, or accept a configure argument, to specify which wx-config script to call. Otherwise they have to be patched.

To make your port use a specific version of wxWidgets there are two variables available for defining (if only one is defined the other will be set to a default value):

The following is a list of available wxWidgets versions and the corresponding ports in the tree:

The variables in Table 6.24, “Variables to Select wxWidgets Versions” can be set to one or more of the following combinations separated by spaces:

There are also some variables to select the preferred versions from the available ones. They can be set to a list of versions, the first ones will have higher priority.

There are other applications that, while not being wxWidgets libraries, are related to them. These applications can be specified in the WX_COMPS variable. The following components are available:

The dependency type can be selected for each component by adding a suffix separated by a semicolon. If not present then a default type will be used (see Table 6.30, “Default wxWidgets Dependency Types”). The following types are available:

The default values for the components are detailed in the following table:

The wxWidgets library supports Unicode since version 2.5. In the ports tree both versions are available and can be selected with the following variables: