Annotation of htdocs/docs/pkgsrc/options.html, revision 1.2
1.1 dsieger 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2: <html>
3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5: <title>Chapter 15. Options handling</title>
1.2 ! rillig 6: <link rel="stylesheet" href="/global.css" type="text/css">
1.1 dsieger 7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
8: <link rel="start" href="index.html" title="The pkgsrc guide">
9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
10: <link rel="prev" href="pkginstall.html" title="Chapter 14. The pkginstall framework">
11: <link rel="next" href="build.html" title="Chapter 16. The build process">
12: </head>
13: <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
14: <div class="navheader">
15: <table width="100%" summary="Navigation header">
16: <tr><th colspan="3" align="center">Chapter 15. Options handling</th></tr>
17: <tr>
18: <td width="20%" align="left">
19: <a accesskey="p" href="pkginstall.html">Prev</a> </td>
20: <th width="60%" align="center">Part II. The pkgsrc developer's guide</th>
21: <td width="20%" align="right"> <a accesskey="n" href="build.html">Next</a>
22: </td>
23: </tr>
24: </table>
25: <hr>
26: </div>
27: <div class="chapter" lang="en">
28: <div class="titlepage"><div><div><h2 class="title">
29: <a name="options"></a>Chapter 15. Options handling</h2></div></div></div>
30: <div class="toc">
31: <p><b>Table of Contents</b></p>
32: <dl>
33: <dt><span class="sect1"><a href="options.html#global-default-options">15.1. Global default options</a></span></dt>
34: <dt><span class="sect1"><a href="options.html#converting-to-options">15.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt>
35: <dt><span class="sect1"><a href="options.html#option-names">15.3. Option Names</a></span></dt>
36: </dl>
37: </div>
38: <p>Many packages have the ability to be built to support different
39: sets of features. <code class="filename">bsd.options.mk</code> is a framework
40: in pkgsrc that provides generic handling of those options that
41: determine different ways in which the packages can be built. It's
42: possible for the user to specify exactly which sets of options will be
43: built into a package or to allow a set of global default options
44: apply.</p>
45: <div class="sect1" lang="en">
46: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
47: <a name="global-default-options"></a>15.1. Global default options</h2></div></div></div>
48: <p>Global default options are listed in
49: <code class="varname">PKG_DEFAULT_OPTIONS</code>, which is a list of the options
50: that should be built into every package if that option is supported.
51: This variable should be set in <code class="filename">/etc/mk.conf</code>.</p>
52: </div>
53: <div class="sect1" lang="en">
54: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
55: <a name="converting-to-options"></a>15.2. Converting packages to use <code class="filename">bsd.options.mk</code>
56: </h2></div></div></div>
57: <p>The following example shows how
58: <code class="filename">bsd.options.mk</code> should be used
59: by the hypothetical ``wibble'' package, either in the package
60: <code class="filename">Makefile</code>, or in a file,
61: e.g. <code class="filename">options.mk</code>, that is included by the
62: main package <code class="filename">Makefile</code>.</p>
63: <pre class="programlisting">
64: PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
65: PKG_SUPPORTED_OPTIONS= wibble-foo ldap
66: PKG_OPTIONS_OPTIONAL_GROUPS= database
67: PKG_OPTIONS_GROUP.database= mysql pgsql
68: PKG_SUGGESTED_OPTIONS= wibble-foo
69: PKG_OPTIONS_LEGACY_VARS+= WIBBLE_USE_OPENLDAP:ldap
70: PKG_OPTIONS_LEGACY_OPTS+= foo:wibble-foo
71:
72: .include "../../mk/bsd.prefs.mk"
73:
74: # this package was previously named wibble2
75: .if defined(PKG_OPTIONS.wibble2)
76: PKG_LEGACY_OPTIONS+= ${PKG_OPTIONS.wibble2}
77: PKG_OPTIONS_DEPRECATED_WARNINGS+= \
78: "Deprecated variable PKG_OPTIONS.wibble2 used, use ${PKG_OPTIONS_VAR} instead."
79: .endif
80:
81: .include "../../mk/bsd.options.mk"
82:
83: # Package-specific option-handling
84:
85: ###
86: ### FOO support
87: ###
88: .if !empty(PKG_OPTIONS:Mwibble-foo)
89: CONFIGURE_ARGS+= --enable-foo
90: .endif
91:
92: ###
93: ### LDAP support
94: ###
95: .if !empty(PKG_OPTIONS:Mldap)
96: . include "../../databases/openldap-client/buildlink3.mk"
97: CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap-client}
98: .endif
99:
100: ###
101: ### database support
102: ###
103: .if !empty(PKG_OPTIONS:Mmysql)
104: . include "../../mk/mysql.buildlink3.mk"
105: .endif
106: .if !empty(PKG_OPTIONS:Mpgsql)
107: . include "../../mk/pgsql.buildlink3.mk"
108: .endif
109: </pre>
110: <p>The first section contains the information about which build
111: options are supported by the package, and any default options settings
112: if needed.</p>
113: <div class="orderedlist"><ol type="1">
114: <li><p><code class="varname">PKG_OPTIONS_VAR</code> is the name of the
115: <a href="http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> variable that the user can set to override the default
116: options. It should be set to
117: PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em>. Do not set it to
118: PKG_OPTIONS.${PKGBASE}, since <code class="varname">PKGBASE</code> is not defined
119: at the point where the options are processed.</p></li>
120: <li><p><code class="varname">PKG_SUPPORTED_OPTIONS</code> is a list of
121: build options supported by the package.</p></li>
122: <li><p><code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a
123: list of names of groups of mutually exclusive options. The options in
124: each group are listed in
125: <code class="varname">PKG_OPTIONS_GROUP.<em class="replaceable"><code>groupname</code></em></code>.
126: The most specific setting of any option from the group takes
127: precedence over all other options in the group. Options from the
128: groups will be automatically added to
129: <code class="varname">PKG_SUPPORTED_OPTIONS</code>.</p></li>
130: <li><p><code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is like
131: <code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but building the
132: packages will fail if no option from the group is
133: selected.</p></li>
134: <li><p><code class="varname">PKG_OPTIONS_NONEMPTY_SETS</code> is a list
135: of names of sets of options. At least one option from each set must
136: be selected. The options in each set are listed in
137: <code class="varname">PKG_OPTIONS_SET.<em class="replaceable"><code>setname</code></em></code>.
138: Options from the sets will be automatically added to
139: <code class="varname">PKG_SUPPORTED_OPTIONS</code>. Building the package will
140: fail if no option from the set is selected.</p></li>
141: <li><p><code class="varname">PKG_SUGGESTED_OPTIONS</code> is a list of
142: build options which are enabled by default.</p></li>
143: <li><p><code class="varname">PKG_OPTIONS_LEGACY_VARS</code> is a list
144: of
145: “<span class="quote"><em class="replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>”
146: pairs that map legacy <code class="filename">/etc/mk.conf</code> variables to
147: their option counterparts. Pairs should be added with
148: “<span class="quote">+=</span>” to keep the listing of global legacy variables. A
149: warning will be issued if the user uses a legacy
150: variable.</p></li>
151: <li><p><code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list
152: of
153: “<span class="quote"><em class="replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>”
154: pairs that map options that have been renamed to their new
155: counterparts. Pairs should be added with “<span class="quote">+=</span>” to keep
156: the listing of global legacy options. A warning will be issued if
157: the user uses a legacy option.</p></li>
158: <li><p><code class="varname">PKG_LEGACY_OPTIONS</code> is a list of
159: options implied by deprecated variables used. This can be used for
160: cases that neither <code class="varname">PKG_OPTIONS_LEGACY_VARS</code> nor
161: <code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> can handle, e. g. when
162: <code class="varname">PKG_OPTIONS_VAR</code> is renamed.</p></li>
163: <li><p><code class="varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is
164: a list of warnings about deprecated variables or options used, and
165: what to use instead.</p></li>
166: </ol></div>
167: <p>A package should never modify
168: <code class="varname">PKG_DEFAULT_OPTIONS</code> or the variable named in
169: <code class="varname">PKG_OPTIONS_VAR</code>. These are strictly user-settable.
170: To suggest a default set of options, use
171: <code class="varname">PKG_SUGGESTED_OPTIONS</code>.</p>
172: <p><code class="varname">PKG_OPTIONS_VAR</code> must be defined before
173: including <code class="filename">bsd.options.mk</code>. If none of
174: <code class="varname">PKG_SUPPORTED_OPTIONS</code>,
175: <code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and
176: <code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> are defined (as can
177: happen with platform-specific options if none of them is supported on
178: the current platform), <code class="varname">PKG_OPTIONS</code> is set to the
179: empty list and the package is otherwise treated as not using the
180: options framework.</p>
181: <p>After the inclusion of <code class="filename">bsd.options.mk</code>, the
182: variable <code class="varname">PKG_OPTIONS</code> contains the list of selected
183: build options, properly filtered to remove unsupported and duplicate
184: options.</p>
185: <p>The remaining sections contain the logic that is specific to
186: each option. The correct way to check for an option is to check
187: whether it is listed in <code class="varname">PKG_OPTIONS</code>:</p>
188: <pre class="programlisting">
189: .if !empty(PKG_OPTIONS:M<em class="replaceable"><code>option</code></em>)
190: </pre>
191: </div>
192: <div class="sect1" lang="en">
193: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
194: <a name="option-names"></a>15.3. Option Names</h2></div></div></div>
195: <p>Options that enable similar features in different packages (like
196: optional support for a library) should use a common name in all
197: packages that support it (like the name of the library). If another
198: package already has an option with the same meaning, use the same
199: name.</p>
200: <p>Options that enable features specific to one package, where it's
201: unlikely that another (unrelated) package has the same (or a similar)
202: optional feature, should use a name prefixed with
203: <code class="varname"><em class="replaceable"><code>pkgname</code></em>-</code>.</p>
204: <p>If a group of related packages share an optional feature
205: specific to that group, prefix it with the name of the
206: “<span class="quote">main</span>” package
207: (e. g. <code class="varname">djbware-errno-hack</code>).</p>
208: <p>For new options, add a line to
209: <code class="filename">mk/defaults/options.description</code>. Lines have two
210: fields, separated by tab. The first field is the option name, the
211: second its description. The description should be a whole sentence
212: (starting with an uppercase letter and ending with a period) that
213: describes what enabling the option does. E. g. “<span class="quote">Enable ispell
214: support.</span>” The file is sorted by option names.</p>
215: </div>
216: </div>
217: <div class="navfooter">
218: <hr>
219: <table width="100%" summary="Navigation footer">
220: <tr>
221: <td width="40%" align="left">
222: <a accesskey="p" href="pkginstall.html">Prev</a> </td>
223: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
224: <td width="40%" align="right"> <a accesskey="n" href="build.html">Next</a>
225: </td>
226: </tr>
227: <tr>
228: <td width="40%" align="left" valign="top">Chapter 14. The pkginstall framework </td>
229: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
230: <td width="40%" align="right" valign="top"> Chapter 16. The build process</td>
231: </tr>
232: </table>
233: </div>
234: </body>
235: </html>
CVSweb <webmaster@jp.NetBSD.org>