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: &#8220;<span class="quote"><em class="replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>&#8221;
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: &#8220;<span class="quote">+=</span>&#8221; 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: &#8220;<span class="quote"><em class="replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>&#8221;
                    182: pairs that map options that have been renamed to their new
                    183: counterparts.  Pairs should be added with &#8220;<span class="quote">+=</span>&#8221; 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: &#8220;<span class="quote">main</span>&#8221; 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. &#8220;<span class="quote">Enable ispell
                    242: support.</span>&#8221; 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>