3.2.1 pkg-descr

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 is a port of oneko, in which a cat chases a poor mouse all over
the screen.
 :
(etc.)

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

3.2.2 pkg-plist

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

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

Refer to the 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:

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

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

The price for this way of listing port's files and directories is that you cannot use command sequences described in 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.

5.2.1 PORTNAME and PORTVERSION

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

5.2.2 PORTREVISION and PORTEPOCH

PORTNAME=	gtkmumble
PORTVERSION=	0.10

PORTNAME=	gtkmumble
PORTVERSION=	0.10
PORTREVISION=	1

PORTNAME=	gtkmumble
PORTVERSION=	0.2
PORTEPOCH=	1

PORTNAME=	gtkmumble
PORTVERSION=	0.3
PORTEPOCH=	1

5.2.3 PKGNAMEPREFIX and PKGNAMESUFFIX

Two optional variables, PKGNAMEPREFIX and PKGNAMESUFFIX, are combined with PORTNAME and PORTVERSION to form PKGNAME as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure this conforms to our guidelines for a good package name. In particular, you are not allowed to use a hyphen (-) in PORTVERSION. Also, if the package name has the language- or the -compiled.specifics part (see below), use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME.

5.2.4 LATEST_LINK

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

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

5.2.5 Package Naming Conventions

The following are the conventions you should follow in naming your packages. This is to have our package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes!

The package name should look like [language[_region]]-name[[-]compiled.specifics]-version.numbers.

The package name is defined as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure to set the variables to conform to that format.

1. FreeBSD strives to support the native language of its users. The language- part should be a two letter abbreviation of the natural language defined by ISO-639 if the port is specific to a certain language. Examples are ja for Japanese, ru for Russian, vi for Vietnamese, zh for Chinese, ko for Korean and de for German.

   If the port is specific to a certain region within the language area, add the two letter country code as well. Examples are en_US for US English and fr_CH for Swiss French.

   The language- part should be set in the PKGNAMEPREFIX variable.

2. The first letter of the name part should be lowercase. (The rest of the name may contain capital letters, so use your own discretion when you are converting a software name that has some capital letters in it.) There is a tradition of naming Perl 5 modules by prepending p5- and converting the double-colon separator to a hyphen; for example, the Data::Dumper module becomes p5-Data-Dumper.

3. Make sure that the port's name and version are clearly separated and placed into the PORTNAME and PORTVERSION variables. The only reason for PORTNAME to contain a version part is if the upstream distribution is really named that way, as in the textproc/libxml2 or japanese/kinput2-freewnn ports. Otherwise, the PORTNAME should not contain any version-specific information. It is quite normal for several ports to have the same PORTNAME, as the www/apache* ports do; in that case, different versions (and different index entries) are distinguished by the PKGNAMEPREFIX, PKGNAMESUFFIX, and LATEST_LINK values.

4. If the port can be built with different hardcoded defaults (usually part of the directory name in a family of ports), the -compiled.specifics part should state the compiled-in defaults (the hyphen is optional). Examples are paper size and font units.

   The -compiled.specifics part should be set in the PKGNAMESUFFIX variable.

5. The version string should follow a dash (-) and be a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string pl (meaning ``patchlevel''), which can be used only when there are no major and minor version numbers in the software. If the software version has strings like ``alpha'', ``beta'', ``rc'', or ``pre'', take the first letter and put it immediately after a period. If the version string continues after those names, the numbers should follow the single alphabet without an extra period between them.

   The idea is to make it easier to sort ports by looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the 0.0.yyyy.mm.dd format, not dd.mm.yyyy or the non-Y2K compliant yy.mm.dd format. It is important to prefix the version with 0.0. in case a release with an actual version number is made, which would of course be numerically less than yyyy.

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

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.

5.3.1 CATEGORIES

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

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

5.3.2 Current List of Categories

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

5.3.3 Choosing the Right Category

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

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

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

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

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

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

• Ports which install loadable kernel modules should have the virtual category kld in their CATEGORIES line.

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

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

