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.
OPTIONS_
give the user installing the port a dialog showing the
available options, and then saves those options to
*${PORT_DBDIR}/${OPTIONS_NAME}/options.
The next time the port is built, the options are
reused. PORT_DBDIR defaults to
/var/db/ports.
OPTIONS_NAME is to the port origin with
an underscore as the space separator, for example, for
dns/bind99 it will be
dns_bind99.
When the user runs make config (or
runs make build for the first time), the
framework checks for
${PORT_DBDIR}/${OPTIONS_NAME}/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 *options 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 OPT2Once 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 OPT6ports/Mk/bsd.options.desc.mk
has descriptions for many common OPTIONS.
While often useful, override them 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 are always in all uppercase. They cannot 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 OPT4There must be one of each
OPTIONS_SINGLE group selected at all
times for the options to be valid. One option of each
group must be added to
OPTIONS_DEFAULT.
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 OPT8OPTIONS can also be grouped as
“multiple-choice” lists, where
at least one option must be
enabled:
OPTIONS_MULTI= MG1
OPTIONS_MULTI_MG1= OPT5 OPT6OPTIONS can also be grouped as
“multiple-choice” lists, where none or any
option can be enabled:
OPTIONS_GROUP= GG1
OPTIONS_GROUP_GG1= OPT9 OPT10OPTIONS are unset by default,
unless they are listed in
OPTIONS_DEFAULT:
OPTIONS_DEFAULT= OPT1 OPT3 OPT6OPTIONS definitions must appear
before the inclusion of
bsd.port.options.mk.
PORT_OPTIONS values 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.*
OPTIONSOPTIONS_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
.endifThe form shown above is discouraged. The preferred method is using a configure knob to really enable and disable the feature to match the option:
# Will add --with-examples / --without-examples
EXAMPLES_CONFIGURE_WITH= examplesOPTIONSOPTIONS_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
# Will add USE_PGSQL=yes
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>These 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 that are not needed by
adding --without-xxx or
--disable-xxx in
CONFIGURE_ARGS.
.if ${PORT_OPTIONS:MFOO}
LIB_DEPENDS+= libfoo.so:${PORTSDIR}/devel/foo
CONFIGURE_ARGS+= --enable-foo
.endifIn 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= fooUnder some circumstances, the shorthand conditional
syntax can cause problems with complex constructs. The
errors are usually
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= yesis 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=""
.endifThe value of OPTIONS_SUB is
ignored. Setting it to any value will add
PLIST_SUB and
SUB_LIST entries for
all options.
When option OPT is selected,
for each
pair in
key=value,
OPT_USEvalue is appended to the
corresponding
USE_. If
KEYvalue has spaces in it, replace
them with commas and they will be changed back to spaces
during processing.
works the same way, but when OPT_USE_OFFOPT is
not selected. For example:
OPTIONS_DEFINE= OPT1 OPT1_USE= mysql=yes xorg=x11,xextproto,xext,xrandr OPT1_USE_OFF= openssl=yes
is equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
USE_MYSQL= yes
USE_XORG= x11 xextproto xext xrandr
.else
USE_OPENSSL= yes
.endifWhen option OPT is selected,
for each entry in
then
OPT_CONFIGURE_ENABLE--enable-
is appended to entryCONFIGURE_ARGS. When
option OPT is
not selected,
--disable-
is appended to entryCONFIGURE_ARGS. An
optional argument can be specified with an
= symbol. This argument is only appended
to the
--enable-
configure option. For example:entry
OPTIONS_DEFINE= OPT1 OPT2 OPT1_CONFIGURE_ENABLE= test1 test2 OPT2_CONFIGURE_ENABLE= test2=exhaustive
is equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
CONFIGURE_ARGS+= --enable-test1 --enable-test2
.else
CONFIGURE_ARGS+= --disable-test1 --disable-test2
.endif
.if ${PORT_OPTIONS:MOPT2}
CONFIGURE_ARGS+= --enable-test2=exhaustive
.else
CONFIGURE_ARGS+= --disable-test2
.endifWhen option OPT is selected,
for each entry in
then
OPT_CONFIGURE_WITH--with-
is appended to entryCONFIGURE_ARGS. When
option OPT is
not selected,
--without-
is appended to entryCONFIGURE_ARGS. An
optional argument can be specified with an
= symbol. This argument is only appended
to the
--with-
configure option. For example:entry
OPTIONS_DEFINE= OPT1 OPT2 OPT1_CONFIGURE_WITH= test1 OPT2_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
.endifWhen option OPT is selected,
the value of
,
if defined, is appended to
OPT_CONFIGURE_ONCONFIGURE_ARGS.
works the same way, but when OPT_CONFIGURE_OFFOPT is
not selected. For example:
OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ON= --add-test OPT1_CONFIGURE_OFF= --no-test
is equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
CONFIGURE_ARGS+= --add-test
.else
CONFIGURE_ARGS+= --no-test
.endifWhen option OPT is selected,
the value of
,
if defined, is appended to OPT_CMAKE_ONCMAKE_ARGS.
works the same way, but when OPT_CMAKE_OFFOPT is
not selected. For example:
OPTIONS_DEFINE= OPT1 OPT1_CMAKE_ON= -DTEST:BOOL=true OPT1_CMAKE_OFF= -DOPTIMIZE:BOOL=true
is equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
CMAKE_ARGS+= -DTEST:BOOL=true
.else
CMAKE_ARGS+= -DOPTIMIZE:BOOL=true
.endifWhen option OPT is selected,
the value of
,
if defined, is appended to OPT_QMAKE_ONQMAKE_ARGS.
works the same way, but when OPT_QMAKE_OFFOPT is
not selected. For example:
OPTIONS_DEFINE= OPT1 OPT1_QMAKE_ON= -DTEST:BOOL=true OPT1_QMAKE_OFF= -DPRODUCTION:BOOL=true
is equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
QMAKE_ARGS+= -DTEST:BOOL=true
.else
QMAKE_ARGS+= -DPRODUCTION:BOOL=true
.endifProvides a way to add dependencies between options.
When OPT is selected, all the
options listed in this variable will be selected too. Using
the
described earlier to illustrate:OPT_CONFIGURE_ENABLE
OPTIONS_DEFINE= OPT1 OPT2 OPT1_IMPLIES= OPT2 OPT1_CONFIGURE_ENABLE= opt1 OPT2_CONFIGURE_ENABLE= opt2
Is equivalent to:
OPTIONS_DEFINE= OPT1 OPT2
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
CONFIGURE_ARGS+= --enable-opt1
.else
CONFIGURE_ARGS+= --disable-opt1
.endif
.if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1}
CONFIGURE_ARGS+= --enable-opt2
.else
CONFIGURE_ARGS+= --disable-opt2
.endifOPT_IMPLIESThis port has a X11 option, and a
GNOME option that needs the
X11 option to be selected to
build.
OPTIONS_DEFINE= X11 GNOME OPTIONS_DEFAULT= X11 X11_USE= xorg=xi,xextproto GNOME_USE= gnome=gtk30 GNOME_IMPLIES= X11
Provides a way to add conflicts between options.
When OPT is selected, all the
options listed in this variable must be un-selected. If
is also selected, its content will be shown, explaining why
they conflict. For example:OPT_PREVENTS_MSG
OPTIONS_DEFINE= OPT1 OPT2
OPT1_PREVENTS= OPT2
OPT1_PREVENTS_MSG= OPT1 and OPT2 enable conflicting optionsIs roughly equivalent to:
OPTIONS_DEFINE= OPT1 OPT2
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT2} || ${PORT_OPTIONS:MOPT1}
BROKEN= Option OPT1 conflicts with OPT2 (select only one)
.endifThe only difference is that the first one will write an
error after running make config,
suggesting changing the selected options.
OPT_PREVENTSThis port has X509 and
SCTP options. Both options add
patches, but the patches conflict with each other, so they
cannot be selected at the same time.
OPTIONS_DEFINE= X509 SCTP
SCTP_PATCHFILES= ${PORTNAME}-6.8p1-sctp-2573.patch.gz:-p1
SCTP_CONFIGURE_WITH= sctp
X509_PATCH_SITES= http://www.roumenpetrov.info/openssh/x509/:x509
X509_PATCHFILES= ${PORTNAME}-7.0p1+x509-8.5.diff.gz:-p1:x509
X509_PREVENTS= SCTP
X509_PREVENTS_MSG= X509 and SCTP patches conflictProvides a generic way to set and append to variables.
Before using
and
OPT_VARS,
see if there is already a more specific helper available in
節 5.12.3.12, “Generic Variables Replacement,
OPT_VARS_OFF
and
OPT_VARIABLE”.OPT_VARIABLE_OFF
When option OPT is selected,
and
defined,
OPT_VARS
and
key=value
pairs are evaluated from
key+=value. An
OPT_VARS= cause the existing value of
KEY to be overwritten, an
+= appends to the value.
works the same way, but when OPT_VARS_OFFOPT is
not selected.
OPTIONS_DEFINE= OPT1 OPT2 OPT3
OPT1_VARS= also_build+=bin1
OPT2_VARS= also_build+=bin2
OPT3_VARS= bin3_build=yes
OPT3_VARS_OFF= bin3_build=no
MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}"is equivalent to:
OPTIONS_DEFINE= OPT1 OPT2
MAKE_ARGS= ALSO_BUILD="${ALSO_BUILD}" BIN3_BUILD="${BIN3_BUILD}"
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
ALSO_BUILD+= bin1
.endif
.if ${PORT_OPTIONS:MOPT2}
ALSO_BUILD+= bin2
.endif
.if ${PORT_OPTIONS:MOPT2}
BIN3_BUILD= yes
.else
BIN3_BUILD= no
.endifValues containing whitespace must be enclosed in quotes:
OPT_VARS= foo="bar baz"This is due to the way make(1) variable expansion
deals with whitespace. When OPT_VARS= foo=bar
baz is expanded, the variable ends up
containing two strings, foo=bar and
baz. But the submitter probably
intended there to be only one string, foo=bar
baz. Quoting the value prevents whitespace
from being used as a delimiter.
For any of these dependency types:
PKG_DEPENDS
EXTRACT_DEPENDS
PATCH_DEPENDS
FETCH_DEPENDS
BUILD_DEPENDS
LIB_DEPENDS
RUN_DEPENDS
When option OPT is
selected, the value of
,
if defined, is appended to
OPT_DEPTYPE.
DEPTYPE
works the same, but when OPT_DEPTYPE_OFFOPT is
not
selected. For example:
OPTIONS_DEFINE= OPT1
OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a
OPT1_LIB_DEPENDS_OFF= libb.so:${PORTSDIR}/devel/bis equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a
.else
LIB_DEPENDS+= libb.so:${PORTSDIR}/devel/b
.endifFor any of these variables:
ALL_TARGET
BROKEN
CATEGORIES
CFLAGS
CONFIGURE_ENV
CONFLICTS
CONFLICTS_BUILD
CONFLICTS_INSTALL
CPPFLAGS
CXXFLAGS
DESKTOP_ENTRIES
DISTFILES
EXTRA_PATCHES
EXTRACT_ONLY
GH_ACCOUNT
GH_PROJECT
GH_TAGNAME
GH_TUPLE
IGNORE
INFO
INSTALL_TARGET
LDFLAGS
LIBS
MAKE_ARGS
MAKE_ENV
PATCHFILES
PATCH_SITES
PLIST_DIRS
PLIST_DIRSTRY
PLIST_FILES
PLIST_SUB
PORTDOCS
PORTEXAMPLES
SUB_FILES
SUB_LIST
TEST_TARGET
USES
When option OPT is
selected, the value of
,
if defined, is appended to
OPT_ABOVEVARIABLE.
ABOVEVARIABLE
works the same way, but when OPT_ABOVEVARIABLE_OFFOPT is
not
selected. For example:
OPTIONS_DEFINE= OPT1 OPT1_USES= gmake OPT1_CFLAGS_OFF= -DTEST
is equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
.if ${PORT_OPTIONS:MOPT1}
USES+= gmake
.else
CFLAGS+= -DTEST
.endifSome variables are not in this list, in particular
PKGNAMEPREFIX and
PKGNAMESUFFIX. This is intentional. A
port must not change its name when
its option set changes.
Some of these variables, at least
ALL_TARGET and
INSTALL_TARGET, have their default
values set after the options are
processed.
With these 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.
These Makefile targets can accept
optional extra build targets:
pre-fetch
do-fetch
post-fetch
pre-extract
do-extract
post-extract
pre-patch
do-patch
post-patch
pre-configure
do-configure
post-configure
pre-build
do-build
post-build
pre-install
do-install
post-install
post-stage
pre-package
do-package
post-package
When option OPT is
selected, the target
,
if defined, is executed after
TARGET-OPT-on.
TARGET
works the same way, but when TARGET-OPT-offOPT is
not selected. For example:
OPTIONS_DEFINE= OPT1
post-patch-OPT1-on:
@${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile
post-patch-OPT1-off:
@${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${LOCALBASE}/bin/|' ${WRKSRC}/Makefileis equivalent to:
OPTIONS_DEFINE= OPT1
.include <bsd.port.options.mk>
post-patch:
.if ${PORT_OPTIONS:MOPT1}
@${REINPLACE_CMD} -e '/opt1/d' ${WRKSRC}/Makefile
.else
@${REINPLACE_CMD} -e '/opt1/s|/usr/bin/|${LOCALBASE}/bin/|' ${WRKSRC}/Makefile
.endif本文及其他文件,可由此下載: ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/。
若有 FreeBSD 方面疑問,請先閱讀
FreeBSD 相關文件,如不能解決的話,再洽詢
<questions@FreeBSD.org>。
關於本文件的問題,請洽詢
<doc@FreeBSD.org>。