diff options
author | dillo <dillo> | 2005-06-07 20:09:35 +0000 |
---|---|---|
committer | dillo <dillo> | 2005-06-07 20:09:35 +0000 |
commit | fc8cf7c801113b4ef2044d49311f8970dc01a594 (patch) | |
tree | 6909648dd8b94f6970a09f34e2b91ae1c0a8d063 /doc/pkgsrc.html | |
parent | 06a199d324e61b566fc4e05ee0c05377804b37ee (diff) | |
download | pkgsrc-fc8cf7c801113b4ef2044d49311f8970dc01a594.tar.gz |
regen (options developer documentation update)
Diffstat (limited to 'doc/pkgsrc.html')
-rw-r--r-- | doc/pkgsrc.html | 192 |
1 files changed, 132 insertions, 60 deletions
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html index 65f591fdd3e..e2647e0e6dc 100644 --- a/doc/pkgsrc.html +++ b/doc/pkgsrc.html @@ -8620,30 +8620,49 @@ PKG_SHELL= ${PREFIX}/bin/zsh included by the main package <code class= "filename">Makefile</code>.</p> <pre class="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 +PKG_OPTIONS_VAR= PKG_OPTIONS.wibble +PKG_SUPPORTED_OPTIONS= wibble-foo ldap +PKG_OPTIONAL_GROUPS= database +PKG_GROUP.database= mysql pgsql +PKG_SUGGESTED_OPTIONS= wibble-foo +PKG_OPTIONS_LEGACY_VARS+= WIBBLE_USE_OPENLDAP:ldap +PKG_OPTIONS_LEGACY_OPTS+= foo:wibble-foo + +.include "../../mk/bsd.prefs.mk" + +# this package was previously named wibble2 +.if defined(PKG_OPTIONS.wibble2) +PKG_LEGACY_OPTIONS+= ${PKG_OPTIONS.wibble2} +PKG_OPTIONS_LEGACY_WARNINGS+="Deprecated variable PKG_OPTIONS.wibble2 used, use "${PKG_OPTIONS_VAR:Q}" instead." +.endif .include "../../mk/bsd.options.mk" # Package-specific option-handling ### +### FOO support +### +.if !empty(PKG_OPTIONS:Mwibble-foo) +CONFIGURE_ARGS+= --enable-foo +.endif + +### ### LDAP support ### .if !empty(PKG_OPTIONS:Mldap) . include "../../databases/openldap/buildlink3.mk" -CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap} +CONFIGURE_ARGS+= --enable-ldap=${BUILDLINK_PREFIX.openldap} .endif ### -### SASL authentication +### database support ### -.if !empty(PKG_OPTIONS:Msasl) -. include "../../security/cyrus-sasl2/buildlink3.mk" -CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} +.if !empty(PKG_OPTIONS:Mmysql) +. include "../../mk/mysql.buildlink3.mk" +.endif +.if !empty(PKG_OPTIONS:Mpgsql) +. include "../../mk/pgsql.buildlink3.mk" .endif </pre> @@ -8659,19 +8678,39 @@ CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} "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 contains the options the user wishes to - select. The recommended value is - “<span class="quote">PKG_OPTIONS.<em class= - "replaceable"><code>pkg</code></em></span>” - but any package-specific value may be used. This - variable should be set in a package Makefile.</p> + that the user can set to override the default + options. It should be set to “<span class= + "quote">PKG_OPTIONS.<em class= + "replaceable"><code>pkgname</code></em></span>”.</p> </li> <li> <p><code class= "varname">PKG_SUPPORTED_OPTIONS</code> is a list of - build options supported by the package. This - variable should be set in a package Makefile.</p> + build options supported by the package.</p> + </li> + + <li> + <p><code class= + "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a + list of names of groups of mutually exclusive + options. The options in each group are listed in + <code class="varname">PKG_OPTIONS_GROUP.<em class= + "replaceable"><code>groupname</code></em></code>. + The most specific setting of any option from the + group takes precedence over all other options in + the group. Options from the groups will be + automatically added to <code class= + "varname">PKG_SUPPORTED_OPTIONS</code>.</p> + </li> + + <li> + <p><code class= + "varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is + like <code class= + "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but + building the packages will fail if no option from + the group is selected.</p> </li> <li> @@ -8681,61 +8720,94 @@ CONFIGURE_ARGS+= --enable-sasl=${BUILDLINK_PREFIX.sasl} </li> <li> - <p><code class="varname">${PKG_OPTIONS_VAR}</code> - (the variable named in <code class= - "varname">PKG_OPTIONS_VAR</code>) lists the - selected build options and overrides any default - options given in <code class= - "varname">PKG_DEFAULT_OPTIONS</code>. If any of the - options begin with a “<span class= - "quote">-</span>”, then that option is always - removed from the selected build options, e.g.</p> - <pre class="programlisting"> -PKG_DEFAULT_OPTIONS= kerberos ldap sasl -PKG_OPTIONS_VAR= WIBBLE_OPTIONS -WIBBLE_OPTIONS= ${PKG_DEFAULT_OPTIONS} -sasl -# leads to PKG_OPTIONS = kerberos ldap -</pre> + <p><code class= + "varname">PKG_OPTIONS_LEGACY_VARS</code> is a list + of “<span class="quote"><em class= + "replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"> + <code>option</code></em></span>” pairs that + map legacy <code class= + "filename">/etc/mk.conf</code> variables to their + option counterparts. Pairs should be added with + “<span class="quote">+=</span>” to keep + the listing of global legacy variables. A warning + will be issued if the user uses a legacy + variable.</p> + </li> - <p>or</p> - <pre class="programlisting"> -PKG_OPTIONS_VAR= WIBBLE_OPTIONS -WIBBLE_OPTIONS= kerberos -ldap ldap -# leads to PKG_OPTIONS = kerberos -</pre> + <li> + <p><code class= + "varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list + of “<span class="quote"><em class= + "replaceable"><code>old-option</code></em>:<em class="replaceable"> + <code>new-option</code></em></span>” pairs + that map options that have been renamed to their + new counterparts. Pairs should be added with + “<span class="quote">+=</span>” to keep + the listing of global legacy options. A warning + will be issued if the user uses a legacy + option.</p> + </li> - <p>This variable should be set in <code class= - "filename">/etc/mk.conf</code>.</p> + <li> + <p><code class="varname">PKG_LEGACY_OPTIONS</code> + is a list of options implied by deprecated + variables used. This can be used for cases that + neither <code class= + "varname">PKG_OPTIONS_LEGACY_VARS</code> nor + <code class= + "varname">PKG_OPTIONS_LEGACY_OPTS</code> can + handle, e. g. when <code class= + "varname">PKG_OPTIONS_VAR</code> is renamed.</p> </li> <li> - <p>The <code class= - "varname">PKG_OPTIONS_LEGACY_VARS</code> is only - needed if you are converting a package that had its - own ad-hoc options handling to use <code class= - "filename">bsd.options.mk</code>. It converts - global or legacy options variables into an - equivalent <code class= - "varname">PKG_OPTIONS.<em class= - "replaceable"><code>pkg</code></em></code> - value.</p> + <p><code class= + "varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is + a list of warnings about deprecated variables or + options used, and what to use instead.</p> </li> </ol> </div> - <p>After the inclusion of bsd.options.mk, the variable + <p>A package should never modify <code class= + "varname">PKG_DEFAULT_OPTIONS</code> or the variable + named in <code class="varname">PKG_OPTIONS_VAR</code>. + These are strictly user-settable. To suggest a default + set of options, use <code class= + "varname">PKG_SUGGESTED_OPTIONS</code>.</p> + + <p><code class="varname">PKG_OPTIONS_VAR</code> and at + least one of <code class= + "varname">PKG_SUPPORTED_OPTIONS</code>, <code class= + "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and + <code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code> + must be defined before including <code class= + "filename">bsd.options.mk</code>.</p> + + <p>After the inclusion of <code class= + "filename">bsd.options.mk</code>, the variable <code class="varname">PKG_OPTIONS</code> contains the - list of the selected build options, properly filtered to + list of selected build options, properly filtered to remove unsupported and duplicate options.</p> <p>The remaining sections contain the logic that is - specific to each option. There should be a check for - every option listed in <code class= - "varname">PKG_SUPPORTED_OPTIONS</code>, 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 <code class="varname">PKG_OPTIONS</code>.</p> + specific to each option. The correct way to check for an + option is to check whether it is listed in <code class= + "varname">PKG_OPTIONS</code>:</p> + <pre class="programlisting"> +.if !empty(PKG_OPTIONS:M<em class= +"replaceable"><code>option</code></em>) +</pre> + + <p>If another package already has an option with the same + meaning, use the same name. For options applicable to + multiple packages (like enabling support for a library), + use short option names (like the name of the library). + For options specific to this package, prefix the name + with <code class="varname"><em class= + "replaceable"><code>pkgname</code></em>-</code>. Document + the option and its meaning in <code class= + "filename">mk/defaults/options.description</code>.</p> </div> </div> |