If you are not sure about the category, please put a comment to that effect in your 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.

5.3.4 Proposing a New Category

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

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

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

Here is the procedure:

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.

5.3.5 Proposing Reorganizing All the Categories

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

5.4.1 DISTVERSION/DISTNAME

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

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:

5.4.2 MASTER_SITES

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

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

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

If the original tarball is part of one of the popular archives such as 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:

MASTER_SITES=		${MASTER_SITE_GNU}
MASTER_SITE_SUBDIR=	make

Or you can use a condensed format:

MASTER_SITES=	GNU/make

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.

MASTER_SITES=	SF

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

MASTER_SITES=	SF/stardict/WyabdcRealPeopleTTS/${PORTVERSION}

This can be also written as

MASTER_SITES=	SF
MASTER_SITE_SUBDIR=	stardict/WyabdcRealPeopleTTS/${PORTVERSION}

5.4.3 EXTRACT_SUFX

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

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

DISTNAME=	foo
EXTRACT_SUFX=	.tgz

The USE_BZIP2, 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.

5.4.4 DISTFILES

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

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

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

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

5.4.5 EXTRACT_ONLY

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

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

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

EXTRACT_ONLY=

5.4.6 PATCHFILES

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

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

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

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

5.4.7 Multiple Distribution Files or Patches from Different Sites and Subdirectories (MASTER_SITES:n)

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

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

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:

DISTFILES=	alpha:0 beta:1

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

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

Just picture 2 files in DISTFILES and 20 sites in MASTER_SITES, the sites slow as hell where beta is carried by all sites in MASTER_SITES, and alpha can only be found in the 20th site. It would be such a waste to check all of them if 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.

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

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

5.4.8 DIST_SUBDIR

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

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

5.4.9 ALWAYS_KEEP_DISTFILES

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.

.if defined(PACKAGE_BUILDING)
DISTFILES+=		foo.tar.gz
ALWAYS_KEEP_DISTFILES=	yes
.endif

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.

5.8.1 LIB_DEPENDS

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

LIB_DEPENDS=   jpeg:${PORTSDIR}/graphics/jpeg

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 target part can be omitted if it is equal to DEPENDS_TARGET (which defaults to install).

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.

5.8.2 RUN_DEPENDS

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

For example,

RUN_DEPENDS=	${LOCALBASE}/news/bin/innd:${PORTSDIR}/news/inn \
		xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr

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:

RUN_DEPENDS=	${BUILD_DEPENDS}

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, USE_GMAKE=yes 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:

RUN_DEPENDS:=	${BUILD_DEPENDS}

5.8.3 BUILD_DEPENDS

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

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

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

5.8.4 FETCH_DEPENDS

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

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

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

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

5.8.5 EXTRACT_DEPENDS

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

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

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

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

5.8.6 PATCH_DEPENDS

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

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

will descend into the java/jfc subdirectory of your ports tree to 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.

5.8.7 USE_*

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.3, while autoconf, automake and libtool are described in Section 6.4. Perl related variables are described in Section 6.7. X11 variables are listed in Section 6.8. Section 6.9 deals with GNOME and Section 6.11 with KDE related variables. Section 6.12 documents Java variables, while Section 6.13 contains information on Apache, PHP and PEAR modules. Python is discussed in Section 6.14, while Ruby in Section 6.17. Section 6.18 provides variables used for SDL applications and finally, Section 6.21 contains information on Xfce.

5.8.8 Minimal Version of a Dependency

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

p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy

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.

5.8.9 Notes on Dependencies

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

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

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

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

will always descend to the jpeg port and extract it.

5.8.10 Circular Dependencies Are Fatal

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.

5.8.11 Problems Caused by Automatic Dependencies

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.

.include <bsd.port.pre.mk>

.if exists(${LOCALBASE}/bin/foo)
LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
.endif

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.

OPTIONS_DEFINE=	BAR
BAR_DESC=	Bar support

.include <bsd.port.options.mk>

