273 lines
11 KiB
XML
273 lines
11 KiB
XML
<!-- $NetBSD: options.xml,v 1.25 2007/10/01 22:38:42 rillig Exp $ -->
|
|
|
|
<!-- based on: pkgsrc/mk/bsd.options.mk 1.56 -->
|
|
|
|
<chapter id="options">
|
|
<title>Options handling</title>
|
|
|
|
<para>Many packages have the ability to be built to support different
|
|
sets of features. <filename>bsd.options.mk</filename> 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.</para>
|
|
|
|
<para>There are two broad classes of behaviors that one might want to
|
|
control via options. One is whether some particular feature is
|
|
enabled in a program that will be built anyway, often by including or
|
|
not including a dependency on some other package. The other is
|
|
whether or not an additional program will be built as part of the
|
|
package. Generally, it is better to make a split package for such
|
|
additional programs instead of using options, because it enables
|
|
binary packages to be built which can then be added separately. For
|
|
example, the foo package might have minimal dependencies (those
|
|
packages without which foo doesn't make sense), and then the foo-gfoo
|
|
package might include the GTK frontend program gfoo. This is better
|
|
than including a gtk option to foo that adds gfoo, because either that
|
|
option is default, in which case binary users can't get foo without
|
|
gfoo, or not default, in which case they can't get gfoo. With split
|
|
packages, they can install foo without having GTK, and later decide to
|
|
install gfoo (pulling in GTK at that time). This is an advantage to
|
|
source users too, avoiding the need for rebuilds.</para>
|
|
|
|
<para>Plugins with widely varying dependencies should usually be split
|
|
instead of options.</para>
|
|
|
|
<para>It is often more work to maintain split packages, especially if
|
|
the upstream package does not support this. The decision of split
|
|
vs. option should be made based on the likelihood that users will want
|
|
or object to the various pieces, the size of the dependencies that are
|
|
included, and the amount of work.</para>
|
|
|
|
<para>A further consideration is licensing. Non-free parts, or parts
|
|
that depend on non-free dependencies (especially plugins) should
|
|
almost always be split if feasible.</para>
|
|
|
|
<sect1 id="global-default-options">
|
|
<title>Global default options</title>
|
|
|
|
<para>Global default options are listed in
|
|
<varname>PKG_DEFAULT_OPTIONS</varname>, 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 &mk.conf;.</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="converting-to-options">
|
|
<title>Converting packages to use <filename>bsd.options.mk</filename></title>
|
|
|
|
<para>The following example shows how
|
|
<filename>bsd.options.mk</filename> should be used
|
|
by the hypothetical ``wibble'' package, either in the package
|
|
<filename>Makefile</filename>, or in a file,
|
|
e.g. <filename>options.mk</filename>, that is included by the
|
|
main package <filename>Makefile</filename>.</para>
|
|
|
|
<programlisting>
|
|
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} 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-client/buildlink3.mk"
|
|
CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap-client}
|
|
.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
|
|
</programlisting>
|
|
|
|
<para>The first section contains the information about which build
|
|
options are supported by the package, and any default options settings
|
|
if needed.</para>
|
|
|
|
<orderedlist>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS_VAR</varname> is the name of the
|
|
&man.make.1; variable that the user can set to override the default
|
|
options. It should be set to
|
|
PKG_OPTIONS.<replaceable>pkgbase</replaceable>. Do not set it to
|
|
PKG_OPTIONS.${PKGBASE}, since <varname>PKGBASE</varname> is not defined
|
|
at the point where the options are processed.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_SUPPORTED_OPTIONS</varname> is a list of
|
|
build options supported by the package.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS_OPTIONAL_GROUPS</varname> is a
|
|
list of names of groups of mutually exclusive options. The options in
|
|
each group are listed in
|
|
<varname>PKG_OPTIONS_GROUP.<replaceable>groupname</replaceable></varname>.
|
|
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
|
|
<varname>PKG_SUPPORTED_OPTIONS</varname>.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS_REQUIRED_GROUPS</varname> is like
|
|
<varname>PKG_OPTIONS_OPTIONAL_GROUPS</varname>, but building the
|
|
packages will fail if no option from the group is
|
|
selected.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS_NONEMPTY_SETS</varname> 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
|
|
<varname>PKG_OPTIONS_SET.<replaceable>setname</replaceable></varname>.
|
|
Options from the sets will be automatically added to
|
|
<varname>PKG_SUPPORTED_OPTIONS</varname>. Building the package will
|
|
fail if no option from the set is selected.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_SUGGESTED_OPTIONS</varname> is a list of
|
|
build options which are enabled by default.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS_LEGACY_VARS</varname> is a list
|
|
of
|
|
<quote><replaceable>USE_VARIABLE</replaceable>:<replaceable>option</replaceable></quote>
|
|
pairs that map legacy &mk.conf; variables to
|
|
their option counterparts. Pairs should be added with
|
|
<quote>+=</quote> to keep the listing of global legacy variables. A
|
|
warning will be issued if the user uses a legacy
|
|
variable.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS_LEGACY_OPTS</varname> is a list
|
|
of
|
|
<quote><replaceable>old-option</replaceable>:<replaceable>new-option</replaceable></quote>
|
|
pairs that map options that have been renamed to their new
|
|
counterparts. Pairs should be added with <quote>+=</quote> to keep
|
|
the listing of global legacy options. A warning will be issued if
|
|
the user uses a legacy option.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_LEGACY_OPTIONS</varname> is a list of
|
|
options implied by deprecated variables used. This can be used for
|
|
cases that neither <varname>PKG_OPTIONS_LEGACY_VARS</varname> nor
|
|
<varname>PKG_OPTIONS_LEGACY_OPTS</varname> can handle, e. g. when
|
|
<varname>PKG_OPTIONS_VAR</varname> is renamed.</para></listitem>
|
|
|
|
<listitem><para><varname>PKG_OPTIONS_DEPRECATED_WARNINGS</varname> is
|
|
a list of warnings about deprecated variables or options used, and
|
|
what to use instead.</para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
<para>A package should never modify
|
|
<varname>PKG_DEFAULT_OPTIONS</varname> or the variable named in
|
|
<varname>PKG_OPTIONS_VAR</varname>. These are strictly user-settable.
|
|
To suggest a default set of options, use
|
|
<varname>PKG_SUGGESTED_OPTIONS</varname>.</para>
|
|
|
|
<para><varname>PKG_OPTIONS_VAR</varname> must be defined before
|
|
including <filename>bsd.options.mk</filename>. If none of
|
|
<varname>PKG_SUPPORTED_OPTIONS</varname>,
|
|
<varname>PKG_OPTIONS_OPTIONAL_GROUPS</varname>, and
|
|
<varname>PKG_OPTIONS_REQUIRED_GROUPS</varname> are defined (as can
|
|
happen with platform-specific options if none of them is supported on
|
|
the current platform), <varname>PKG_OPTIONS</varname> is set to the
|
|
empty list and the package is otherwise treated as not using the
|
|
options framework.</para>
|
|
|
|
<para>After the inclusion of <filename>bsd.options.mk</filename>, the
|
|
variable <varname>PKG_OPTIONS</varname> contains the list of selected
|
|
build options, properly filtered to remove unsupported and duplicate
|
|
options.</para>
|
|
|
|
<para>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 <varname>PKG_OPTIONS</varname>:</para>
|
|
|
|
<programlisting>
|
|
.if !empty(PKG_OPTIONS:M<replaceable>option</replaceable>)
|
|
</programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="option-names">
|
|
<title>Option Names</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>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
|
|
<varname><replaceable>pkgname</replaceable>-</varname>.</para>
|
|
|
|
<para>If a group of related packages share an optional feature
|
|
specific to that group, prefix it with the name of the
|
|
<quote>main</quote> package
|
|
(e. g. <varname>djbware-errno-hack</varname>).</para>
|
|
|
|
<para>For new options, add a line to
|
|
<filename>mk/defaults/options.description</filename>. 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. <quote>Enable ispell
|
|
support.</quote> The file is sorted by option names.</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="option-build">
|
|
<title>Determining the options of dependencies</title>
|
|
|
|
<para>When writing &buildlink3.mk; files, it is often necessary to list
|
|
different dependencies based on the options with which the package was
|
|
built. For querying these options, the file
|
|
<filename>pkgsrc/mk/pkg-build-options.mk</filename> should be used. A
|
|
typical example looks like this:</para>
|
|
|
|
<programlisting>
|
|
pkgbase := libpurple
|
|
.include "../../mk/pkg-build-options.mk"
|
|
|
|
.if !empty(PKG_BUILD_OPTIONS.libpurple:Mdbus)
|
|
...
|
|
.endif
|
|
</programlisting>
|
|
|
|
<para>Including <filename>pkg-build-options.mk</filename> here will set
|
|
the variable <varname>PKG_BUILD_OPTIONS.libpurple</varname> to the build
|
|
options of the libpurple package, which can then be queried like
|
|
<varname>PKG_OPTIONS</varname> in the <filename>options.mk</filename>
|
|
file. See the file <filename>pkg-build-options.mk</filename> for more
|
|
details.</para>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|