5.12. Makefile Options
Prev | Chapter 5. Configuring the Makefile | Next

## 5.12. Makefile Options

Many applications can be built with optional or differing configurations. Examples include choice of natural (human) language, GUI versus command-line, or type of database to support. Users may need a different configuration than the default, so the ports system provides hooks the port author can use to control which variant will be built. Supporting these options properly will make users happy, and effectively provide two or more ports for the price of one.

### 5.12.1. Knobs

#### 5.12.1.1. `WITH_`*`` and `WITHOUT_`*``

These variables are designed to be set by the system administrator. There are many that are standardized in the `ports/KNOBS` file.

When creating a port, do not make knob names specific to a given application. For example in Avahi port, use `WITHOUT_MDNS` instead of `WITHOUT_AVAHI_MDNS`.

### 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 a specific value such as `YES` or `NO`.

Table 5.3. Common `WITH_`*`` and `WITHOUT_`*`` Variables

Variable | Means
--- | ---
`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` | Installs the version of OpenSSL from `security/openssl`, even if the base is up to date.
`WITHOUT_X11` | Ports that can be built both with and without X support are normally built with X support. If this variable is defined, then the version that does not have X support will be built instead.

#### 5.12.1.2. Knob Naming

Porters should use like-named knobs, both 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.12.2. `OPTIONS`

#### 5.12.2.1. Background

The `OPTIONS_*` variables give the user installing the port a dialog showing the available options, and then saves those options to `/var/db/ports/`${UNIQUENAME}`/options`. The next time the port is built, the options are reused.

When the user runs `make config` (or runs `make build` for the first time), the framework checks for `/var/db/ports/`${UNIQUENAME}`/options`. If that file does not exist, the values of `OPTIONS_*` are used, and a dialog box is displayed where the options can be enabled or disabled. Then the `options` file is saved and the configured variables are used when building the port.

If a new version of the port adds new `OPTIONS`, the dialog will be presented to the user with the saved values of old `OPTIONS` prefilled.

`make showconfig` shows the saved configuration. Use `make rmconfig` to remove the saved configuration.

#### 5.12.2.2. Syntax

`OPTIONS_DEFINE` contains a list of `OPTIONS` to be used. These are independent of each other and are not grouped:

OPTIONS_DEFINE= OPT1 OPT2

Once defined, `OPTIONS` are described (optional, but strongly recommended):

OPT1_DESC= Describe OPT1 OPT2_DESC= Describe OPT2 OPT3_DESC= Describe OPT3 OPT4_DESC= Describe OPT4 OPT5_DESC= Describe OPT5 OPT6_DESC= Describe OPT6

### Tip:

`ports/Mk/bsd.options.desc.mk` has descriptions for many common `OPTIONS`; there is usually no need to override these.

### Tip:

When describing options, view it from the perspective of the user: “What does it do?” and “Why would I want to enable this?” Do not just repeat the name. For example, describing the `NLS` option as “include NLS support” does not help the user, who can already see the option name but may not know what it means. Describing it as “Native Language Support via gettext utilities” is much more helpful.

`OPTIONS` can be grouped as radio choices, where only one choice from each group is allowed:

OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4

`OPTIONS` can be grouped as radio choices, where none or only one choice from each group is allowed:

OPTIONS_RADIO= RG1 OPTIONS_RADIO_RG1= OPT7 OPT8

`OPTIONS` can also be grouped as “multiple-choice” lists, where at least one option must be enabled:

OPTIONS_MULTI= MG1 OPTIONS_MULTI_MG1= OPT5 OPT6

`OPTIONS` can also be grouped as “multiple-choice” lists, where none or any option can be enabled:

OPTIONS_GROUP= GG1 OPTIONS_GROUP_GG1= OPT9 OPT10

`OPTIONS` are unset by default, unless they are listed in `OPTIONS_DEFAULT`:

OPTIONS_DEFAULT= OPT1 OPT3 OPT6

`OPTIONS` definitions must appear before the inclusion of `bsd.port.options.mk`. The `PORT_OPTIONS` variable can only be tested after the inclusion of `bsd.port.options.mk`. Inclusion of `bsd.port.pre.mk` can be used instead, too, and is still widely used in ports written before the introduction of `bsd.port.options.mk`. But be aware that some variables will not work as expected after the inclusion of `bsd.port.pre.mk`, typically some `USE_*` flags.

Example 5.10. Simple Use of `OPTIONS`
OPTIONS_DEFINE= FOO BAR FOO_DESC= Enable option foo BAR_DESC= Support feature bar OPTIONS_DEFAULT=FOO .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MFOO} CONFIGURE_ARGS+=--with-foo .else CONFIGURE_ARGS+=--without-foo .endif .if ${PORT_OPTIONS:MBAR} RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar .endif .include <bsd.port.mk>
Example 5.11. Check for Unset Port `OPTIONS`
.if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif
Example 5.12. Practical Use of `OPTIONS`
OPTIONS_DEFINE= EXAMPLES OPTIONS_SINGLE= BACKEND OPTIONS_SINGLE_BACKEND= MYSQL PGSQL BDB OPTIONS_MULTI= AUTH OPTIONS_MULTI_AUTH= LDAP PAM SSL EXAMPLES_DESC= Install extra examples MYSQL_DESC= Use MySQL as backend PGSQL_DESC= Use PostgreSQL as backend BDB_DESC= Use Berkeley DB as backend LDAP_DESC= Build with LDAP authentication support PAM_DESC= Build with PAM support SSL_DESC= Build with OpenSSL support OPTIONS_DEFAULT= PGSQL LDAP SSL .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MPGSQL} USE_PGSQL= yes CONFIGURE_ARGS+= --with-postgres .else CONFIGURE_ARGS+= --without-postgres .endif .if ${PORT_OPTIONS:MICU} LIB_DEPENDS+= icuuc:${PORTSDIR}/devel/icu .endif .if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+= --without-examples .endif # Check other OPTIONS .include <bsd.port.mk>

#### 5.12.2.3. Default Options

The following options are always on by default.

- `DOCS` — build and install documentation.

- `NLS` — Native Language Support.

- `EXAMPLES` — build and install examples.

- `IPV6` — IPv6 protocol support.

### Note:

There is no need to add these to `OPTIONS_DEFAULT`. To have them show up in the options selection dialog, however, they must be added to `OPTIONS_DEFINE`.

### 5.12.3. Feature Auto-Activation

When using a GNU configure script, keep an eye on which optional features are activated by auto-detection. Explicitly disable optional features you do not wish to be used by passing respective `--without-xxx` or `--disable-xxx` in `CONFIGURE_ARGS`.

Example 5.13. Wrong Handling of an Option
.if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= foo:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .endif

In the example above, imagine a library libfoo is installed on the system. The user does not want this application to use libfoo, so he toggled the option off in the `make config` dialog. But the application's configure script detects the library present in the system and includes its support in the resulting executable. Now when the user decides to remove libfoo from the system, the ports system does not protest (no dependency on libfoo was recorded) but the application breaks.

Example 5.14. Correct Handling of an Option
.if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= foo:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .else CONFIGURE_ARGS+= --disable-foo .endif

In the second example, the library libfoo is explicitly disabled. The configure script does not enable related features in the application, despite library's presence in the system.

### Note:

Under some circumstances, the shorthand conditional syntax can cause problems with complex constructs. If you receive errors such as `Malformed conditional`, an alternative syntax can be used.

.if !empty(VARIABLE:MVALUE) # as an alternative to .if ${VARIABLE:MVALUE}

Prev | Up | Next
5.11. Info Files | Home | 5.13. Specifying the Working Directory

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