5.8. Dependencies

Many ports depend on other ports. This is a very convenient feature of most Unix-like operating systems, including FreeBSD. Multiple ports can share a common dependency, rather than bundling that dependency with every port or package that needs it. There are seven variables that can be used to ensure that all the required bits will be on the user's machine. There are also some pre-supported dependency variables for common cases, plus a few more to control the behavior of dependencies.

5.8.1. LIB_DEPENDS

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,

LIB_DEPENDS= libjpeg.so:${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 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.

Note:

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

Note:

The official search PATH used on the ports build cluster is

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

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

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.

Note:

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

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.

Note:

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

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

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:

USES= feature[:arguments]

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

Warning:

USES cannot be assigned after inclusion of bsd.port.pre.mk.

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

Note:

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

USE_GCC=X.Y

(where X.Y is version number) would add a dependency on gccXY for every port, including lang/gccXY itself!

Table 5.2. The USE_* Variables
VariableMeans
USE_BZIP2The port's tarballs are compressed with bzip2.
USE_ZIPThe port's tarballs are compressed with zip.
USE_GCCThe port requires GCC (gcc or g++) to build. Some ports need any GCC version, some require modern, recent versions. It is typically set to any (in this case, GCC from base would be used on versions of FreeBSD that still have it, or lang/gcc port would be installed when default C/C++ compiler is Clang); or yes (means always use stable, modern GCC from lang/gcc port). The exact version can be also specified, with a value such as 4.7. The minimal required version can be specified as 4.6+. The GCC from the base system is used when it satisfies the requested version, otherwise an appropriate compiler in built from the port, and the CC and CXX variables are adjusted accordingly.

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.

5.8.9. 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.10. 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.11. Circular Dependencies Are Fatal

Important:

Do not introduce any circular dependencies into the ports tree!

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

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

Example 5.8. Wrong Declaration of an Optional Dependency
.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.

Example 5.9. Correct Declaration of an Optional Dependency
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.13. 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.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.

Send questions about this document to <freebsd-doc@FreeBSD.org>.