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.
These variables are designed to be set by the system
administrator. There are many that are standardized in
the 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.
You should not assume that a
WITH_
necessarily has a corresponding
*WITHOUT_
variable and vice versa. In general, the default is
simply assumed.*
Unless otherwise specified, these variables are only
tested for being set or not set, rather than being set
to a specific value such as YES
or NO.
WITH_* and
WITHOUT_*
Variables| Variable | Means |
|---|---|
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. |
Porters should use like-named knobs, both
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 installing the port a dialog showing the available
options, and then saves those options to
/var/db/ports/.
The next time the port is built, the options are
reused.${UNIQUENAME}/options
When the user runs make config (or
runs make build for the first time),
the framework checks for
/var/db/ports/.
If that file does not exist, the values of
${UNIQUENAME}/optionsOPTIONS_* 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:
Once defined, OPTIONS are
described (optional, but strongly recommended):
ports/Mk/bsd.options.desc.mk
has descriptions for many common
OPTIONS; there is usually no need
to override these.
When describing options, view it from the
perspective of the user: “What does it do?”
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.
OPTIONS can be grouped as radio
choices, where only one choice from each group is
allowed:
OPTIONS can be grouped as radio
choices, where none or only one choice from each group
is allowed:
OPTIONS can also be grouped as
“multiple-choice” lists, where
at least one option must be
enabled:
OPTIONS can also be grouped as
“multiple-choice” lists, where none or any
option can be enabled:
OPTIONS are unset by default,
unless they are listed in
OPTIONS_DEFAULT:
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.
OPTIONSOPTIONSOPTIONSThe 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 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.
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.
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.
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.
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, for example:
is equivalent to:
If X_CONFIGURE_ENABLE is set then
--enable-${X_CONFIGURE_ENABLE} or
--disable-${X_CONFIGURE_ENABLE} will be
added to CONFIGURE_ARGS depending on the
value of the optionX, for example:
is equivalent to:
If X_CONFIGURE_WITH is set then
--with-${X_CONFIGURE_WITH}
or --without-${X_CONFIGURE_WITH} will
be added to CONFIGURE_ARGS depending
on the status of the option X,
for example:
is equivalent to:
If X_CONFIGURE_ON is set then its
value will be appended to CONFIGURE_ARGS
depending on the status of the option X,
for example:
is equivalent to:
If X_CONFIGURE_OFF is set then its
value will be appended to CONFIGURE_ARGS
depending on the status of the option X,
for example:
is equivalent to:
If X_CMAKE_ON is set then its value
will be appended to CMAKE_ARGS depending
on the status of the option X, for
example:
is equivalent to:
If X_CMAKE_OFF is set then its value
will be appended to CMAKE_ARGS depending
on the status of the option X, for
example:
is equivalent to:
For any of the following variables:
ALL_TARGET
CATEGORIES
CFLAGS
CPPFLAGS
CXXFLAGS
CONFIGURE_ENV
DISTFILES
EXTRA_PATCHES
INSTALL_TARGET
LDFLAGS
MAKE_ARGS
MAKE_ENV
PATCH_SITES
PATCHFILES
PLIST_FILES
PLIST_DIRS
PLIST_DIRSTRY
USES
If X_ABOVEVARIABLE is defined then
its value will be appended to
ABOVEVARIABLE depending on the status of
the option X, for example:
is equivalent to:
For any of the following dependency type:
PKG_DEPENDS
EXTRACT_DEPENDS
PATCH_DEPENDS
FETCH_DEPENDS
BUILD_DEPENDS
LIB_DEPENDS
RUN_DEPENDS
If X_ABOVEVARIABLE is defined then
its value will be appended to
ABOVEVARIABLE depending on the status
of the option X, for example:
is equivalent to:
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>.