1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
<!-- $NetBSD: options.xml,v 1.12 2005/09/02 19:12:37 rillig Exp $ -->
<!-- based on: pkgsrc/mk/bsd.options.mk 1.42 -->
<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>
<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 <filename>/etc/mk.conf</filename>.</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: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
</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
<quote>PKG_OPTIONS.<replaceable>pkgbase</replaceable></quote>.</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 <filename>/etc/mk.conf</filename> 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>
<para>If another package already has an option with the same meaning,
use the same name. For options applicable to multiple packages (like
enabling support for a library), use short option names (like the name
of the library). For options specific to this package, prefix the
name with <varname><replaceable>pkgname</replaceable>-</varname>.
Document the option and its meaning in
<filename>mk/defaults/options.description</filename>.</para>
</sect1>
</chapter>
|