.if ${PORT_OPTIONS:MBAR}
LIB_DEPENDS=	bar:${PORTSDIR}/foo/bar
.endif

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.

5.8.12 USE_ and WANT_

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

USE_FIREFOX=	yes

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

USE_APACHE=	22

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:

USE_PHP=	session mhash gettext mbstring pcre openssl xml

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

WANT_PHP_WEB=	yes

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

5.12.1 Knobs

5.12.2 OPTIONS

OPTIONS_DEFINE=	OPT1 OPT2

OPT1_DESC=	Describe OPT1
OPT2_DESC=	Describe OPT2
OPT3_DESC=	Describe OPT3
OPT4_DESC=	Describe OPT4
OPT5_DESC=	Describe OPT5
OPT6_DESC=	Describe OPT6

OPTIONS_SINGLE=		SG1
OPTIONS_SINGLE_SG1=	OPT3 OPT4

OPTIONS_RADIO=		RG1
OPTIONS_RADIO_RG1=	OPT7 OPT8

OPTIONS_MULTI=		MG1
OPTIONS_MULTI_MG1=	OPT5 OPT6

OPTIONS_GROUP=		GG1
OPTIONS_GROUP_GG1=	OPT9 OPT10

OPTIONS_DEFAULT=	OPT1 OPT3 OPT6

OPTIONS_DEFINE=	FOO BAR
FOO_DESC=	Enable option foo
BAR_DESC=	Support feature bar

OPTIONS_DEFAULT=FOO

.include <bsd.port.options.mk>

.if ${PORT_OPTIONS:MFOO}
CONFIGURE_ARGS+=--with-foo
.else
CONFIGURE_ARGS+=--without-foo
.endif

.if ${PORT_OPTIONS:MBAR}
RUN_DEPENDS+=	bar:${PORTSDIR}/bar/bar
.endif

.include <bsd.port.mk>

.if ! ${PORT_OPTIONS:MEXAMPLES}
CONFIGURE_ARGS+=--without-examples
.endif

OPTIONS_DEFINE=		EXAMPLES

OPTIONS_SINGLE=		BACKEND
OPTIONS_SINGLE_BACKEND=	MYSQL PGSQL BDB

OPTIONS_MULTI=		AUTH
OPTIONS_MULTI_AUTH=	LDAP PAM SSL

EXAMPLES_DESC=		Install extra examples
MYSQL_DESC=		Use MySQL as backend
PGSQL_DESC=		Use PostgreSQL as backend
BDB_DESC=		Use Berkeley DB as backend
LDAP_DESC=		Build with LDAP authentication support
PAM_DESC=		Build with PAM support
SSL_DESC=		Build with OpenSSL support

OPTIONS_DEFAULT=	PGSQL LDAP SSL

.include <bsd.port.options.mk>

.if ${PORT_OPTIONS:MPGSQL}
USE_PGSQL=		yes
CONFIGURE_ARGS+=	--with-postgres
.else
CONFIGURE_ARGS+=	--without-postgres
.endif

.if ${PORT_OPTIONS:MICU}
LIB_DEPENDS+=	icuuc:${PORTSDIR}/devel/icu
.endif

.if ! ${PORT_OPTIONS:MEXAMPLES}
CONFIGURE_ARGS+=	--without-examples
.endif

# Check other OPTIONS

.include <bsd.port.mk>

OPTIONS=	FOO "Enable option foo" On

.include <bsd.port.pre.mk>

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

.include <bsd.port.post.mk>

5.12.3 Feature Auto-Activation

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.

.if ${PORT_OPTIONS:MFOO}
LIB_DEPENDS+=		foo:${PORTSDIR}/devel/foo
CONFIGURE_ARGS+=	--enable-foo
.endif

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.

.if ${PORT_OPTIONS:MFOO}
LIB_DEPENDS+=		foo:${PORTSDIR}/devel/foo
CONFIGURE_ARGS+=	--enable-foo
.else
CONFIGURE_ARGS+=	--disable-foo
.endif

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.

5.13.1 WRKSRC

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

