5.8. Dependencies
Prev | Chapter 5. Configuring the Makefile | Next

## 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`[`: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.

### 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, `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.

### 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 `Makefile`s. Each of them is styled as `USE_`*``. These variables may be used only in the port `Makefile`s 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.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_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, “Building Mechanisms”, while autoconf, automake and libtool are described in Section 6.4, “Using GNU Autotools”. Perl related variables are described in Section 6.6, “Using Perl”. X11 variables are listed in Section 6.7, “Using X11”. Section 6.8, “Using GNOME” deals with GNOME and Section 6.10, “Using KDE” with KDE related variables. Section 6.11, “Using Java” documents Java variables, while Section 6.12, “Web Applications, Apache and PHP” contains information on Apache, PHP and PEAR modules. Python is discussed in Section 6.13, “Using Python”, while Ruby in Section 6.16, “Using Ruby”. Section 6.17, “Using SDL” provides variables used for SDL applications and finally, Section 6.20, “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`.

Prev | Up | Next
5.7. `PORTSCOUT` | Home | 5.9. `MASTERDIR`

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.