diff options
| -rw-r--r-- | doc/pkgsrc.html | 99 | ||||
| -rw-r--r-- | doc/pkgsrc.txt | 70 |
2 files changed, 136 insertions, 33 deletions
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html index f3b54ed92f4..27a457e790e 100644 --- a/doc/pkgsrc.html +++ b/doc/pkgsrc.html @@ -276,6 +276,7 @@ builds)</a></span></dt> <dt><span class="sect1"><a href="#global-default-options">16.1. Global default options</a></span></dt> <dt><span class="sect1"><a href="#converting-to-options">16.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt> <dt><span class="sect1"><a href="#option-names">16.3. Option Names</a></span></dt> +<dt><span class="sect1"><a href="#option-build">16.4. Determining the options of dependencies</a></span></dt> </dl></dd> <dt><span class="chapter"><a href="#build">17. The build process</a></span></dt> <dd><dl> @@ -360,7 +361,7 @@ builds)</a></span></dt> <dt><span class="sect2"><a href="#perl-modules">19.6.6. Packages installing perl modules</a></span></dt> <dt><span class="sect2"><a href="#faq.info-files">19.6.7. Packages installing info files</a></span></dt> <dt><span class="sect2"><a href="#manpages">19.6.8. Packages installing man pages</a></span></dt> -<dt><span class="sect2"><a href="#gconf2-data-files">19.6.9. Packages installing GConf2 data files</a></span></dt> +<dt><span class="sect2"><a href="#gconf-data-files">19.6.9. Packages installing GConf data files</a></span></dt> <dt><span class="sect2"><a href="#scrollkeeper-data-files">19.6.10. Packages installing scrollkeeper data files</a></span></dt> <dt><span class="sect2"><a href="#x11-fonts">19.6.11. Packages installing X11 fonts</a></span></dt> <dt><span class="sect2"><a href="#gtk2-modules">19.6.12. Packages installing GTK2 modules</a></span></dt> @@ -3865,6 +3866,7 @@ anymore, you can remove that file and run <span><strong class="command">cvs -q u <dt><span class="sect1"><a href="#global-default-options">16.1. Global default options</a></span></dt> <dt><span class="sect1"><a href="#converting-to-options">16.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt> <dt><span class="sect1"><a href="#option-names">16.3. Option Names</a></span></dt> +<dt><span class="sect1"><a href="#option-build">16.4. Determining the options of dependencies</a></span></dt> </dl></dd> <dt><span class="chapter"><a href="#build">17. The build process</a></span></dt> <dd><dl> @@ -3949,7 +3951,7 @@ anymore, you can remove that file and run <span><strong class="command">cvs -q u <dt><span class="sect2"><a href="#perl-modules">19.6.6. Packages installing perl modules</a></span></dt> <dt><span class="sect2"><a href="#faq.info-files">19.6.7. Packages installing info files</a></span></dt> <dt><span class="sect2"><a href="#manpages">19.6.8. Packages installing man pages</a></span></dt> -<dt><span class="sect2"><a href="#gconf2-data-files">19.6.9. Packages installing GConf2 data files</a></span></dt> +<dt><span class="sect2"><a href="#gconf-data-files">19.6.9. Packages installing GConf data files</a></span></dt> <dt><span class="sect2"><a href="#scrollkeeper-data-files">19.6.10. Packages installing scrollkeeper data files</a></span></dt> <dt><span class="sect2"><a href="#x11-fonts">19.6.11. Packages installing X11 fonts</a></span></dt> <dt><span class="sect2"><a href="#gtk2-modules">19.6.12. Packages installing GTK2 modules</a></span></dt> @@ -5563,7 +5565,7 @@ BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0 <div class="sect1" lang="en"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="creating-buildlink3.mk"></a>14.2. Writing <code class="filename">buildlink3.mk</code> files</h2></div></div></div> -<p>A package's <code class="filename">buildlink3.mk</code> file is +<a name="buildlink3.mk"></a><p>A package's <code class="filename">buildlink3.mk</code> file is included by Makefiles to indicate the need to compile and link against header files and libraries provided by the package. A <code class="filename">buildlink3.mk</code> file should always provide @@ -6314,6 +6316,7 @@ environment variable to <code class="literal">NO</code>.</p> <dt><span class="sect1"><a href="#global-default-options">16.1. Global default options</a></span></dt> <dt><span class="sect1"><a href="#converting-to-options">16.2. Converting packages to use <code class="filename">bsd.options.mk</code></a></span></dt> <dt><span class="sect1"><a href="#option-names">16.3. Option Names</a></span></dt> +<dt><span class="sect1"><a href="#option-build">16.4. Determining the options of dependencies</a></span></dt> </dl> </div> <p>Many packages have the ability to be built to support different @@ -6323,6 +6326,33 @@ determine different ways in which the packages can be built. It's possible for the user to specify exactly which sets of options will be built into a package or to allow a set of global default options apply.</p> +<p>There are two broad classes of behaviors that one might want to +control via options. One is whether some particular feature is +enabled in a program that will be built anyway, often by including or +not including a dependency on some other package. The other is +whether or not an additional program will be built as part of the +package. Generally, it is better to make a split package for such +additional programs instead of using options, because it enables +binary packages to be built which can then be added separately. For +example, the foo package might have minimal dependencies (those +packages without which foo doesn't make sense), and then the foo-gfoo +package might include the GTK frontend program gfoo. This is better +than including a gtk option to foo that adds gfoo, because either that +option is default, in which case binary users can't get foo without +gfoo, or not default, in which case they can't get gfoo. With split +packages, they can install foo without having GTK, and later decide to +install gfoo (pulling in GTK at that time). This is an advantage to +source users too, avoiding the need for rebuilds.</p> +<p>Plugins with widely varying dependencies should usually be split +instead of options.</p> +<p>It is often more work to maintain split packages, especially if +the upstream package does not support this. The decision of split +vs. option should be made based on the likelihood that users will want +or object to the various pieces, the size of the dependencies that are +included, and the amount of work.</p> +<p>A further consideration is licensing. Non-free parts, or parts +that depend on non-free dependencies (especially plugins) should +almost always be split if feasible.</p> <div class="sect1" lang="en"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="global-default-options"></a>16.1. Global default options</h2></div></div></div> @@ -6494,6 +6524,29 @@ second its description. The description should be a whole sentence describes what enabling the option does. E. g. “<span class="quote">Enable ispell support.</span>” The file is sorted by option names.</p> </div> +<div class="sect1" lang="en"> +<div class="titlepage"><div><div><h2 class="title" style="clear: both"> +<a name="option-build"></a>16.4. Determining the options of dependencies</h2></div></div></div> +<p>When writing <a href="#buildlink3.mk"><code class="filename">buildlink3.mk</code></a> files, it is often necessary to list +different dependencies based on the options with which the package was +built. For querying these options, the file +<code class="filename">pkgsrc/mk/pkg-build-options.mk</code> should be used. A +typical example looks like this:</p> +<pre class="programlisting"> +pkgbase := libpurple +.include "../../mk/pkg-build-options.mk" + +.if !empty(PKG_BUILD_OPTIONS.libpurple:Mdbus) +... +.endif +</pre> +<p>Including <code class="filename">pkg-build-options.mk</code> here will set +the variable <code class="varname">PKG_BUILD_OPTIONS.libpurple</code> to the build +options of the libpurple package, which can then be queried like +<code class="varname">PKG_OPTIONS</code> in the <code class="filename">options.mk</code> +file. See the file <code class="filename">pkg-build-options.mk</code> for more +details.</p> +</div> </div> <div class="chapter" lang="en"> <div class="titlepage"><div><div><h2 class="title"> @@ -7602,7 +7655,7 @@ TOOLS_PLATFORM.true?= true # shell builtin <tbody> <tr class="question"> <td align="left" valign="top"> -<a name="tools.new"></a><a name="id2708056"></a><b>18.4.1.</b> +<a name="tools.new"></a><a name="id2708188"></a><b>18.4.1.</b> </td> <td align="left" valign="top"><p>How do I add a new tool?</p></td> </tr> @@ -7612,7 +7665,7 @@ TOOLS_PLATFORM.true?= true # shell builtin </tr> <tr class="question"> <td align="left" valign="top"> -<a name="tools.listall"></a><a name="id2708066"></a><b>18.4.2.</b> +<a name="tools.listall"></a><a name="id2708198"></a><b>18.4.2.</b> </td> <td align="left" valign="top"><p>How do I get a list of all available tools?</p></td> @@ -7623,7 +7676,7 @@ TOOLS_PLATFORM.true?= true # shell builtin </tr> <tr class="question"> <td align="left" valign="top"> -<a name="tools.used"></a><a name="id2708145"></a><b>18.4.3.</b> +<a name="tools.used"></a><a name="id2708209"></a><b>18.4.3.</b> </td> <td align="left" valign="top"><p>How can I get a list of all the tools that a package is using while being built? I want to know whether it @@ -7695,7 +7748,7 @@ TOOLS_PLATFORM.true?= true # shell builtin <dt><span class="sect2"><a href="#perl-modules">19.6.6. Packages installing perl modules</a></span></dt> <dt><span class="sect2"><a href="#faq.info-files">19.6.7. Packages installing info files</a></span></dt> <dt><span class="sect2"><a href="#manpages">19.6.8. Packages installing man pages</a></span></dt> -<dt><span class="sect2"><a href="#gconf2-data-files">19.6.9. Packages installing GConf2 data files</a></span></dt> +<dt><span class="sect2"><a href="#gconf-data-files">19.6.9. Packages installing GConf data files</a></span></dt> <dt><span class="sect2"><a href="#scrollkeeper-data-files">19.6.10. Packages installing scrollkeeper data files</a></span></dt> <dt><span class="sect2"><a href="#x11-fonts">19.6.11. Packages installing X11 fonts</a></span></dt> <dt><span class="sect2"><a href="#gtk2-modules">19.6.12. Packages installing GTK2 modules</a></span></dt> @@ -9022,17 +9075,17 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist </div> <div class="sect2" lang="en"> <div class="titlepage"><div><div><h3 class="title"> -<a name="gconf2-data-files"></a>19.6.9. Packages installing GConf2 data files</h3></div></div></div> +<a name="gconf-data-files"></a>19.6.9. Packages installing GConf data files</h3></div></div></div> <p>If a package installs <code class="filename">.schemas</code> or - <code class="filename">.entries</code> files, used by GConf2, + <code class="filename">.entries</code> files, used by GConf, you need to take some extra steps to make sure they get registered in the database:</p> <div class="orderedlist"><ol type="1"> -<li><p>Include <code class="filename">../../devel/GConf2/schemas.mk</code> +<li><p>Include <code class="filename">../../devel/GConf/schemas.mk</code> instead of its <code class="filename">buildlink3.mk</code> file. This - takes care of rebuilding the GConf2 database at installation and + takes care of rebuilding the GConf database at installation and deinstallation time, and tells the package where to install - GConf2 data files using some standard configure arguments. It + GConf data files using some standard configure arguments. It also disallows any access to the database directly from the package.</p></li> <li><p>Ensure that the package installs its @@ -9043,11 +9096,11 @@ PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist <li><p>Check the PLIST and remove any entries under the etc/gconf directory, as they will be handled automatically. See <a href="#faq.conf" title="9.13. How do I change the location of configuration files?">Section 9.13, “How do I change the location of configuration files?”</a> for more information.</p></li> -<li><p>Define the <code class="varname">GCONF2_SCHEMAS</code> variable in +<li><p>Define the <code class="varname">GCONF_SCHEMAS</code> variable in your <code class="filename">Makefile</code> with a list of all <code class="filename">.schemas</code> files installed by the package, if any. Names must not contain any directories in them.</p></li> -<li><p>Define the <code class="varname">GCONF2_ENTRIES</code> variable in +<li><p>Define the <code class="varname">GCONF_ENTRIES</code> variable in your <code class="filename">Makefile</code> with a list of all <code class="filename">.entries</code> files installed by the package, if any. Names must not contain any directories in @@ -9624,7 +9677,7 @@ do?</a> <tbody> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.makeflags"></a><a name="id2713952"></a><b>22.1.</b> +<a name="devfaq.makeflags"></a><a name="id2713947"></a><b>22.1.</b> </td> <td align="left" valign="top"><p>What is the difference between <code class="varname">MAKEFLAGS</code>, <code class="varname">.MAKEFLAGS</code> and @@ -9640,7 +9693,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.make"></a><a name="id2713990"></a><b>22.2.</b> +<a name="devfaq.make"></a><a name="id2713986"></a><b>22.2.</b> </td> <td align="left" valign="top"><p>What is the difference between <code class="varname">MAKE</code>, <code class="varname">GMAKE</code> and @@ -9658,7 +9711,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.cc"></a><a name="id2714030"></a><b>22.3.</b> +<a name="devfaq.cc"></a><a name="id2714026"></a><b>22.3.</b> </td> <td align="left" valign="top"><p>What is the difference between <code class="varname">CC</code>, <code class="varname">PKG_CC</code> and @@ -9676,7 +9729,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.bl3flags"></a><a name="id2714070"></a><b>22.4.</b> +<a name="devfaq.bl3flags"></a><a name="id2714066"></a><b>22.4.</b> </td> <td align="left" valign="top"><p>What is the difference between <code class="varname">BUILDLINK_LDFLAGS</code>, @@ -9689,7 +9742,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.bl3prefix"></a><a name="id2714090"></a><b>22.5.</b> +<a name="devfaq.bl3prefix"></a><a name="id2714086"></a><b>22.5.</b> </td> <td align="left" valign="top"><p>Why does <span><strong class="command">make show-var VARNAME=BUILDLINK_PREFIX.<em class="replaceable"><code>foo</code></em></strong></span> @@ -9705,7 +9758,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.master_sites"></a><a name="id2714120"></a><b>22.6.</b> +<a name="devfaq.master_sites"></a><a name="id2714116"></a><b>22.6.</b> </td> <td align="left" valign="top"><p>What does <code class="literal">${MASTER_SITE_SOURCEFORGE:=package/}</code> mean? I @@ -9729,7 +9782,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.mailinglists"></a><a name="id2714197"></a><b>22.7.</b> +<a name="devfaq.mailinglists"></a><a name="id2714261"></a><b>22.7.</b> </td> <td align="left" valign="top"><p>Which mailing lists are there for package developers?</p></td> @@ -9754,7 +9807,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.documentation"></a><a name="id2714304"></a><b>22.8.</b> +<a name="devfaq.documentation"></a><a name="id2714299"></a><b>22.8.</b> </td> <td align="left" valign="top"><p>Where is the pkgsrc documentation?</p></td> @@ -9802,7 +9855,7 @@ do?</a> </tr> <tr class="question"> <td align="left" valign="top"> -<a name="devfaq.too-much-time"></a><a name="id2714365"></a><b>22.9.</b> +<a name="devfaq.too-much-time"></a><a name="id2714361"></a><b>22.9.</b> </td> <td align="left" valign="top"><p>I have a little time to kill. What shall I do?</p></td> diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt index 1a99b73e092..01d95e4f9f1 100644 --- a/doc/pkgsrc.txt +++ b/doc/pkgsrc.txt @@ -265,6 +265,7 @@ II. The pkgsrc developer's guide 16.1. Global default options 16.2. Converting packages to use bsd.options.mk 16.3. Option Names + 16.4. Determining the options of dependencies 17. The build process @@ -352,7 +353,7 @@ II. The pkgsrc developer's guide 19.6.6. Packages installing perl modules 19.6.7. Packages installing info files 19.6.8. Packages installing man pages - 19.6.9. Packages installing GConf2 data files + 19.6.9. Packages installing GConf data files 19.6.10. Packages installing scrollkeeper data files 19.6.11. Packages installing X11 fonts 19.6.12. Packages installing GTK2 modules @@ -3275,6 +3276,7 @@ Table of Contents 16.1. Global default options 16.2. Converting packages to use bsd.options.mk 16.3. Option Names + 16.4. Determining the options of dependencies 17. The build process @@ -3361,7 +3363,7 @@ Table of Contents 19.6.6. Packages installing perl modules 19.6.7. Packages installing info files 19.6.8. Packages installing man pages - 19.6.9. Packages installing GConf2 data files + 19.6.9. Packages installing GConf data files 19.6.10. Packages installing scrollkeeper data files 19.6.11. Packages installing X11 fonts 19.6.12. Packages installing GTK2 modules @@ -5264,6 +5266,7 @@ Table of Contents 16.1. Global default options 16.2. Converting packages to use bsd.options.mk 16.3. Option Names +16.4. Determining the options of dependencies Many packages have the ability to be built to support different sets of features. bsd.options.mk is a framework in pkgsrc that provides generic @@ -5272,6 +5275,34 @@ can be built. It's possible for the user to specify exactly which sets of options will be built into a package or to allow a set of global default options apply. +There are two broad classes of behaviors that one might want to control via +options. One is whether some particular feature is enabled in a program that +will be built anyway, often by including or not including a dependency on some +other package. The other is whether or not an additional program will be built +as part of the package. Generally, it is better to make a split package for +such additional programs instead of using options, because it enables binary +packages to be built which can then be added separately. For example, the foo +package might have minimal dependencies (those packages without which foo +doesn't make sense), and then the foo-gfoo package might include the GTK +frontend program gfoo. This is better than including a gtk option to foo that +adds gfoo, because either that option is default, in which case binary users +can't get foo without gfoo, or not default, in which case they can't get gfoo. +With split packages, they can install foo without having GTK, and later decide +to install gfoo (pulling in GTK at that time). This is an advantage to source +users too, avoiding the need for rebuilds. + +Plugins with widely varying dependencies should usually be split instead of +options. + +It is often more work to maintain split packages, especially if the upstream +package does not support this. The decision of split vs. option should be made +based on the likelihood that users will want or object to the various pieces, +the size of the dependencies that are included, and the amount of work. + +A further consideration is licensing. Non-free parts, or parts that depend on +non-free dependencies (especially plugins) should almost always be split if +feasible. + 16.1. Global default options Global default options are listed in PKG_DEFAULT_OPTIONS, which is a list of @@ -5417,6 +5448,25 @@ description. The description should be a whole sentence (starting with an uppercase letter and ending with a period) that describes what enabling the option does. E. g. "Enable ispell support." The file is sorted by option names. +16.4. Determining the options of dependencies + +When writing buildlink3.mk files, it is often necessary to list different +dependencies based on the options with which the package was built. For +querying these options, the file pkgsrc/mk/pkg-build-options.mk should be used. +A typical example looks like this: + +pkgbase := libpurple +.include "../../mk/pkg-build-options.mk" + +.if !empty(PKG_BUILD_OPTIONS.libpurple:Mdbus) +... +.endif + +Including pkg-build-options.mk here will set the variable +PKG_BUILD_OPTIONS.libpurple to the build options of the libpurple package, +which can then be queried like PKG_OPTIONS in the options.mk file. See the file +pkg-build-options.mk for more details. + Chapter 17. The build process Table of Contents @@ -6379,7 +6429,7 @@ Table of Contents 19.6.6. Packages installing perl modules 19.6.7. Packages installing info files 19.6.8. Packages installing man pages - 19.6.9. Packages installing GConf2 data files + 19.6.9. Packages installing GConf data files 19.6.10. Packages installing scrollkeeper data files 19.6.11. Packages installing X11 fonts 19.6.12. Packages installing GTK2 modules @@ -7435,14 +7485,14 @@ use of --mandir, you can set GNU_CONFIGURE_MANDIR as needed. See Section 13.5, "Man page compression" for information on installation of compressed manual pages. -19.6.9. Packages installing GConf2 data files +19.6.9. Packages installing GConf data files -If a package installs .schemas or .entries files, used by GConf2, you need to +If a package installs .schemas or .entries files, used by GConf, you need to take some extra steps to make sure they get registered in the database: - 1. Include ../../devel/GConf2/schemas.mk instead of its buildlink3.mk file. - This takes care of rebuilding the GConf2 database at installation and - deinstallation time, and tells the package where to install GConf2 data + 1. Include ../../devel/GConf/schemas.mk instead of its buildlink3.mk file. + This takes care of rebuilding the GConf database at installation and + deinstallation time, and tells the package where to install GConf data files using some standard configure arguments. It also disallows any access to the database directly from the package. @@ -7454,11 +7504,11 @@ take some extra steps to make sure they get registered in the database: they will be handled automatically. See Section 9.13, "How do I change the location of configuration files?" for more information. - 4. Define the GCONF2_SCHEMAS variable in your Makefile with a list of all + 4. Define the GCONF_SCHEMAS variable in your Makefile with a list of all .schemas files installed by the package, if any. Names must not contain any directories in them. - 5. Define the GCONF2_ENTRIES variable in your Makefile with a list of all + 5. Define the GCONF_ENTRIES variable in your Makefile with a list of all .entries files installed by the package, if any. Names must not contain any directories in them. |