WRKSRC=	${WRKDIR}/foo

or possibly

WRKSRC=	${WRKDIR}/${PORTNAME}

5.13.2 NO_WRKSUBDIR

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

NO_WRKSUBDIR=	yes

5.14.1 CONFLICTS_INSTALL

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.

5.14.2 CONFLICTS_BUILD

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.

5.14.3 CONFLICTS

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.

5.15.1 INSTALL_* Macros

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

• INSTALL_PROGRAM is a command to install binary executables.

• INSTALL_SCRIPT is a command to install executable scripts.

• INSTALL_LIB is a command to install shared libraries.

• INSTALL_KLD is a command to install kernel loadable modules. Some architectures do not like having the modules stripped, so use this command instead of INSTALL_PROGRAM.

• INSTALL_DATA is a command to install sharable data.

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

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

5.15.2 Stripping Binaries and Shared Libraries

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:

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

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.

5.15.3 Installing a Whole Tree of Files

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.

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.

post-install:
	${MKDIR} ${EXAMPLESDIR}
	(cd ${WRKSRC}/examples/ && ${COPYTREE_SHARE} \* ${EXAMPLESDIR})

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

post-install:
	${MKDIR} ${DATADIR}/summer
	(cd ${WRKSRC}/temperatures/ && ${COPYTREE_SHARE} "June July August" ${DATADIR}/summer/)

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.

post-install:
	${MKDIR} ${EXAMPLESDIR}
	(cd ${WRKSRC}/examples/ && \
		${COPYTREE_SHARE} \* ${EXAMPLESDIR} "! -name Makefile")

Note that these macros does not add the installed files to pkg-plist. You still need to list them.

5.15.4 Install Additional Documentation

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

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

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

post-install:
.if ${PORT_OPTIONS:MDOCS}
	${MKDIR} ${DOCSDIR}
	${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR}
.endif

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

• DATADIR gets expanded to PREFIX/share/PORTNAME.

• DATADIR_REL gets expanded to share/PORTNAME.

• DOCSDIR gets expanded to PREFIX/share/doc/PORTNAME.

• DOCSDIR_REL gets expanded to share/doc/PORTNAME.

• EXAMPLESDIR gets expanded to PREFIX/share/examples/PORTNAME.

• EXAMPLESDIR_REL gets expanded to share/examples/PORTNAME.

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

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

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

As an alternative to enumerating the documentation files in pkg-plist, a port can set the variable PORTDOCS to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to DOCSDIR. Therefore, a port that utilizes PORTDOCS and uses a non-default location for its documentation should set DOCSDIR accordingly. If a directory is listed in PORTDOCS or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. 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:

