# Makefile Options

FreeBSD Porter's Handbook
Prev | Chapter 5 ³]©w Makefile | Next

# 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

### 5.11.1.1 `WITH_`*`` and `WITHOUT_`*``

These variables are designed to be set by the system administrator. There are many that are standardized in `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 some kind of variable such as `YES` or `NO`.

Table 5-2. 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` | 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.

### 5.11.1.2 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`

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

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.

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

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

### 5.11.2.3 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
    .else
    CONFIGURE_ARGS+=	--with-foo
    .endif

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

    .include <bsd.port.post.mk>

## 5.11.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-9. Wrong handling of an option

    .if defined(WITH_FOO)
    LIB_DEPENDS+=          foo.0:${PORTSDIR}/devel/foo
    CONFIGURE_ARGS+=       --enable-foo
    .endif

In the example above, imagine a library libfoo is installed on the system. 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 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-10. Correct handling of an option

    .if defined(WITH_FOO)
    LIB_DEPENDS+=          foo.0:${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.

Prev | Home | Next
Info files | Up | Specifying the working directory

For questions about the FreeBSD ports system, e-mail <ports@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.