Table of Contents
Many packages have the ability to be built to support
different sets of features. bsd.options.mk is a framework in pkgsrc that
provides generic handling of those options that determine
different ways in which the packages can be built. It's
possible for the user to specify exactly which sets of options
will be built into a package or to allow a set of global
default options apply.
Global default options are listed in PKG_DEFAULT_OPTIONS, which is a list of the
options that should be built into every package if that
option is supported. This variable should be set in
/etc/mk.conf.
The following example shows how bsd.options.mk should be used by the
hypothetical ``wibble'' package, either in the package
Makefile, or in a file, e.g. options.mk, that is included by the main
package Makefile.
PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
PKG_SUPPORTED_OPTIONS= wibble-foo ldap
PKG_OPTIONS_OPTIONAL_GROUPS= database
PKG_OPTIONS_GROUP.database= mysql pgsql
PKG_SUGGESTED_OPTIONS= wibble-foo
PKG_OPTIONS_LEGACY_VARS+= WIBBLE_USE_OPENLDAP:ldap
PKG_OPTIONS_LEGACY_OPTS+= foo:wibble-foo
.include "../../mk/bsd.prefs.mk"
# this package was previously named wibble2
.if defined(PKG_OPTIONS.wibble2)
PKG_LEGACY_OPTIONS+= ${PKG_OPTIONS.wibble2}
PKG_OPTIONS_DEPRECATED_WARNINGS+= \
"Deprecated variable PKG_OPTIONS.wibble2 used, use "${PKG_OPTIONS_VAR:Q}" instead."
.endif
.include "../../mk/bsd.options.mk"
# Package-specific option-handling
###
### FOO support
###
.if !empty(PKG_OPTIONS:Mwibble-foo)
CONFIGURE_ARGS+= --enable-foo
.endif
###
### LDAP support
###
.if !empty(PKG_OPTIONS:Mldap)
. include "../../databases/openldap/buildlink3.mk"
CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap}
.endif
###
### database support
###
.if !empty(PKG_OPTIONS:Mmysql)
. include "../../mk/mysql.buildlink3.mk"
.endif
.if !empty(PKG_OPTIONS:Mpgsql)
. include "../../mk/pgsql.buildlink3.mk"
.endif
The first section contains the information about which build options are supported by the package, and any default options settings if needed.
PKG_OPTIONS_VAR is the
name of the
make(1) variable that
the user can set to override the default options. It
should be set to PKG_OPTIONS.pkgbase. Do not set it
to PKG_OPTIONS.${PKGBASE}, since PKGBASE is set after PKG_OPTIONS_VAR is used.
PKG_SUPPORTED_OPTIONS
is a list of build options supported by the
package.
PKG_OPTIONS_OPTIONAL_GROUPS is a list
of names of groups of mutually exclusive options. The
options in each group are listed in PKG_OPTIONS_GROUP.. The
most specific setting of any option from the group
takes precedence over all other options in the group.
Options from the groups will be automatically added to
groupnamePKG_SUPPORTED_OPTIONS.
PKG_OPTIONS_REQUIRED_GROUPS is like
PKG_OPTIONS_OPTIONAL_GROUPS, but
building the packages will fail if no option from the
group is selected.
PKG_OPTIONS_NONEMPTY_SETS is a list of
names of sets of options. At least one option from each
set must be selected. The options in each set are
listed in PKG_OPTIONS_SET.. Options
from the sets will be automatically added to
setnamePKG_SUPPORTED_OPTIONS.
Building the package will fail if no option from the
set is selected.
PKG_SUGGESTED_OPTIONS
is a list of build options which are enabled by
default.
PKG_OPTIONS_LEGACY_VARS
is a list of “USE_VARIABLE:option”
pairs that map legacy /etc/mk.conf variables to their
option counterparts. Pairs should be added with
“+=” to keep the
listing of global legacy variables. A warning will be
issued if the user uses a legacy variable.
PKG_OPTIONS_LEGACY_OPTS
is a list of “old-option:new-option”
pairs that map options that have been renamed to their
new counterparts. Pairs should be added with
“+=” to keep the
listing of global legacy options. A warning will be
issued if the user uses a legacy option.
PKG_LEGACY_OPTIONS is a
list of options implied by deprecated variables used.
This can be used for cases that neither PKG_OPTIONS_LEGACY_VARS nor
PKG_OPTIONS_LEGACY_OPTS
can handle, e. g. when PKG_OPTIONS_VAR is renamed.
PKG_OPTIONS_DEPRECATED_WARNINGS is a
list of warnings about deprecated variables or options
used, and what to use instead.
A package should never modify PKG_DEFAULT_OPTIONS or the variable named in
PKG_OPTIONS_VAR. These are
strictly user-settable. To suggest a default set of options,
use PKG_SUGGESTED_OPTIONS.
PKG_OPTIONS_VAR must be
defined before including bsd.options.mk. If none of PKG_SUPPORTED_OPTIONS, PKG_OPTIONS_OPTIONAL_GROUPS, and
PKG_OPTIONS_REQUIRED_GROUPS are
defined (as can happen with platform-specific options if none
of them is supported on the current platform), PKG_OPTIONS is set to the empty list and the
package is otherwise treated as not using the options
framework.
After the inclusion of bsd.options.mk, the variable PKG_OPTIONS contains the list of selected
build options, properly filtered to remove unsupported and
duplicate options.
The remaining sections contain the logic that is specific
to each option. The correct way to check for an option is to
check whether it is listed in PKG_OPTIONS:
.if !empty(PKG_OPTIONS:Moption)
Options that enable similar features in different packages (like optional support for a library) should use a common name in all packages that support it (like the name of the library). If another package already has an option with the same meaning, use the same name.
Options that enable features specific to one package,
where it's unlikely that another (unrelated) package has the
same (or a similar) optional feature, should use a name
prefixed with pkgname-
If a group of related packages share an optional feature
specific to that group, prefix it with the name of the
“main” package (e. g.
djbware-errno-hack).
For new options, add a line to mk/defaults/options.description. Lines have
two fields, separated by tab. The first field is the option
name, the second its description. The description should be a
whole sentence (starting with an uppercase letter and ending
with a period) that describes what enabling the option does.
E. g. “Enable ispell
support.” The file is sorted by option
names.