PORTDOCS=	README.* ChangeLog docs/*

5.15.5 Subdirectories Under PREFIX

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.

6.2.1 NO_PACKAGE

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

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

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

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

6.2.2 NO_CDROM

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

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

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

6.2.3 NOFETCHFILES

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.

6.2.4 RESTRICTED

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

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

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

6.2.5 RESTRICTED_FILES

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

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

6.2.6 Examples

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

.if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX})
IGNORE=	may not be redistributed because of licensing reasons. Please visit some-website to accept their license and download ${DISTFILES} into ${DISTDIR}
.endif

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.

6.3.1 Building Ports in Parallel

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.

6.3.2 make, gmake, and imake

If your port uses GNU make, set USE_GMAKE=yes.

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

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.

6.3.3 configure Script

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.

6.3.4 Using scons

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:

env = Environment(**ARGUMENTS)

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

6.4.1 Introduction

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:

USE_AUTOTOOLS=	tool:version[:operation] ...

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.

6.4.2 libtool

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:

USE_AUTOTOOLS=	libtool:version[:env]

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.

6.4.3 libltdl

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.

USE_AUTOTOOLS=	libltdl:version

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.

6.4.4 autoconf and autoheader

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.

USE_AUTOTOOLS=	autoconf:version[:env]

and

USE_AUTOTOOLS=	autoheader:version

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.

6.4.5 automake and aclocal

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:

USE_AUTOTOOLS=	automake:version[:env]

and

USE_AUTOTOOLS=	aclocal:version

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.

6.6.1 Basic Usage

If your port requires gettext, just set USE_GETTEXT to yes, and your port will grow the dependency on devel/gettext. The value of USE_GETTEXT can also specify the required version of the libintl library, the basic part of gettext, but using this feature is strongly discouraged: Your port should work with just the current version of devel/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:

USE_GETTEXT=	yes
CPPFLAGS+=	-I${LOCALBASE}/include
LDFLAGS+=	-L${LOCALBASE}/lib

GNU_CONFIGURE=	yes
CONFIGURE_ENV=	CPPFLAGS="${CPPFLAGS}" \
		LDFLAGS="${LDFLAGS}"

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

USE_GETTEXT=	yes
GNU_CONFIGURE=	yes
CONFIGURE_ENV=	CPPFLAGS="-I${LOCALBASE}/include" \
		LDFLAGS="-L${LOCALBASE}/lib"

6.6.2 Optional Usage

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 WITHOUT_NLS. For ports of low to medium complexity, you can rely on the following idiom:

GNU_CONFIGURE=		yes

.if !defined(WITHOUT_NLS)
USE_GETTEXT=		yes
PLIST_SUB+=		NLS=""
.else
CONFIGURE_ARGS+=	--disable-nls
PLIST_SUB+=		NLS="@comment "
.endif

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:

%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo

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

6.6.3 Handling Message Catalog Directories

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 your port. The most popular languages have their respective directories listed in /etc/mtree/BSD.local.dist; that is, they are a part of the base system. The directories for many other languages are governed by the devel/gettext port. You may want to consult its pkg-plist and see whether your port is going to install a message catalog file for a unique language.

6.8.1 X.Org Components

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.

USE_XORG=	xrender xft xkbfile xt xaw
USE_GL=		glu

Some ports define USE_XLIB, which makes the port depend on all the 50 or so libraries. This variable exists for backwards compatibility, as it predates modular X.Org, and should not be used on new ports.

# Use some X11 libraries and depend on
# font server as well as cyrillic fonts.
RUN_DEPENDS=	${LOCALBASE}/bin/xfs:${X_FONTSERVER_PORT} \
		${LOCALBASE}/lib/X11/fonts/cyrillic/crox1c.pcf.gz:${X_FONTS_CYRILLIC_PORT}

USE_XORG=	x11 xpm

6.8.2 Ports That Require Motif

If your port requires a Motif library, define USE_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:

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

• If the port uses XmClientLibs in its Imakefile, change it to ${MOTIFLIB} ${XTOOLLIB} ${XLIB}.

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.

6.8.3 X11 Fonts

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

6.8.4 Getting a Fake DISPLAY with Xvfb

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.

USE_DISPLAY=	yes

6.8.5 Desktop Entries

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.

DESKTOP_ENTRIES=	"NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify

DESKTOP_ENTRIES=	"ToME" "Roguelike game based on JRR Tolkien's work" \
			"${DATADIR}/xtra/graf/tome-128.png" \
			"tome -v -g" "Application;Game;RolePlaying;" \
			false

6.10.1 Ports That Require Qt

When USE_QT_VER is set to 3, some useful settings are passed to the configure script:

CONFIGURE_ARGS+=	--with-qt-includes=${QT_PREFIX}/include \
			--with-qt-libraries=${QT_PREFIX}/lib \
			--with-extra-libs=${LOCALBASE}/lib \
			--with-extra-includes=${LOCALBASE}/include
CONFIGURE_ENV+=	MOC="${MOC}" LIBS="${QTCFGLIBS}" \
		QTDIR="${QT_PREFIX}" KDEDIR="${KDE_PREFIX}"
CPPFLAGS+=	${QTCPPFLAGS}

If USE_QT4 is set, the following settings are deployed:

CONFIGURE_ARGS+=	--with-qt-includes=${QT_INCDIR} \
			--with-qt-libraries=${QT_LIBDIR} \
			--with-extra-libs=${LOCALBASE}/lib \
			--with-extra-includes=${LOCALBASE}/include
CONFIGURE_ENV+=	MOC="${MOC}" UIC="${UIC}" LIBS="${QTCFGLIBS}" \
		QMAKE="${QMAKE}" QMAKESPEC="${QMAKESPEC}" QTDIR="${QT_PREFIX}"
MAKE_ENV+=	QMAKESPEC="${QMAKESPEC}"

PLIST_SUB+=	QT_INCDIR_REL=${QT_INCDIR_REL} \
		QT_LIBDIR_REL=${QT_LIBDIR_REL} \
		QT_PLUGINDIR_REL=${QT_PLUGINDIR_REL}

6.10.2 Component Selection (Qt 4.x Only)

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.

USE_QT4=	gui moc_build qmake_build rcc_build uic_build

6.10.3 Additional Considerations

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

HAS_CONFIGURE=	yes

do-configure:
	@cd ${WRKSRC} && ${SETENV} ${CONFIGURE_ENV} \
		${QMAKE} ${QMAKEFLAGS} PREFIX=${PREFIX} texmaker.pro

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:

• Missing additional include paths. Many applications come with system tray icon support, but neglect to look for includes and/or libraries in the X11 directories. You can tell qmake to add directories to the include and library search paths via the command line, for example:

  ${QMAKE} ${QMAKEFLAGS} PREFIX=${PREFIX} INCLUDEPATH+=${LOCALBASE}/include \
  	LIBS+=-L${LOCALBASE}/lib sillyapp.pro
  

• Bogus installation paths. Sometimes data such as icons or .desktop files are by default installed into directories which are not scanned by XDG-compatible applications. editors/texmaker is an example for this - look at patch-texmaker.pro in the files directory of that port for a template on how to remedy this directly in the qmake project file.

6.11.1 Variable Definitions (KDE 3.x Only)

6.11.2 KDE 4 Variable Definitions

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, to avoid conflicts with KDE 3.x ports. 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.

USE_CMAKE=	yes
USE_KDE4=	kdelibs kdeprefix automoc4
USE_QT4=	moc_build qmake_build rcc_build uic_build

6.12.1 Variable Definitions

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

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

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

6.12.2 Building with Ant

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

6.12.3 Best Practices

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

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

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

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

The default value for DATADIR is ${PREFIX}/share/${PORTNAME}. It is a good idea to override DATADIR to ${JAVASHAREDIR}/${PORTNAME} for Java ports. Indeed, DATADIR is automatically added to PLIST_SUB (documented in Section 7.1) 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.

6.13.1 Apache

6.13.2 Web Applications

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.

6.13.3 PHP

6.13.4 PEAR Modules

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.

PORTNAME=       Date
PORTVERSION=	1.4.3
CATEGORIES=	devel www pear

MAINTAINER=	example@domain.com
COMMENT=	PEAR Date and Time Zone Classes

BUILD_DEPENDS=	${PEARDIR}/PEAR.php:${PORTSDIR}/devel/pear-PEAR
RUN_DEPENDS:=	${BUILD_DEPENDS}

FILES=		Date.php Date/Calc.php Date/Human.php Date/Span.php     \
		Date/TimeZone.php
TESTS=		test_calc.php test_date_methods_span.php testunit.php   \
		testunit_date.php testunit_date_span.php wknotest.txt   \
		bug674.php bug727_1.php bug727_2.php bug727_3.php       \
		bug727_4.php bug967.php weeksinmonth_4_monday.txt       \
		weeksinmonth_4_sunday.txt weeksinmonth_rdm_monday.txt   \
		weeksinmonth_rdm_sunday.txt
DOCS=		TODO
_DOCSDIR=	.

.include <bsd.port.pre.mk>
.include "${PORTSDIR}/devel/pear/bsd.pear.mk"
.include <bsd.port.post.mk>

6.19.1 Introduction

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.

6.19.2 Version Selection

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

6.19.3 Component Selection

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-31). The following types are available:

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

USE_WX=		2.4
WX_COMPS=	wx contrib

6.19.4 Unicode

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:

6.19.5 Detecting Installed Versions

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.

WANT_WX=	yes

.include <bsd.port.pre.mk>

.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4)
USE_WX=			2.4
CONFIGURE_ARGS+=	--enable-wx
.endif

USE_WX=		2.6
WX_COMPS=	wx
WANT_WX=	2.6

.include <bsd.port.pre.mk>

.if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython)
WX_COMPS+=		python
CONFIGURE_ARGS+=	--enable-wxpython
.endif

6.19.6 Defined Variables

The following variables are available in the port (after defining one from Table 6-25).

6.19.7 Processing in bsd.port.pre.mk

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

USE_WX=		2.4
WX_PREMK=	yes

.include <bsd.port.pre.mk>

.if exists(${WX_CONFIG})
VER_STR!=	${WX_CONFIG} --release

PLIST_SUB+=	VERSION="${VER_STR}"
.endif

6.19.8 Additional configure Arguments

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.

6.20.1 Introduction

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.

6.20.2 Version Selection

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

USE_LUA=	5.0-5.1
WANT_LUA_VER=	5.0

6.20.3 Component Selection

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-41). The following types are available:

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

USE_LUA=	4.0
LUA_COMPS=	lua ruby

6.20.4 Detecting Installed Versions

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.

WANT_LUA=	yes

.include <bsd.port.pre.mk>

.if defined(WITH_LUA5) || !empty(PORT_OPTIONS:MLUA5) || !empty(HAVE_LUA:Mlua-5.[01])
USE_LUA=		5.0-5.1
CONFIGURE_ARGS+=	--enable-lua5
.endif

USE_LUA=	4.0
LUA_COMPS=	lua
WANT_LUA=	4.0

.include <bsd.port.pre.mk>

.if defined(WITH_TOLUA) || !empty(PORT_OPTIONS:MTOLUA) || !empty(HAVE_LUA:Mtolua)
LUA_COMPS+=		tolua
CONFIGURE_ARGS+=	--enable-tolua
.endif

6.20.5 Defined Variables

The following variables are available in the port (after defining one from Table 6-35).

USE_LUA=	4.0
GNU_CONFIGURE=	yes
CONFIGURE_ENV=	CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"

6.20.6 Processing in bsd.port.pre.mk

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

USE_LUA=	5.0
LUA_PREMK=	yes

.include <bsd.port.pre.mk>

.if exists(${LUA_CMD})
VER_STR!=	${LUA_CMD} -v

CFLAGS+=	-DLUA_VERSION_STRING="${VER_STR}"
.endif

6.24.1 Stopping Services at Deinstall

It is possible to have a service stopped automatically as part of the deinstall routine. We advise using this feature only when it is absolutely necessary to stop a service before its files go away. Usually, it is up to the administrator's discretion to decide, whether to stop the service on deinstall or not. Also note this affects upgrades, too.

A line like this goes in the pkg-plist:

@stopdaemon doormand

The argument must match the content of USE_RC_SUBR variable.

6.24.2 Pre-Commit Checklist

Before contributing a port with an rc.d script, and more importantly, before committing one, please consult the following checklist to be sure that it is ready.

7.2.1 Cleaning Up Empty Directories

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

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

However, sometimes @dirrm will give you errors because other ports share the same directory. You can use @dirrmtry to remove only empty directories without warning.

@dirrmtry share/doc/gimp

This will neither print any error messages nor cause pkg_delete(1) to exit abnormally even if ${PREFIX}/share/doc/gimp is not empty due to other ports installing some files in there.

7.2.2 Creating Empty Directories

Empty directories created during port installation need special attention. They will not get created when installing the package, because packages only store the files, and pkg_add(1) creates directories for them as needed. To make sure the empty directory is created when installing the package, add this line to pkg-plist above the corresponding @dirrm line:

@exec mkdir -p %D/share/foo/templates