5.7 Dependencies

Many ports depend on other ports. This is very convenient and nice feature of most Unix-like operating systems, including FreeBSD. It allows not having to bundle common dependencies with every port or package, since a lot of ports would share them. 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.7.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.9:${PORTSDIR}/graphics/jpeg
will check for a shared jpeg library with major version 9, 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.[5-7] and intl are allowed. The first pattern, intl.[5-7], will match any of: intl.5, intl.6 or intl.7. The second pattern, intl, will match any version of the intl library.

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.7.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}/etc/innd:${PORTSDIR}/news/inn \
           xmlcatmgr:${PORTSDIR}/textproc/xmlcatmgr

will check if the file or directory /usr/local/etc/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:/usr/X11R6/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}

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

5.7.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.7.7 USE_*

A number of variables exist in order to encapsulate common dependencies that many ports have. Although their use is optional, they can help to reduce the verbosity of the port Makefiles. Each of them is styled as USE_*. The usage of these variables is restricted to the port Makefiles and ports/Mk/bsd.*.mk and is not designed to encapsulate user-settable options -- use WITH_* and WITHOUT_* for that purpose.

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

USE_GCC=3.4
would 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.6. X11 variables are listed in Section 6.7. Section 6.8 deals with GNOME and Section 6.10 with KDE related variables. Section 6.11 documents Java variables, while Section 6.12 contains information on Apache, PHP and PEAR modules. Python is discussed in Section 6.13, while Ruby in Section 6.16. Section 6.17 provides variables used for SDL applications and finally, Section 6.20 contains information on Xfce.

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

For questions about the FreeBSD ports system, e-mail <[email protected]>.
For questions about this documentation, e-mail <[email protected]>.