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_*
VariablesPorters 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.
OPTIONS
OPTIONS
OPTIONS
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 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.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.