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.
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.
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
ports/Mk/bsd.options.desc.mk
has descriptions for many common OPTIONS
.
While often useful, they should be overridden if the
description is insufficient for the port.
When describing options, view it from the
perspective of the user: “What functionality does it
change?”
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.
Option names should always be in all uppercase. They should not use mixed case or lowercase.
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.
OPTIONS
OPTIONS_DEFINE= FOO BAR FOO_DESC= Option foo support BAR_DESC= Feature bar support OPTIONS_DEFAULT=FOO # Will add --with-foo / --without-foo FOO_CONFIGURE_WITH= foo BAR_RUN_DEPENDS= bar:${PORTSDIR}/bar/bar .include <bsd.port.mk>
OPTIONS
.if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif
Though, you should use the following so that the configure knob is really enabled and disabled when the option is.
# Will add --with-examples / --without-examples EXAMPLES_CONFIGURE_WITH= examples
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 PGSQL_USE= pgsql=yes # Will add --enable-postgres / --disable-postgres PGSQL_CONFIGURE_ENABLE= postgres ICU_LIB_DEPENDS= libicuuc.so:${PORTSDIR}/devel/icu # Will add --with-examples / --without-examples EXAMPLES_CONFIGURE_WITH= examples # Check other OPTIONS .include <bsd.port.mk>
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.
There is no need to add these to
OPTIONS_DEFAULT
. To have them active,
and show up in the options selection dialog, however, they
must be added to OPTIONS_DEFINE
.
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
.
.if ${PORT_OPTIONS:MFOO} LIB_DEPENDS+= libfoo.so:${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.
FOO_LIB_DEPENDS= libfoo.so:${PORTSDIR}/devel/foo # Will add --enable-foo / --disable-foo FOO_CONFIGURE_ENABLE= foo
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}
There are some macros to help simplify conditional values which differ based on the options set.
If OPTIONS_SUB
is set to
yes
then each of the options added to
OPTIONS_DEFINE
will be added to
PLIST_SUB
and
SUB_LIST
, for example:
OPTIONS_DEFINE= OPT1 OPTIONS_SUB= yes
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} PLIST_SUB+= OPT1="" NO_OPT1="@comment " SUB_LIST+= OPT1="" NO_OPT1="@comment " .else PLIST_SUB+= OPT1="@comment " NO_OPT1="" SUB_LIST+= OPT1="@comment " NO_OPT1="" .endif
The value of OPTIONS_SUB
is
ignored. Setting it to any value will add
PLIST_SUB
and
SUB_LIST
entries for
all options.
For each
pair in
key
=value
the
corresponding
OPT
_USEUSE_
variable will be set to KEY
value
.
If value
has spaces in it,
replace them with commas, they will be changed back to
spaces during processing. For example:
OPTIONS_DEFINE= OPT1 OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} USE_MYSQL= yes USE_XORG= x11 xextproto xext xrandr .endif
If
is set then
OPT
_CONFIGURE_ENABLE--enable-${
or
OPT
_CONFIGURE_ENABLE}--disable-${
will be added to OPT
_CONFIGURE_ENABLE}CONFIGURE_ARGS
depending
on the value of the option
, for
example:OPT
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ENABLE= test
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --enable-test .else CONFIGURE_ARGS+= --disable-test .endif
If
is set then
OPT
_CONFIGURE_WITH--with-${
or
OPT
_CONFIGURE_WITH}--without-${
will be added to OPT
_CONFIGURE_WITH}CONFIGURE_ARGS
depending
on the status of the option
. An
optional argument can be specified with an
OPT
=
symbol. This argument is only appended
to the
--with-
configure option. For example:opt
OPTIONS_DEFINE= OPT1 OPT2 OPT1_CONFIGURE_WITH= test1 OPT1_CONFIGURE_WITH= test2=exhaustive
is equivalent to:
OPTIONS_DEFINE= OPT1 OPT2 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --with-test1 .else CONFIGURE_ARGS+= --without-test1 .endif .if ${PORT_OPTIONS:MOPT2} CONFIGURE_ARGS+= --with-test2=exhaustive .else CONFIGURE_ARGS+= --without-test2 .endif
If
is set then its value will be appended to
OPT
_CONFIGURE_ONCONFIGURE_ARGS
depending on the status of
the option
, for
example:OPT
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ON= --add-test
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --add-test .endif
If
is set then its value will be appended to
OPT
_CONFIGURE_OFFCONFIGURE_ARGS
depending on the status of
the option
, for
example:OPT
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_OFF= --no-test
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ! ${PORT_OPTIONS:MOPT1} CONFIGURE_ARGS+= --no-test .endif
If
is set then its value will be appended to
OPT
_CMAKE_ONCMAKE_ARGS
depending on the status of the
option
,
for example:OPT
OPTIONS_DEFINE= OPT1 OPT1_CMAKE_ON= -DTEST:BOOL=true
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=true .endif
If
is set then its value will be appended to
OPT
_CMAKE_OFFCMAKE_ARGS
depending on the status of the
option
,
for example:OPT
OPTIONS_DEFINE= OPT1 OPT1_CMAKE_OFF= -DTEST:BOOL=false
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ! ${PORT_OPTIONS:MOPT1} CMAKE_ARGS+= -DTEST:BOOL=false .endif
For any of the following dependency type:
PKG_DEPENDS
EXTRACT_DEPENDS
PATCH_DEPENDS
FETCH_DEPENDS
BUILD_DEPENDS
LIB_DEPENDS
RUN_DEPENDS
If
is defined then its value will be appended to
OPT
_ABOVEVARIABLE
depending on the status of the option
ABOVEVARIABLE
, for
example:OPT
OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a .endif
If
is set then a dependency of type
OPT
_ABOVEVARIABLE
_OFF
will be added when option
ABOVEVARIABLE
is not
selected. For example:OPT
OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS_OFF= liba.so:${PORTSDIR}/devel/a
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> . if ! ${PORT_OPTIONS:MOPT1} LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a .endif
For any of the following variables:
ALL_TARGET
CATEGORIES
CFLAGS
CPPFLAGS
CXXFLAGS
CONFIGURE_ENV
CONFLICTS
CONFLICTS_BUILD
CONFLICTS_INSTALL
DISTFILES
EXTRA_PATCHES
INFO
INSTALL_TARGET
LDFLAGS
MAKE_ARGS
MAKE_ENV
PATCH_SITES
PATCHFILES
PLIST_FILES
PLIST_DIRS
PLIST_DIRSTRY
PLIST_SUB
USES
Some of these variables, at least
ALL_TARGET
and
INSTALL_TARGET
, have their default
values set after the options are
processed.
With the following lines in the
Makefile
:
ALL_TARGET= all DOCS_ALL_TARGET= doc
If the DOCS
option is enabled,
ALL_TARGET
will have a final value of
all doc
; if the option is disabled, it
would have a value of all
.
With only the options helper line in the
Makefile
:
DOCS_ALL_TARGET= doc
If the DOCS
option is enabled,
ALL_TARGET
will have a final value of
doc
; if the option is disabled, it
would have a value of all
.
If
is defined then its value will be appended to
OPT
_ABOVEVARIABLE
depending on the status of the option
ABOVEVARIABLE
, for
example:OPT
OPTIONS_DEFINE= OPT1 OPT1_USES= gmake OPT1_CFLAGS= -DTEST
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MOPT1} USES+= gmake CFLAGS+= -DTEST .endif
If
is set then a flag
OPT
_ABOVEVARIABLE
_OFF
will be automatically set when option
ABOVEVARIABLE
is not
selected. For example:OPT
OPTIONS_DEFINE= OPT1 OPT1_USES_OFF=gmake
is equivalent to:
OPTIONS_DEFINE= OPT1 .include <bsd.port.options.mk> .if ! ${PORT_OPTIONS:MOPT1} USES+= gmake .endif
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.