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.
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).
Note: The lib part is a regular expression which is being looked up in the ldconfig -r output. Values such as intl.9 and intl.[5-7] are allowed. The first pattern, intl.9, will match only version 9 of intl, while intl.[5-7], will match any of: intl.5, intl.6 or intl.7.
The dependency is checked twice, once from within the extract target and then from within the install target. Also, the name of the dependency is put into the package so that pkg_add(1) will automatically install it if it is not on the user's system.
This variable specifies executables or files this port depends on during run-time. It is a list of path:dir[:target] tuples where path is the name of the executable or file, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. If path starts with a slash (/), it is treated as a file and its existence is tested with test -e; otherwise, it is assumed to be an executable, and which -s is used to determine if the program exists in the search path.
For example,
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, 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}
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
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.
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.7.
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.
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=3.4would add a dependency on gcc34 for every port, including gcc34 itself!
Table 5-2. The USE_* Variables
| Variable | Means |
|---|---|
| USE_BZIP2 | The port's tarballs are compressed with bzip2. |
| USE_ZIP | The port's tarballs are compressed with zip. |
| USE_BISON | The port uses bison for building. |
| USE_CDRTOOLS | The port requires cdrecord either from sysutils/cdrtools or sysutils/cdrtools-cjk, according to the user's preference. |
| USE_GCC | The port requires a specific version of gcc to build. The exact version can be specified with value such as 3.4. The minimal required version can be specified as 3.4+. The gcc from the base system is used when it satisfies the requested version, otherwise an appropriate gcc is compiled from ports and the CC and CXX variables are adjusted. |
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.
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.
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.
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.
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.
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.