Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Examples include choice of natural (human) language, GUI versus command-line, or type of database to support. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to control which configuration should be built. Supporting these properly will make users happy, and effectively provide 2 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
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
some kind of variable such as YES
or
NO
.
WITH_*
and WITHOUT_*
variablesVariable | Means |
---|---|
WITHOUT_NLS | If set, says that internationalization is not needed, which can save compile time. By default, internationalization is used. |
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. |
WITHOUT_X11 | If the port can be built both with and without X support, then it should normally be built with X support. If this variable is defined, then the version that does not have X support should be built instead. |
It is recommended that porters use like-named knobs, 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
variable gives the user who
installs the port a dialog with the available options and saves
them to /var/db/ports/portname/options
.
Next time when the port has to be rebuild, the options are reused.
Never again you will have to remember all the twenty
WITH_
and
*
WITHOUT_
options you
used to build this port!*
When the user runs make config
(or runs
make build
for the first time), the framework will
check for
/var/db/ports/portname/options
.
If that file does not exist, it will use the values of
OPTIONS
to create a dialogbox where the options
can be enabled or disabled. Then the
options
file is saved and the selected
variables will be 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.
Use make showconfig
to see the saved
configuration. Use make rmconfig
to remove the
saved configuration.
The syntax for the OPTIONS
variable is:
OPTIONS= OPTION "descriptive text" default ...
The value for default is either ON
or
OFF
. Multiple repetitions of these three fields
are allowed.
OPTIONS
definition must appear before
the inclusion of bsd.port.pre.mk
.
The WITH_*
and WITHOUT_*
variables can only be tested after the inclusion of
bsd.port.pre.mk
.
OPTIONS
OPTIONS= FOO "Enable option foo" On \ BAR "Support feature bar" Off .include <bsd.port.pre.mk> .if defined(WITHOUT_FOO) CONFIGURE_ARGS+= --without-foo .else CONFIGURE_ARGS+= --with-foo .endif .if defined(WITH_BAR) RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar .endif .include <bsd.port.post.mk>
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 defined(WITH_FOO) LIB_DEPENDS+= foo.0:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .endif
In the example above, imagine a library libfoo is installed on
the system. 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 user decides to remove libfoo from the system, the ports system
does not protest (no dependency on libfoo was recorded) but the
application breaks.
.if defined(WITH_FOO) LIB_DEPENDS+= foo.0:${PORTSDIR}/devel/foo CONFIGURE_ARGS+= --enable-foo .else CONFIGURE_ARGS+= --disable-foo .endif
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.
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>.