5.11 Makefile Options

Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Examples include choice of natural (human) language, GUI versus command-line, or type of database to support. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to control which configuration should be built. Supporting these properly will make users happy, and effectively provide 2 or more ports for the price of one.

5.11.1 KNOBS WITH_* and WITHOUT_*

These variables are designed to be set by the system administrator. There are many that are standardized in ports/Mk/bsd.*.mk; others are not, which can be confusing. If you need to add such a configuration variable, please consider using one of the ones from the following list.

Note: You should not assume that a WITH_* necessarily has a corresponding WITHOUT_* variable and vice versa. In general, the default is simply assumed.

Note: Unless otherwise specified, these variables are only tested for being set or not set, rather than being set to some kind of variable such as YES or NO.

Table 5-2. The WITH_* and WITHOUT_* variables

Variable Means
WITH_APACHE2 If set, use www/apache20 instead of the default of www/apache13.
WITH_BERKELEY_DB Define this variable to specify the ability to use a variant of the Berkeley database package such as databases/db41. An associated variable, WITH_BDB_VER, may be set to values such as 2, 3, 4, 41 or 42.
WITH_MYSQL Define this variable to specify the ability to use a variant of the MySQL database package such as databases/mysql40-server. An associated variable, WANT_MYSQL_VER, may be set to values such as 323, 40, 41, or 50.
WITHOUT_NLS If set, says that internationalization is not needed, which can save compile time. By default, internationalization is used.
WITH_OPENSSL_BASE Use the version of OpenSSL in the base system.
WITH_OPENSSL_PORT Use the version of OpenSSL from security/openssh, overwriting the version that was originally installed in the base system.
WITH_POSTGRESQL Define this variable to specify the ability to use a variant of the PostGreSQL database package such as databases/postgresql72.
WITHOUT_X11 If the port can be built both with and without X support, then it should normally be built with X support. If this variable is defined, then the version that does not have X support should be built instead. Knob naming

It is recommended that porters use like-named knobs, for the benefit of end-users and to help keep the number of knob names down. A list of popular knob names can be found in the KNOBS file.

Knob names should reflect what the knob is and does. When a port has a lib-prefix in the PORTNAME the lib-prefix should be dropped in knob naming.

5.11.2 OPTIONS Background

The OPTIONS variable gives the user who installs the port a dialog with the available options and saves them to /var/db/ports/portname/options. Next time when the port has to be rebuild, the options are reused. Never again you will have to remember all the twenty WITH_* and WITHOUT_* options you used to build this port!

When the user runs make config (or runs make build for the first time), the framework will check for /var/db/ports/portname/options. If that file does not exist, it will use the values of OPTIONS to create a dialogbox where the options can be enabled or disabled. Then the options file is saved and the selected variables will be used when building the port.

Use make showconfig to see the saved configuration. Use make rmconfig to remove the saved configuration. Syntax

The syntax for the OPTIONS variable is:

OPTIONS=   OPTION  "descriptive text" default ...
The value for default is either ON or OFF. Multiple repetitions of these three fields are allowed.

OPTIONS definition must appear before the inclusion of bsd.port.pre.mk. The WITH_* and WITHOUT_* variables can only be tested after the inclusion of bsd.port.pre.mk.

Due to a deficiency in the infrastructure, you can only test WITH_* variables for options which are OFF by default, and WITHOUT_* variables for options which default to ON. The reasoning behind this: when packages are built with PACKAGE_BUILDING or BATCH defined, the config target is not run, and therefore no OPTIONS are selected. This would cause make depends and make describe to break for ports not following the aforementioned rule. Example

Example 5-8. Simple use of OPTIONS

OPTIONS=      FOO "Enable option foo" On \
              BAR "Support feature bar" Off

.include <bsd.port.pre.mk>

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

.if defined(WITH_BAR)
RUN_DEPENDS+=   bar:${PORTSDIR}/bar/bar

.include <bsd.port.post.mk>

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