FreeBSD Porter's Handbook

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(1) 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(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 fulfill more sophisticated tasks.

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.

LATEST_LINK is used during package building to determine a shortened name to create links that can be used by pkg_add -r. This makes it possible to, for example, install the latest perl version by running pkg_add -r perl without knowing the exact version number. This name needs to be unique and obvious to users.

In some cases, several versions of a program may be present in the ports collection at the same time. Both the index build and the package build system need to be able to see them as different, independent ports, although they may all have the same PORTNAME, PKGNAMEPREFIX, and even PKGNAMESUFFIX. In those cases, the optional LATEST_LINK variable should be set to a different value for all ports except the “main” one — see the lang/gcc46 and lang/gcc ports, and the www/apache* family for examples of its use. By setting NO_LATEST_LINK, no link will be generated, which may be an option for all but the “main” version. Note that how to choose a “main” version — “most popular”, “best supported”, “least patched”, and so on — is outside the scope of this handbook's recommendations; we only tell you how to specify the other ports' versions after you have picked a “main” one.

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}-${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 and DISTNAME will be derived automatically, but can of course be overridden. The following table lists some examples:

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 MASTER_SITE_* (e.g., MASTER_SITE_SOURCEFORGE, MASTER_SITE_GNU and MASTER_SITE_PERL_CPAN). Simply set MASTER_SITES to one of these variables and MASTER_SITE_SUBDIR to the path within the archive. Here is an example:

Or you can use a condensed format:

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.

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 be also 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 .gz or .Z.

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 extract target and then from within the install target. Also, the name of the dependency is put into the package so that pkg_add(1) 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_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.

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.

There several parameters exist for defining different kind of features and dependencies that the port in question uses. They can be specified by adding the following line to the Makefile of the port:

For the complete list of such 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.

If OPTIONS_SUB is set to yes then each of the options added to OPTIONS_DEFINE will be added to PLIST_SUB, for example:

is equivalent to:

If X_CONFIGURE_ENABLE is set then --enable-${X_CONFIGURE_ENABLE} or --disable-${X_CONFIGURE_ENABLE} will be added to CONFIGURE_ARGS depending on the value of the optionX, for example:

is equivalent to:

If X_CONFIGURE_WITH is set then --with-${X_CONFIGURE_WITH} or --without-${X_CONFIGURE_WITH} will be added to CONFIGURE_ARGS depending on the status of the option X, for example:

is equivalent to:

If X_CONFIGURE_ON is set then its value will be appended to CONFIGURE_ARGS depending on the status of the option X, for example:

is equivalent to:

If X_CONFIGURE_OFF is set then its value will be appended to CONFIGURE_ARGS depending on the status of the option X, for example:

is equivalent to:

If X_CMAKE_ON is set then its value will be appended to CMAKE_ARGS depending on the status of the option X, for example:

is equivalent to:

If X_CMAKE_OFF is set then its value will be appended to CMAKE_ARGS depending on the status of the option X, for example:

is equivalent to:

For any of the following variables:

If X_ABOVEVARIABLE is defined then its value will be appended to ABOVEVARIABLE depending on the status of the option X, for example:

is equivalent to:

For any of the following dependency type:

If X_ABOVEVARIABLE is defined then its value will be appended to ABOVEVARIABLE depending on the status of the option X, for example:

is equivalent to:

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.

Do use the macros provided in bsd.port.mk to ensure correct modes of files in your own *-install targets. Ownership should be set directly in the pkg-plist file with the corresponding entries, such as @owner owner and @group group. Note that these operators work until being overridden, or until the end of pkg-plist, so do not forget to reset them afterwards they are not needed any more. 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:

Use the 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, strip(1) will not strip a previously stripped program; it will instead exit cleanly.

Sometimes, there is a need to install a big number of files, preserving their hierarchical organization, i.e., copying over a whole directory tree from WRKSRC to a target directory under PREFIX. Note that PREFIX, EXAMPLESDIR, DATADIR, and such have to be always prepended with STAGEDIR in order 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.

Note that these macros does not add the installed files to pkg-plist. You still need to list them. For optional documentation (PORTDOCS, see Section 5.15.4, “Install Additional Documentation”) and examples (PORTEXAMPLES), the %%PORTDOCS%% or %%PORTEXAMPLES%% prefixes have to 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 has to only be associated 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.

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

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. Unfortunately, not all ports handle parallel building well. Therefore it is required to explicitly enable this feature by adding MAKE_JOBS_SAFE=yes somewhere below the dependency declaration section of the Makefile.

Another option for controlling this feature from the maintainer's point of view is the MAKE_JOBS_UNSAFE=yes variable. It is used when a port is known to be broken with -jX and a user forces the use of multi processor compilations for all ports in /etc/make.conf with the FORCE_MAKE_JOBS=yes variable.

If your port uses GNU make, set USES= gmake.

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 libtool, libltdl, autoconf, autoheader, automake or aclocal.

version specifies the particular tool revision to be used (see devel/{automake,autoconf,libtool}[0-9]+ for valid versions).

operation is an optional extension to modify how the tool is used.

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

Finally, there is the special tool, called autotools, which is a convenience function to bring in all available versions of the autotools to allow for cross-development work. This can also be accomplished by installing the devel/autotools port.

Shared libraries using the GNU building framework usually use libtool to adjust the compilation and installation of shared libraries to match the specifics of the underlying operating system. The usual practice is to use copy of libtool bundled with the application. In case you need to use external libtool, you can use the version provided by The Ports Collection:

With no additional operations, libtool:version tells the building framework to patch the configure script with the system-installed copy of libtool. The GNU_CONFIGURE is implied. Further, a number of make and shell variables will be assigned for onward use by the port. See bsd.autotools.mk for details.

With the :env operation, only the environment will be set up.

Finally, LIBTOOLFLAGS and LIBTOOLFILES can be optionally set to override the most likely arguments to, and files patched by, libtool. Most ports are unlikely to need this. See bsd.autotools.mk for further details.

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

Similarly to libtool, the inclusion of the optional :env operation simply sets up the environment for further use. Without it, patching and reconfiguration of the port is carried out.

The additional optional variables AUTOCONF_ARGS and AUTOHEADER_ARGS can be overridden by the port Makefile if specifically requested. As with the libtool equivalents, most ports are unlikely to need this.

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

which also implies the use of automake:version.

Similarly to libtool and autoconf, the inclusion of the optional :env operation simply sets up the environment for further use. Without it, reconfiguration of the port is carried out.

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 devel/gettext. Other values for gettext usage are listed in Section 15.1, “Values of USES”.

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:

Of course, the code can be more compact if there are no more flags to pass to configure:

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:

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_QT_VER is set to 3, some useful settings are passed to the configure script:

If 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 file but a .pro file, you can use the following:

Note the similarity to the qmake line from the provided BUILD.sh script. Passing CONFIGURE_ENV ensures qmake will see the QMAKESPEC variable, without which it cannot work. qmake generates standard Makefiles, so it is not necessary to write our own build target.

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

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 SVN 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.23, “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.29, “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:

To detect an installed version you have to define WANT_WX. If you do not set it to a specific version then the components will have a version suffix. The HAVE_WX variable will be filled after detection.

The following variables are available in the port (after defining one from Table 6.23, “Variables to Select wxWidgets Versions”).

If you need to use the variables for running commands right after including bsd.port.pre.mk you need to define WX_PREMK.

Some GNU configure scripts can not find wxWidgets with just the WX_CONFIG environment variable set, requiring additional arguments. The WX_CONF_ARGS variable can be used for provide them.

There are many versions of the Lua libraries and corresponding interpreters, 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. But it can be solved by adding some additional flags to the compiler and linker.

To make your port use a specific version of Lua 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 Lua versions and the corresponding ports in the tree:

The variables in Table 6.33, “Variables to Select Lua 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 Lua libraries, are related to them. These applications can be specified in the LUA_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.39, “Default Lua Dependency Types”). The following types are available:

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

To detect an installed version you have to define WANT_LUA. If you do not set it to a specific version then the components will have a version suffix. The HAVE_LUA variable will be filled after detection.

The following variables are available in the port (after defining one from Table 6.33, “Variables to Select Lua Versions”).

If you need to use the variables for running commands right after including bsd.port.pre.mk you need to define LUA_PREMK.