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.
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-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 | 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. |
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.
The OPTIONS_* variables give the user who installs the port a dialog with the available options and saves them to /var/db/ports/${UNIQUENAME}/options. Next time when the port has to be rebuilt, the options are reused.
When the user runs make config (or runs make build for the first time), the framework will check for /var/db/ports/${UNIQUENAME}/options. If that file does not exist, it will use the values of OPTIONS_* to create a dialog box 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.
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 optionally described:
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.
OPTIONS can be grouped as radio choices (only one choice from each group allowed):
OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4
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 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+=--without-foo
.else
CONFIGURE_ARGS+=--with-foo
.endif
.if ${PORT_OPTIONS:MBAR}
RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar
.endif
.include <bsd.port.mk>
Example 5-11. 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
# Check other OPTIONS
.include <bsd.port.mk>
Example 5-12. Old-Style Use of OPTIONS
OPTIONS= FOO "Enable option foo" On .include <bsd.port.pre.mk> .if defined(WITHOUT_FOO) CONFIGURE_ARGS+= --without-foo .else CONFIGURE_ARGS+= --with-foo .endif .include <bsd.port.post.mk>
Important: This method of using OPTIONS is deprecated, and will be removed at some point. It should not be included in new ports.
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.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-14. Correct Handling of an Option
.if ${PORT_OPTIONS:MFOO}
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.