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
|
<!-- $NetBSD: options.xml,v 1.4 2005/05/20 10:02:03 rillig Exp $ -->
<!-- based on:
pkgsrc/mk/bsd.options.mk 1.23
-->
<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>
<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>
<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>
# Global and legacy options
PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
PKG_SUPPORTED_OPTIONS= ldap sasl
PKG_SUGGESTED_OPTIONS= sasl
PKG_OPTION_LEGACY_VARS= WIBBLE_USE_OPENLDAP:ldap USE_SASL2:sasl
.include "../../mk/bsd.options.mk"
# Package-specific option-handling
###
### LDAP support
###
.if !empty(PKG_OPTIONS:Mldap)
. include "../../databases/openldap/buildlink3.mk"
CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap}
.endif
###
### SASL authentication
###
.if !empty(PKG_OPTIONS:Msasl)
. include "../../security/cyrus-sasl2/buildlink3.mk"
CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl}
.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 contains the options the
user wishes to select. The recommended value is
<quote>PKG_OPTIONS.<replaceable>pkg</replaceable></quote>
but any package-specific value may be
used. This variable should be set in a package Makefile.
</para>
</listitem>
<listitem>
<para> <varname>PKG_SUPPORTED_OPTIONS</varname> is a list of
build options supported by the package. This variable
should be set in a package Makefile. </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_VAR}</varname> (the variable
named in <varname>PKG_OPTIONS_VAR</varname>)
lists the selected build options and overrides any
default options given in
<varname>PKG_DEFAULT_OPTIONS</varname>. If any of the
options begin with a <quote>-</quote>, then that option is
always removed from the selected build options, e.g.
</para>
<programlisting>
PKG_DEFAULT_OPTIONS= kerberos ldap sasl
PKG_OPTIONS_VAR= WIBBLE_OPTIONS
WIBBLE_OPTIONS= ${PKG_DEFAULT_OPTIONS} -sasl
# leads to PKG_OPTIONS = kerberos ldap
</programlisting>
<para>or</para>
<programlisting>
PKG_OPTIONS_VAR= WIBBLE_OPTIONS
WIBBLE_OPTIONS= kerberos -ldap ldap
# leads to PKG_OPTIONS = kerberos
</programlisting>
<para> This variable should be set in
<filename>/etc/mk.conf</filename>. </para>
</listitem>
<listitem><para>The <varname>PKG_OPTIONS_LEGACY_VARS</varname>
is only needed if you are converting a package that had its own
ad-hoc options handling to use
<filename>bsd.options.mk</filename>. It converts global or
legacy options variables into an equivalent
<varname>PKG_OPTIONS.<replaceable>pkg</replaceable></varname>
value.</para></listitem>
</orderedlist>
<para> After the inclusion of bsd.options.mk, the variable
<varname>PKG_OPTIONS</varname> contains the list of the 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. There should be a check for every option
listed in <varname>PKG_SUPPORTED_OPTIONS</varname>, and there
should be clear documentation on what turning on the option
will do in the comments preceding each section. The correct
way to check for an option is to check whether it is listed in
<varname>PKG_OPTIONS</varname>.
</para>
</sect1>
</chapter>
|
