Annotation of htdocs/docs/pkgsrc/options.html, revision 1.7
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">
1.4 rillig 5: <title>Chapter 16. 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">
1.7 ! rillig 8: <link rel="home" href="index.html" title="The pkgsrc guide">
1.1 dsieger 9: <link rel="up" href="developers-guide.html" title="Part II. The pkgsrc developer's guide">
1.4 rillig 10: <link rel="prev" href="pkginstall.html" title="Chapter 15. The pkginstall framework">
11: <link rel="next" href="build.html" title="Chapter 17. The build process">
1.1 dsieger 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">
1.4 rillig 16: <tr><th colspan="3" align="center">Chapter 16. Options handling</th></tr>
1.1 dsieger 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">
1.4 rillig 29: <a name="options"></a>Chapter 16. Options handling</h2></div></div></div>
1.1 dsieger 30: <div class="toc">
31: <p><b>Table of Contents</b></p>
32: <dl>
1.4 rillig 33: <dt><span class="sect1"><a href="options.html#global-default-options">16.1. Global default options</a></span></dt>
1.7 ! rillig 34: <dt><span class="sect1"><a href="options.html#converting-to-options">16.2. Converting packages to use bsd.options.mk</a></span></dt>
1.4 rillig 35: <dt><span class="sect1"><a href="options.html#option-names">16.3. Option Names</a></span></dt>
1.5 rillig 36: <dt><span class="sect1"><a href="options.html#option-build">16.4. Determining the options of dependencies</a></span></dt>
1.1 dsieger 37: </dl>
38: </div>
39: <p>Many packages have the ability to be built to support different
40: sets of features. <code class="filename">bsd.options.mk</code> is a framework
41: in pkgsrc that provides generic handling of those options that
42: determine different ways in which the packages can be built. It's
43: possible for the user to specify exactly which sets of options will be
44: built into a package or to allow a set of global default options
45: apply.</p>
1.5 rillig 46: <p>There are two broad classes of behaviors that one might want to
47: control via options. One is whether some particular feature is
48: enabled in a program that will be built anyway, often by including or
49: not including a dependency on some other package. The other is
50: whether or not an additional program will be built as part of the
51: package. Generally, it is better to make a split package for such
52: additional programs instead of using options, because it enables
53: binary packages to be built which can then be added separately. For
54: example, the foo package might have minimal dependencies (those
55: packages without which foo doesn't make sense), and then the foo-gfoo
56: package might include the GTK frontend program gfoo. This is better
57: than including a gtk option to foo that adds gfoo, because either that
58: option is default, in which case binary users can't get foo without
59: gfoo, or not default, in which case they can't get gfoo. With split
60: packages, they can install foo without having GTK, and later decide to
61: install gfoo (pulling in GTK at that time). This is an advantage to
62: source users too, avoiding the need for rebuilds.</p>
63: <p>Plugins with widely varying dependencies should usually be split
64: instead of options.</p>
65: <p>It is often more work to maintain split packages, especially if
66: the upstream package does not support this. The decision of split
67: vs. option should be made based on the likelihood that users will want
68: or object to the various pieces, the size of the dependencies that are
69: included, and the amount of work.</p>
70: <p>A further consideration is licensing. Non-free parts, or parts
71: that depend on non-free dependencies (especially plugins) should
72: almost always be split if feasible.</p>
1.1 dsieger 73: <div class="sect1" lang="en">
74: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4 rillig 75: <a name="global-default-options"></a>16.1. Global default options</h2></div></div></div>
1.1 dsieger 76: <p>Global default options are listed in
77: <code class="varname">PKG_DEFAULT_OPTIONS</code>, which is a list of the options
78: that should be built into every package if that option is supported.
1.6 hubertf 79: This variable should be set in <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a>.</p>
1.1 dsieger 80: </div>
81: <div class="sect1" lang="en">
82: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4 rillig 83: <a name="converting-to-options"></a>16.2. Converting packages to use <code class="filename">bsd.options.mk</code>
1.1 dsieger 84: </h2></div></div></div>
85: <p>The following example shows how
86: <code class="filename">bsd.options.mk</code> should be used
87: by the hypothetical ``wibble'' package, either in the package
88: <code class="filename">Makefile</code>, or in a file,
89: e.g. <code class="filename">options.mk</code>, that is included by the
90: main package <code class="filename">Makefile</code>.</p>
91: <pre class="programlisting">
92: PKG_OPTIONS_VAR= PKG_OPTIONS.wibble
93: PKG_SUPPORTED_OPTIONS= wibble-foo ldap
94: PKG_OPTIONS_OPTIONAL_GROUPS= database
95: PKG_OPTIONS_GROUP.database= mysql pgsql
96: PKG_SUGGESTED_OPTIONS= wibble-foo
97: PKG_OPTIONS_LEGACY_VARS+= WIBBLE_USE_OPENLDAP:ldap
98: PKG_OPTIONS_LEGACY_OPTS+= foo:wibble-foo
99:
100: .include "../../mk/bsd.prefs.mk"
101:
102: # this package was previously named wibble2
103: .if defined(PKG_OPTIONS.wibble2)
104: PKG_LEGACY_OPTIONS+= ${PKG_OPTIONS.wibble2}
105: PKG_OPTIONS_DEPRECATED_WARNINGS+= \
106: "Deprecated variable PKG_OPTIONS.wibble2 used, use ${PKG_OPTIONS_VAR} instead."
107: .endif
108:
109: .include "../../mk/bsd.options.mk"
110:
111: # Package-specific option-handling
112:
113: ###
114: ### FOO support
115: ###
116: .if !empty(PKG_OPTIONS:Mwibble-foo)
117: CONFIGURE_ARGS+= --enable-foo
118: .endif
119:
120: ###
121: ### LDAP support
122: ###
123: .if !empty(PKG_OPTIONS:Mldap)
124: . include "../../databases/openldap-client/buildlink3.mk"
125: CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap-client}
126: .endif
127:
128: ###
129: ### database support
130: ###
131: .if !empty(PKG_OPTIONS:Mmysql)
132: . include "../../mk/mysql.buildlink3.mk"
133: .endif
134: .if !empty(PKG_OPTIONS:Mpgsql)
135: . include "../../mk/pgsql.buildlink3.mk"
136: .endif
137: </pre>
138: <p>The first section contains the information about which build
139: options are supported by the package, and any default options settings
140: if needed.</p>
141: <div class="orderedlist"><ol type="1">
142: <li><p><code class="varname">PKG_OPTIONS_VAR</code> is the name of the
1.6 hubertf 143: <a class="citerefentry" 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
1.1 dsieger 144: options. It should be set to
145: PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em>. Do not set it to
146: PKG_OPTIONS.${PKGBASE}, since <code class="varname">PKGBASE</code> is not defined
147: at the point where the options are processed.</p></li>
148: <li><p><code class="varname">PKG_SUPPORTED_OPTIONS</code> is a list of
149: build options supported by the package.</p></li>
150: <li><p><code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a
151: list of names of groups of mutually exclusive options. The options in
152: each group are listed in
153: <code class="varname">PKG_OPTIONS_GROUP.<em class="replaceable"><code>groupname</code></em></code>.
154: The most specific setting of any option from the group takes
155: precedence over all other options in the group. Options from the
156: groups will be automatically added to
157: <code class="varname">PKG_SUPPORTED_OPTIONS</code>.</p></li>
158: <li><p><code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is like
159: <code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but building the
160: packages will fail if no option from the group is
161: selected.</p></li>
162: <li><p><code class="varname">PKG_OPTIONS_NONEMPTY_SETS</code> is a list
163: of names of sets of options. At least one option from each set must
164: be selected. The options in each set are listed in
165: <code class="varname">PKG_OPTIONS_SET.<em class="replaceable"><code>setname</code></em></code>.
166: Options from the sets will be automatically added to
167: <code class="varname">PKG_SUPPORTED_OPTIONS</code>. Building the package will
168: fail if no option from the set is selected.</p></li>
169: <li><p><code class="varname">PKG_SUGGESTED_OPTIONS</code> is a list of
170: build options which are enabled by default.</p></li>
171: <li><p><code class="varname">PKG_OPTIONS_LEGACY_VARS</code> is a list
172: of
173: “<span class="quote"><em class="replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>”
1.6 hubertf 174: pairs that map legacy <a class="link" href="configuring.html#mk.conf"><code class="filename">mk.conf</code></a> variables to
1.1 dsieger 175: their option counterparts. Pairs should be added with
176: “<span class="quote">+=</span>” to keep the listing of global legacy variables. A
177: warning will be issued if the user uses a legacy
178: variable.</p></li>
179: <li><p><code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list
180: of
181: “<span class="quote"><em class="replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>”
182: pairs that map options that have been renamed to their new
183: counterparts. Pairs should be added with “<span class="quote">+=</span>” to keep
184: the listing of global legacy options. A warning will be issued if
185: the user uses a legacy option.</p></li>
186: <li><p><code class="varname">PKG_LEGACY_OPTIONS</code> is a list of
187: options implied by deprecated variables used. This can be used for
188: cases that neither <code class="varname">PKG_OPTIONS_LEGACY_VARS</code> nor
189: <code class="varname">PKG_OPTIONS_LEGACY_OPTS</code> can handle, e. g. when
190: <code class="varname">PKG_OPTIONS_VAR</code> is renamed.</p></li>
191: <li><p><code class="varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is
192: a list of warnings about deprecated variables or options used, and
193: what to use instead.</p></li>
194: </ol></div>
195: <p>A package should never modify
196: <code class="varname">PKG_DEFAULT_OPTIONS</code> or the variable named in
197: <code class="varname">PKG_OPTIONS_VAR</code>. These are strictly user-settable.
198: To suggest a default set of options, use
199: <code class="varname">PKG_SUGGESTED_OPTIONS</code>.</p>
200: <p><code class="varname">PKG_OPTIONS_VAR</code> must be defined before
201: including <code class="filename">bsd.options.mk</code>. If none of
202: <code class="varname">PKG_SUPPORTED_OPTIONS</code>,
203: <code class="varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and
204: <code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> are defined (as can
205: happen with platform-specific options if none of them is supported on
206: the current platform), <code class="varname">PKG_OPTIONS</code> is set to the
207: empty list and the package is otherwise treated as not using the
208: options framework.</p>
209: <p>After the inclusion of <code class="filename">bsd.options.mk</code>, the
210: variable <code class="varname">PKG_OPTIONS</code> contains the list of selected
211: build options, properly filtered to remove unsupported and duplicate
212: options.</p>
213: <p>The remaining sections contain the logic that is specific to
214: each option. The correct way to check for an option is to check
215: whether it is listed in <code class="varname">PKG_OPTIONS</code>:</p>
216: <pre class="programlisting">
217: .if !empty(PKG_OPTIONS:M<em class="replaceable"><code>option</code></em>)
218: </pre>
219: </div>
220: <div class="sect1" lang="en">
221: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
1.4 rillig 222: <a name="option-names"></a>16.3. Option Names</h2></div></div></div>
1.1 dsieger 223: <p>Options that enable similar features in different packages (like
224: optional support for a library) should use a common name in all
225: packages that support it (like the name of the library). If another
226: package already has an option with the same meaning, use the same
227: name.</p>
228: <p>Options that enable features specific to one package, where it's
229: unlikely that another (unrelated) package has the same (or a similar)
230: optional feature, should use a name prefixed with
231: <code class="varname"><em class="replaceable"><code>pkgname</code></em>-</code>.</p>
232: <p>If a group of related packages share an optional feature
233: specific to that group, prefix it with the name of the
234: “<span class="quote">main</span>” package
235: (e. g. <code class="varname">djbware-errno-hack</code>).</p>
236: <p>For new options, add a line to
237: <code class="filename">mk/defaults/options.description</code>. Lines have two
238: fields, separated by tab. The first field is the option name, the
239: second its description. The description should be a whole sentence
240: (starting with an uppercase letter and ending with a period) that
241: describes what enabling the option does. E. g. “<span class="quote">Enable ispell
242: support.</span>” The file is sorted by option names.</p>
243: </div>
1.5 rillig 244: <div class="sect1" lang="en">
245: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
246: <a name="option-build"></a>16.4. Determining the options of dependencies</h2></div></div></div>
1.6 hubertf 247: <p>When writing <a class="link" href="buildlink.html#buildlink3.mk"><code class="filename">buildlink3.mk</code></a> files, it is often necessary to list
1.5 rillig 248: different dependencies based on the options with which the package was
249: built. For querying these options, the file
250: <code class="filename">pkgsrc/mk/pkg-build-options.mk</code> should be used. A
251: typical example looks like this:</p>
252: <pre class="programlisting">
253: pkgbase := libpurple
254: .include "../../mk/pkg-build-options.mk"
255:
256: .if !empty(PKG_BUILD_OPTIONS.libpurple:Mdbus)
257: ...
258: .endif
259: </pre>
260: <p>Including <code class="filename">pkg-build-options.mk</code> here will set
261: the variable <code class="varname">PKG_BUILD_OPTIONS.libpurple</code> to the build
262: options of the libpurple package, which can then be queried like
263: <code class="varname">PKG_OPTIONS</code> in the <code class="filename">options.mk</code>
264: file. See the file <code class="filename">pkg-build-options.mk</code> for more
265: details.</p>
266: </div>
1.1 dsieger 267: </div>
268: <div class="navfooter">
269: <hr>
270: <table width="100%" summary="Navigation footer">
271: <tr>
272: <td width="40%" align="left">
273: <a accesskey="p" href="pkginstall.html">Prev</a> </td>
274: <td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td>
275: <td width="40%" align="right"> <a accesskey="n" href="build.html">Next</a>
276: </td>
277: </tr>
278: <tr>
1.4 rillig 279: <td width="40%" align="left" valign="top">Chapter 15. The pkginstall framework </td>
1.1 dsieger 280: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
1.4 rillig 281: <td width="40%" align="right" valign="top"> Chapter 17. The build process</td>
1.1 dsieger 282: </tr>
283: </table>
284: </div>
285: </body>
286: </html>
CVSweb <webmaster@jp.NetBSD.org>