pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc Regen after addition of some GNOME-specific docume...
details: https://anonhg.NetBSD.org/pkgsrc/rev/ff165c7e5058
branches: trunk
changeset: 518135:ff165c7e5058
user: jmmv <jmmv%pkgsrc.org@localhost>
date: Fri Sep 01 16:46:49 2006 +0000
description:
Regen after addition of some GNOME-specific documentation.
diffstat:
doc/pkgsrc.html | 811 ++++++++++++++++++++++++++++++++++++++++++++-----------
doc/pkgsrc.txt | 660 +++++++++++++++++++++++++++++++++++---------
2 files changed, 1156 insertions(+), 315 deletions(-)
diffs (truncated from 2131 to 300 lines):
diff -r ef29810efcd5 -r ff165c7e5058 doc/pkgsrc.html
--- a/doc/pkgsrc.html Fri Sep 01 16:35:38 2006 +0000
+++ b/doc/pkgsrc.html Fri Sep 01 16:46:49 2006 +0000
@@ -31,7 +31,7 @@
</h3>
</div></div>
<div><p class="copyright">Copyright © 1994-2006 The NetBSD Foundation, Inc</p></div>
-<div><p class="pubdate">$NetBSD: pkgsrc.xml,v 1.21 2006/07/03 23:51:01 rillig Exp $</p></div>
+<div><p class="pubdate">$NetBSD: pkgsrc.xml,v 1.22 2006/09/01 16:35:39 jmmv Exp $</p></div>
<div><div class="abstract">
<p class="title"><b>Abstract</b></p>
<p>pkgsrc is a centralized package management system for
@@ -170,6 +170,10 @@
<dt><span class="sect1"><a href="#components.Makefile">9.1. <code class="filename">Makefile</code></a></span></dt>
<dt><span class="sect1"><a href="#components.distinfo">9.2. <code class="filename">distinfo</code></a></span></dt>
<dt><span class="sect1"><a href="#components.patches">9.3. patches/*</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#components.patches.guidelines">9.3.1. Patching guidelines</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.feedback">9.3.2. Feedback to the author</a></span></dt>
+</dl></dd>
<dt><span class="sect1"><a href="#other-mandatory-files">9.4. Other mandatory files</a></span></dt>
<dt><span class="sect1"><a href="#components.optional">9.5. Optional files</a></span></dt>
<dd><dl>
@@ -328,8 +332,9 @@
<dt><span class="sect2"><a href="#intltool">17.5.15. Packages using intltool</a></span></dt>
<dt><span class="sect2"><a href="#startup-scripts">17.5.16. Packages installing startup scripts</a></span></dt>
<dt><span class="sect2"><a href="#tex-packages">17.5.17. Packages installing TeX modules</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#feedback-to-author">17.6. Feedback to the author</a></span></dt>
+<dt><span class="sect2"><a href="#hicolor-theme">17.5.18. Packages installing hicolor theme icons</a></span></dt>
+<dt><span class="sect2"><a href="#desktop-files">17.5.19. Packages installing desktop files</a></span></dt>
+</dl></dd>
</dl></dd>
<dt><span class="chapter"><a href="#debug">18. Debugging</a></span></dt>
<dt><span class="chapter"><a href="#submit">19. Submitting and Committing</a></span></dt>
@@ -342,44 +347,51 @@
<dt><span class="sect1"><a href="#moving-package">19.6. Moving a package in pkgsrc</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#devfaq">20. Frequently Asked Questions</a></span></dt>
+<dt><span class="chapter"><a href="#gnome">21. GNOME packaging and porting</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#meta-packages">21.1. Meta packages</a></span></dt>
+<dt><span class="sect1"><a href="#new-package">21.2. Packaging a GNOME application</a></span></dt>
+<dt><span class="sect1"><a href="#full-update">21.3. Updating GNOME to a newer version</a></span></dt>
+<dt><span class="sect1"><a href="#patching">21.4. Patching guidelines</a></span></dt>
+</dl></dd>
</dl></dd>
<dt><span class="part"><a href="#infrastructure">III. The pkgsrc infrastructure internals</a></span></dt>
<dd><dl>
-<dt><span class="chapter"><a href="#infr.design">21. Design of the pkgsrc infrastructure</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#infr.vardef">21.1. The meaning of variable definitions</a></span></dt>
-<dt><span class="sect1"><a href="#infr.vardef.problems">21.2. Avoiding problems before they arise</a></span></dt>
-<dt><span class="sect1"><a href="#infr.var">21.3. Variable evaluation</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#infr.var.load">21.3.1. At load time</a></span></dt>
-<dt><span class="sect2"><a href="#infr.var.run">21.3.2. At runtime</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#infr.varspec">21.4. How can variables be specified?</a></span></dt>
-<dt><span class="sect1"><a href="#infr.design.intf">21.5. Designing interfaces for Makefile fragments</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#infr.design.intf.proc">21.5.1. Procedures with parameters</a></span></dt>
-<dt><span class="sect2"><a href="#infr.design.intf.action">21.5.2. Actions taken on behalf of parameters</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#infr.order">21.6. The order in which files are loaded</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#infr.order.prefs">21.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
-<dt><span class="sect2"><a href="#infr.order.pkg">21.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
-</dl></dd>
-</dl></dd>
-<dt><span class="chapter"><a href="#regression">22. Regression tests</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#regression.descr">22.1. The regression tests framework</a></span></dt>
-<dt><span class="sect1"><a href="#regression.run">22.2. Running the regression tests</a></span></dt>
-<dt><span class="sect1"><a href="#regression.new">22.3. Adding a new regression test</a></span></dt>
-<dd><dl>
-<dt><span class="sect2"><a href="#regression.fun.override">22.3.1. Overridable functions</a></span></dt>
-<dt><span class="sect2"><a href="#regression.fun.helper">22.3.2. Helper functions</a></span></dt>
-</dl></dd>
-</dl></dd>
-<dt><span class="chapter"><a href="#porting">23. Porting pkgsrc</a></span></dt>
-<dd><dl>
-<dt><span class="sect1"><a href="#porting.opsys">23.1. Porting pkgsrc to a new operating system</a></span></dt>
-<dt><span class="sect1"><a href="#porting.compiler">23.2. Adding support for a new compiler</a></span></dt>
+<dt><span class="chapter"><a href="#infr.design">22. Design of the pkgsrc infrastructure</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#infr.vardef">22.1. The meaning of variable definitions</a></span></dt>
+<dt><span class="sect1"><a href="#infr.vardef.problems">22.2. Avoiding problems before they arise</a></span></dt>
+<dt><span class="sect1"><a href="#infr.var">22.3. Variable evaluation</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#infr.var.load">22.3.1. At load time</a></span></dt>
+<dt><span class="sect2"><a href="#infr.var.run">22.3.2. At runtime</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#infr.varspec">22.4. How can variables be specified?</a></span></dt>
+<dt><span class="sect1"><a href="#infr.design.intf">22.5. Designing interfaces for Makefile fragments</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#infr.design.intf.proc">22.5.1. Procedures with parameters</a></span></dt>
+<dt><span class="sect2"><a href="#infr.design.intf.action">22.5.2. Actions taken on behalf of parameters</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#infr.order">22.6. The order in which files are loaded</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#infr.order.prefs">22.6.1. The order in <code class="filename">bsd.prefs.mk</code></a></span></dt>
+<dt><span class="sect2"><a href="#infr.order.pkg">22.6.2. The order in <code class="filename">bsd.pkg.mk</code></a></span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="chapter"><a href="#regression">23. Regression tests</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#regression.descr">23.1. The regression tests framework</a></span></dt>
+<dt><span class="sect1"><a href="#regression.run">23.2. Running the regression tests</a></span></dt>
+<dt><span class="sect1"><a href="#regression.new">23.3. Adding a new regression test</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#regression.fun.override">23.3.1. Overridable functions</a></span></dt>
+<dt><span class="sect2"><a href="#regression.fun.helper">23.3.2. Helper functions</a></span></dt>
+</dl></dd>
+</dl></dd>
+<dt><span class="chapter"><a href="#porting">24. Porting pkgsrc</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#porting.opsys">24.1. Porting pkgsrc to a new operating system</a></span></dt>
+<dt><span class="sect1"><a href="#porting.compiler">24.2. Adding support for a new compiler</a></span></dt>
</dl></dd>
</dl></dd>
<dt><span class="appendix"><a href="#examples">A. A simple example package: bison</a></span></dt>
@@ -423,6 +435,10 @@
</dt>
<dt>3.1. <a href="#binary-kits">Binary kits and available packages</a>
</dt>
+<dt>9.1. <a href="#patch-examples">Patching examples</a>
+</dt>
+<dt>21.1. <a href="#plist-handling">PLIST handling for GNOME packages</a>
+</dt>
</dl>
</div>
<div class="chapter" lang="en">
@@ -1240,7 +1256,7 @@
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="darwin"></a>3.3.1. Darwin (Mac OS X)</h3></div></div></div>
-<p>Darwin 5.x and 6.x are supported. There are two methods of using
+<p>Darwin 5.x and up are supported. There are two methods of using
pkgsrc on Mac OS X, by using a <a href="#platform.osx-image" title="3.3.1.1. Using a disk image">disk
image</a>, or a <a href="#platform.osx-ufs" title="3.3.1.2. Using a UFS partition">UFS
partition</a>.</p>
@@ -1255,18 +1271,23 @@
at boot time, where you must manually mount a disk image.</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
-<p>You cannot use a HFS+ file system for pkgsrc, because pkgsrc currently
- requires the file system to be case-sensitive, and HFS+ is not.</p>
+<p>You cannot use an ordinary HFS+ file system for pkgsrc, because pkgsrc currently
+ requires the file system to be case-sensitive. You can, however, use a case-sensitive HFS+ file system as found in Darwin 7.0 and newer.</p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="platform.osx-image"></a>3.3.1.1. Using a disk image</h4></div></div></div>
<p>Create the disk image:</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd pkgsrc/bootstrap</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>./ufsdiskimage create ~/Documents/NetBSD 512</code></strong> # megabytes - season to taste
-<code class="prompt">#</code> <strong class="userinput"><code>./ufsdiskimage mount ~/Documents/NetBSD</code></strong>
+<code class="prompt">#</code> <strong class="userinput"><code>./darwindiskimage create ~/Documents/NetBSD 512</code></strong> # megabytes - season to taste
+<code class="prompt">#</code> <strong class="userinput"><code>./darwindiskimage mount ~/Documents/NetBSD</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>sudo chown `id -u`:`id -g` /Volumes/NetBSD</code></strong></pre>
-<p>That's it!</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">Note</h3>
+<p>darwindiskimage will mount the filesystem nosuid, which will cause problems for packages that depend on setgid. It will also mount the filesystem asynchronous, which is somewhat dangerous
according to the mount(8) man page.</p>
+</div>
+<p>Allow suid and synchronous writes:</p>
+<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>sudo mount -u -o suid,sync /Volumes/NetBSD</code></strong></pre>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
@@ -2059,7 +2080,7 @@
<p>You can overwrite some of the major distribution sites to fit to sites
that are close to your own. Have a look at
<code class="filename">pkgsrc/mk/defaults/mk.conf</code> to find some examples
- — in particular, look for the <code class="varname">MASTER_SORT</code>,
+ — in particular, look for the <code class="varname">MASTER_SORT</code>,
<code class="varname">MASTER_SORT_REGEX</code> and
<code class="varname">INET_COUNTRY</code> definitions. This may save some of your
bandwidth and time.</p>
@@ -2320,7 +2341,7 @@
can be NFS-mounted while <code class="filename">${WRKOBJDIR}</code>
is local to every architecture. (It should be noted that
<code class="varname">PKGSRCDIR</code> should not be set by the user
- — it is an internal definition which refers to the
+ — it is an internal definition which refers to the
root of the pkgsrc tree. It is possible to have many
pkgsrc tree instances.)</p></li>
<li><p><code class="varname">LOCALPATCHES</code>:
@@ -2793,7 +2814,7 @@
</li>
<li>
<p><code class="filename">/usr/src</code> (system sources,
- e. g. for <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/aperture/README.html"; target="_top"><code class="filename">sysutils/aperture</code></a>):</p>
+ e. g. for <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/aperture/README.html"; target="_top"><code class="filename">sysutils/aperture</code></a>):</p>
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ln -s ../disk1/cvs .</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>ln -s cvs/src-2.0 src</code></strong></pre>
</li>
@@ -3449,6 +3470,10 @@
<dt><span class="sect1"><a href="#components.Makefile">9.1. <code class="filename">Makefile</code></a></span></dt>
<dt><span class="sect1"><a href="#components.distinfo">9.2. <code class="filename">distinfo</code></a></span></dt>
<dt><span class="sect1"><a href="#components.patches">9.3. patches/*</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#components.patches.guidelines">9.3.1. Patching guidelines</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.feedback">9.3.2. Feedback to the author</a></span></dt>
+</dl></dd>
<dt><span class="sect1"><a href="#other-mandatory-files">9.4. Other mandatory files</a></span></dt>
<dt><span class="sect1"><a href="#components.optional">9.5. Optional files</a></span></dt>
<dd><dl>
@@ -3607,8 +3632,9 @@
<dt><span class="sect2"><a href="#intltool">17.5.15. Packages using intltool</a></span></dt>
<dt><span class="sect2"><a href="#startup-scripts">17.5.16. Packages installing startup scripts</a></span></dt>
<dt><span class="sect2"><a href="#tex-packages">17.5.17. Packages installing TeX modules</a></span></dt>
-</dl></dd>
-<dt><span class="sect1"><a href="#feedback-to-author">17.6. Feedback to the author</a></span></dt>
+<dt><span class="sect2"><a href="#hicolor-theme">17.5.18. Packages installing hicolor theme icons</a></span></dt>
+<dt><span class="sect2"><a href="#desktop-files">17.5.19. Packages installing desktop files</a></span></dt>
+</dl></dd>
</dl></dd>
<dt><span class="chapter"><a href="#debug">18. Debugging</a></span></dt>
<dt><span class="chapter"><a href="#submit">19. Submitting and Committing</a></span></dt>
@@ -3621,6 +3647,13 @@
<dt><span class="sect1"><a href="#moving-package">19.6. Moving a package in pkgsrc</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#devfaq">20. Frequently Asked Questions</a></span></dt>
+<dt><span class="chapter"><a href="#gnome">21. GNOME packaging and porting</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#meta-packages">21.1. Meta packages</a></span></dt>
+<dt><span class="sect1"><a href="#new-package">21.2. Packaging a GNOME application</a></span></dt>
+<dt><span class="sect1"><a href="#full-update">21.3. Updating GNOME to a newer version</a></span></dt>
+<dt><span class="sect1"><a href="#patching">21.4. Patching guidelines</a></span></dt>
+</dl></dd>
</dl>
</div>
</div>
@@ -3717,6 +3750,10 @@
<dt><span class="sect1"><a href="#components.Makefile">9.1. <code class="filename">Makefile</code></a></span></dt>
<dt><span class="sect1"><a href="#components.distinfo">9.2. <code class="filename">distinfo</code></a></span></dt>
<dt><span class="sect1"><a href="#components.patches">9.3. patches/*</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#components.patches.guidelines">9.3.1. Patching guidelines</a></span></dt>
+<dt><span class="sect2"><a href="#components.patches.feedback">9.3.2. Feedback to the author</a></span></dt>
+</dl></dd>
<dt><span class="sect1"><a href="#other-mandatory-files">9.4. Other mandatory files</a></span></dt>
<dt><span class="sect1"><a href="#components.optional">9.5. Optional files</a></span></dt>
<dd><dl>
@@ -3919,11 +3956,6 @@
<p>When you have finished a package, remember to generate the checksums
for the patch files by using the <span><strong class="command">make makepatchsum</strong></span>
command, see <a href="#components.distinfo" title="9.2. distinfo">Section 9.2, “<code class="filename">distinfo</code>”</a>.</p>
-<p>When adding a patch that corrects a problem in the distfile (rather
- than e.g. enforcing pkgsrc's view of where man pages should go), send
- the patch as a bug report to the maintainer. This benefits
- non-pkgsrc users of the package, and usually enables removing
- the patch in future version.</p>
<p>Patch files that are distributed by the author or other
maintainers can be listed in
<code class="varname">$PATCHFILES</code>. </p>
@@ -3939,6 +3971,128 @@
it in <code class="filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
files in the named directory are expected to be patch files, and
<span class="emphasis"><em>they are applied after pkgsrc patches are applied</em></span>.</p>
+<div class="sect2" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="components.patches.guidelines"></a>9.3.1. Patching guidelines</h3></div></div></div>
+<p>When fixing a portability issue in the code do not use
+ preprocessor magic to check for the current operating system nor
+ platform. Doing so hurts portability to other platforms because
+ the OS-specific details are not abstracted appropriately.</p>
+<p>The general rule to follow is: instead of checking for the
+ operating system the application is being built on, check for the
+ specific <span class="emphasis"><em>features</em></span> you need. For example,
+ instead of assuming that kqueue is available under NetBSD and
+ using the <code class="varname">__NetBSD__</code> macro to conditionalize
+ kqueue support, add a check that detects kqueue itself —
+ yes, this generally involves patching the
+ <span><strong class="command">configure</strong></span> script. There is absolutely nothing
+ that prevents some OSes from adopting interfaces from other OSes
+ (e.g. Linux implementing kqueue), something that the above checks
+ cannot take into account.</p>
+<p>Of course, checking for features generally involves more
+ work on the developer's side, but the resulting changes are
+ clearner and there are chances they will work on many other
+ platforms. Not to mention that there are higher chances of being
+ later integrated into the mainstream sources. Remember:
+ <span class="emphasis"><em>It doesn't work unless it is right!</em></span></p>
+<p>Some typical examples:</p>
+<div class="table">
+<a name="patch-examples"></a><p class="title"><b>Table 9.1. Patching examples</b></p>
+<div class="table-contents"><table summary="Patching examples" border="1">
+<colgroup>
+<col>
+<col>
+<col>
+</colgroup>
+<thead><tr>
+<th>Where</th>
+<th>Incorrect</th>
+<th>Correct</th>
+</tr></thead>
Home |
Main Index |
Thread Index |
Old Index