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: &#8220;<span class="quote"><em class="replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>&#8221;
                    146: pairs that map legacy <code class="filename">/etc/mk.conf</code> variables to
                    147: their option counterparts.  Pairs should be added with
                    148: &#8220;<span class="quote">+=</span>&#8221; 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: &#8220;<span class="quote"><em class="replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>&#8221;
                    154: pairs that map options that have been renamed to their new
                    155: counterparts.  Pairs should be added with &#8220;<span class="quote">+=</span>&#8221; 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: &#8220;<span class="quote">main</span>&#8221; 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. &#8220;<span class="quote">Enable ispell
                    214: support.</span>&#8221; 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>