pkgsrc-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc regen
details: https://anonhg.NetBSD.org/pkgsrc/rev/1d9015c77c4c
branches: trunk
changeset: 520489:1d9015c77c4c
user: rillig <rillig%pkgsrc.org@localhost>
date: Sun Oct 22 12:15:00 2006 +0000
description:
regen
diffstat:
doc/pkgsrc.html | 772 +++++++++++++++++++++++++++++++++++++++----------------
doc/pkgsrc.txt | 361 +++++++++++++++++++++++--
2 files changed, 875 insertions(+), 258 deletions(-)
diffs (truncated from 2131 to 300 lines):
diff -r 8f49384c5676 -r 1d9015c77c4c doc/pkgsrc.html
--- a/doc/pkgsrc.html Sun Oct 22 11:39:00 2006 +0000
+++ b/doc/pkgsrc.html Sun Oct 22 12:15:00 2006 +0000
@@ -5,11 +5,7 @@
<title>The pkgsrc guide</title>
<link rel="stylesheet" href="/NetBSD.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
-<meta name="description" content="pkgsrc is a centralized package management system for
- Unix-like operating systems. This guide provides information for
- users and developers of pkgsrc. It covers installation of binary
- and source packages, creation of binary and source packages and
- a high-level overview about the infrastructure.">
+<meta name="description" content="pkgsrc is a centralized package management system for Unix-like operating systems. This guide provides information for users and developers of pkgsrc. It covers
installation of binary and source packages, creation of binary and source packages and a high-level overview about the infrastructure.">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en">
<div class="titlepage">
@@ -146,7 +142,7 @@
</dl></dd>
<dt><span class="chapter"><a href="#files">7. Directory layout of the installed files</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#files.localbase">7.1. File system layout in <code class="literal">${PREFIX}</code></a></span></dt>
+<dt><span class="sect1"><a href="#files.localbase">7.1. File system layout in <code class="literal">${LOCALBASE}</code></a></span></dt>
<dt><span class="sect1"><a href="#files.varbase">7.2. File system layout in <code class="literal">${VARBASE}</code></a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#faq">8. Frequently Asked Questions</a></span></dt>
@@ -176,6 +172,15 @@
<dt><span class="part"><a href="#developers-guide">II. The pkgsrc developer's guide</a></span></dt>
<dd><dl>
<dt><span class="chapter"><a href="#creating">9. Creating a new pkgsrc package from scratch</a></span></dt>
+<dd><dl>
+<dt><span class="sect1"><a href="#creating.common">9.1. Common types of packages</a></span></dt>
+<dd><dl>
+<dt><span class="sect2"><a href="#creating.perl-module">9.1.1. Perl modules</a></span></dt>
+<dt><span class="sect2"><a href="#creating.kde-app">9.1.2. KDE applications</a></span></dt>
+</dl></dd>
+<dt><span class="sect1"><a href="#creating.examples">9.2. Examples</a></span></dt>
+<dd><dl><dt><span class="sect2"><a href="#creating.nvu">9.2.1. How the www/nvu package came into pkgsrc</a></span></dt></dl></dd>
+</dl></dd>
<dt><span class="chapter"><a href="#components">10. Package components - files, directories and contents</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#components.Makefile">10.1. <code class="filename">Makefile</code></a></span></dt>
@@ -493,13 +498,13 @@
<p>pkgsrc currently contains several thousand packages,
including:</p>
<div class="itemizedlist"><ul type="disc">
-<li><p><a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache/README.html"; target="_top"><code class="filename">www/apache</code></a> - The Apache
+<li><p><a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/apache/README.html"; target="_top"><code class="filename">www/apache</code></a> - The Apache
web server</p></li>
-<li><p><a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/firefox/README.html"; target="_top"><code class="filename">www/firefox</code></a> - The Firefox
+<li><p><a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/firefox/README.html"; target="_top"><code class="filename">www/firefox</code></a> - The Firefox
web browser</p></li>
-<li><p><a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/gnome/README.html"; target="_top"><code class="filename">meta-pkgs/gnome</code></a> - The GNOME
+<li><p><a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/gnome/README.html"; target="_top"><code class="filename">meta-pkgs/gnome</code></a> - The GNOME
Desktop Environment</p></li>
-<li><p><a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/kde3/README.html"; target="_top"><code class="filename">meta-pkgs/kde3</code></a> - The K
+<li><p><a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/kde3/README.html"; target="_top"><code class="filename">meta-pkgs/kde3</code></a> - The K
Desktop Environment</p></li>
</ul></div>
<p>...just to name a few.</p>
@@ -541,6 +546,20 @@
available right out of the box, so you can configure it specifically
for your environment.</p></li>
</ul></div>
+<p>The following principles are basic to pkgsrc:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>“<span class="quote">It should only work if it's right.</span>”
+— That means, if a package contains bugs, it's better to find
+them and to complain about them rather than to just install the package
+and hope that it works. There are numerous checks in pkgsrc that try to
+find such bugs: Static analysis tools (<a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkglint/README.html"; target="_top"><code class="filename">pkgtools/pkglint</code></a>),
build-time checks (portability
+of shell scripts), and post-installation checks (installed files,
+references to shared libraries, script interpreters).</p></li>
+<li><p>“<span class="quote">If it works, it should work everywhere</span>”
+— Like NetBSD has been ported to many hardware architectures,
+pkgsrc has been ported to many operating systems. Care is taken that
+packages behave the same on all platforms.</p></li>
+</ul></div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
@@ -554,7 +573,7 @@
grown a lot, and now supports the following platforms:</p>
<div class="table">
<a name="supported-platforms"></a><p class="title"><b>Table 1.1. Platforms supported by pkgsrc</b></p>
-<table summary="Platforms supported by pkgsrc" border="1">
+<div class="table-contents"><table summary="Platforms supported by pkgsrc" border="1">
<colgroup>
<col>
<col>
@@ -619,8 +638,9 @@
<td align="center">Nov 2004</td>
</tr>
</tbody>
-</table>
-</div>
+</table></div>
+</div>
+<br class="table-break">
</div>
</div>
<div class="sect1" lang="en">
@@ -816,7 +836,7 @@
</dl></dd>
<dt><span class="chapter"><a href="#files">7. Directory layout of the installed files</a></span></dt>
<dd><dl>
-<dt><span class="sect1"><a href="#files.localbase">7.1. File system layout in <code class="literal">${PREFIX}</code></a></span></dt>
+<dt><span class="sect1"><a href="#files.localbase">7.1. File system layout in <code class="literal">${LOCALBASE}</code></a></span></dt>
<dt><span class="sect1"><a href="#files.varbase">7.2. File system layout in <code class="literal">${VARBASE}</code></a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#faq">8. Frequently Asked Questions</a></span></dt>
@@ -863,15 +883,14 @@
</dl></dd>
</dl>
</div>
-<p>The most common location where pkgsrc is installed is
- <code class="filename">/usr/pkgsrc</code> for the “<span class="quote">package
- sources</span>” and <code class="filename">/usr/pkg</code> for the
- installed binary packages. You are though free to install the
- sources and binary packages wherever you want in your
- filesystem, provided that both paths do not contain white-space
- or other characters that are interpreted specially by the shell
- and some other programs. A safe bet is to use only letters,
- digits, underscores and dashes in the names.</p>
+<p>Before you download and extract the files, you need to decide
+where you want to extract them. When using pkgsrc as root user, pkgsrc
+is usually installed in <code class="filename">/usr/pkgsrc</code>. You are though
+free to install the sources and binary packages wherever you want in
+your filesystem, provided that the pathname does not contain white-space
+or other characters that are interpreted specially by the shell and some
+other programs. A safe bet is to use only letters, digits, underscores
+and dashes.</p>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="getting-first"></a>2.1. Getting pkgsrc for the first time</h2></div></div></div>
@@ -899,8 +918,8 @@
directory <code class="filename">2006Q1</code> and is also called <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/2006Q1/pkgsrc.tar.gz"; target="_top"><code
class="filename">pkgsrc.tar.gz</code></a>.</p>
<p>After downloading the tar file, change to the directory
where you want to have pkgsrc. This is usually
- <code class="filename">/usr</code>. Then, run <span><strong class="command">tar xfz
- pkgsrc.tar.gz</strong></span> to extract the files.</p>
+ <code class="filename">/usr</code>. Then, run <span><strong class="command">gzcat
+ pkgsrc.tar.gz | tar xf -</strong></span> to extract the files.</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
@@ -1049,7 +1068,7 @@
</div>
<div class="table">
<a name="binary-kits"></a><p class="title"><b>Table 3.1. Binary kits and available packages</b></p>
-<table summary="Binary kits and available packages" border="1">
+<div class="table-contents"><table summary="Binary kits and available packages" border="1">
<colgroup>
<col>
<col>
@@ -1220,9 +1239,9 @@
<td class="binary-pkgs-url"> </td>
</tr>
</tbody>
-</table>
-</div>
-<p>
+</table></div>
+</div>
+<br class="table-break"><p>
Simply download the binary kit for your platform, and extract it into
<code class="filename">/</code> e.g.
</p>
@@ -1496,10 +1515,10 @@
<p>Interix has no native support for audio output. For audio
support, pkgsrc uses the <span><strong class="command">esound</strong></span> client/server
audio system on Interix. Unlike on most platforms, the
- <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/audio/esound/README.html"; target="_top"><code class="filename">audio/esound</code></a> package does
+ <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/audio/esound/README.html"; target="_top"><code class="filename">audio/esound</code></a> package does
<span class="emphasis"><em>not</em></span> contain the <span><strong class="command">esd</strong></span>
server component. To output audio via an Interix host, the
- <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/emulators/cygwin_esound/README.html"; target="_top"><code class="filename">emulators/cygwin_esound</code></a> package
+ <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/emulators/cygwin_esound/README.html"; target="_top"><code class="filename">emulators/cygwin_esound</code></a> package
must also be installed.</p>
</li>
<li>
@@ -1702,7 +1721,7 @@
for building all packages.</p>
<p>It is recommended that an external gcc be used only for bootstrapping,
then either build gcc from
- <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/gcc/README.html"; target="_top"><code class="filename">lang/gcc</code></a> or install a binary gcc
+ <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/lang/gcc/README.html"; target="_top"><code class="filename">lang/gcc</code></a> or install a binary gcc
package, then remove gcc used during bootstrapping.</p>
<p>Binary packages of gcc can be found through <a href="http://www.sun.com/bigadmin/common/freewareSearch.html"; target="_top">http://www.sun.com/bigadmin/common/freewareSearch.html</a>.</p>
</div>
@@ -1789,13 +1808,13 @@
<p>Sometimes, when using <span><strong class="command">libtool</strong></span>,
<code class="filename">/bin/ksh</code> crashes with a segmentation fault.
The workaround is to use another shell for the configure
- scripts, for example by installing <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/bash/README.html"; target="_top"><code class="filename">shells/bash</code></a> and adding the
following lines
+ scripts, for example by installing <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/shells/bash/README.html"; target="_top"><code class="filename">shells/bash</code></a> and adding the
following lines
to your <code class="filename">mk.conf</code>:</p>
<pre class="programlisting">
CONFIG_SHELL= ${LOCALBASE}/bin/bash
WRAPPER_SHELL= ${LOCALBASE}/bin/bash
</pre>
-<p>Then, rebuild the <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/libtool-base/README.html"; target="_top"><code class="filename">devel/libtool-base</code></a> package.</p>
+<p>Then, rebuild the <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/libtool-base/README.html"; target="_top"><code class="filename">devel/libtool-base</code></a> package.</p>
</div>
</div>
</div>
@@ -1937,7 +1956,7 @@
moved, since removing them could cause missing dependencies. To
use these packages, add the <code class="filename">vulnerable</code>
directory to your <code class="varname">PKG_PATH</code>. However, you should run
- <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a> regularly,
+ <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a> regularly,
especially after installing new packages, and verify that the
vulnerabilities are acceptable for your configuration. An example
<code class="varname">PKG_PATH</code> would be:
@@ -1991,14 +2010,14 @@
FTP site at <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities"; target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities</a>.
</p>
<p>
- Through <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a>,
+ Through <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a>,
this list can be downloaded
automatically, and a security audit of all packages installed on a system
can take place.
</p>
<p>
There are two components to
- <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a>. The first
+ <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a>. The first
component, “<span class="quote">download-vulnerability-list</span>”, is for downloading
the list of vulnerabilities from the NetBSD FTP site. The second
component, “<span class="quote">audit-packages</span>”, checks to see if any of your
@@ -2008,18 +2027,18 @@
<pre class="screen">Package samba-2.0.9 has a local-root-shell vulnerability, see
http://www.samba.org/samba/whatsnew/macroexploit.html</pre>
<p>
- One can set up <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a> to download
the
+ One can set up <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a> to download
the
<a href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities"; target="_top">vulnerabilities</a>
file daily, and include a package audit in the daily security script.
Details on this are located in the <a href="http://cvsweb.NetBSD.org/bsdweb.cgi/pkgsrc/security/audit-packages/MESSAGE?rev=HEAD&content-type=text/x-cvsweb-markup"; target="_top">MESSAGE</a>
- file for <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a>.
+ file for <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/security/audit-packages/README.html"; target="_top"><code class="filename">security/audit-packages</code></a>.
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="pkg_versions"></a>4.1.6. Finding if newer versions of your installed packages are in pkgsrc</h3></div></div></div>
<p>
- Install <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html"; target="_top"><code class="filename">pkgtools/pkglint</code></a> and run
+ Install <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkglint/README.html"; target="_top"><code class="filename">pkgtools/pkglint</code></a> and run
<span><strong class="command">lintpkgsrc</strong></span> with the “<span class="quote">-i</span>”
argument to check if your packages are up-to-date, e.g.
</p>
@@ -2062,7 +2081,7 @@
categories. You can browse the online index of packages, or run
<span><strong class="command">make readme</strong></span> from the <code class="filename">pkgsrc</code>
directory to build local <code class="filename">README.html</code> files for
- all packages, viewable with any web browser such as <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/lynx/README.html"; target="_top"><code class="filename">www/lynx</code></a> or <a
href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/firefox/README.html"; target="_top"><code class="filename">www/firefox</code></a>.</p>
+ all packages, viewable with any web browser such as <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/lynx/README.html"; target="_top"><code class="filename">www/lynx</code></a> or <a
href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/www/firefox/README.html"; target="_top"><code class="filename">www/firefox</code></a>.</p>
<p>The default <span class="emphasis"><em>prefix</em></span> for installed packages
is <code class="filename">/usr/pkg</code>. If you wish to change this, you
should do so by setting <code class="varname">LOCALBASE</code> in
@@ -2096,6 +2115,13 @@
<pre class="screen">DISTDIR=/cdrom/pkgsrc/distfiles</pre>
<p>
to your <code class="filename">mk.conf</code>.</p>
+<p>By default a list of distribution sites will be randomly
+ intermixed to prevent huge load on servers which holding popular
+ packages (for example, SourceForge.net mirrors). Thus, every
+ time when you need to fetch yet another distfile all the mirrors
+ will be tried in new (random) order. You can turn this feature
+ off by setting <code class="varname">MASTER_SORT_RANDOM=NO</code> (for
+ <code class="varname">PKG_DEVELOPER</code>s it's already disabled).</p>
<p>You can overwrite some of the major distribution sites to
fit to sites that are close to your own. By setting one or two
variables you can modify the order in which the master sites are
@@ -2113,7 +2139,7 @@
and adding the definitions there.</p>
<p>
If a package depends on many other packages (such as
- <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/kde3/README.html"; target="_top"><code class="filename">meta-pkgs/kde3</code></a>), the build process may
+ <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/meta-pkgs/kde3/README.html"; target="_top"><code class="filename">meta-pkgs/kde3</code></a>), the build process may
alternate between periods of
downloading source, and compiling. To ensure you have all the source
downloaded initially you can run the command:
@@ -2432,7 +2458,7 @@
<p>Using <code class="varname">CFLAGS=</code> (i.e. without the
“<span class="quote">+</span>”) may lead to problems with packages that need
to add their own flags. Also, you may want to take a look at
- the <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/cpuflags/README.html"; target="_top"><code class="filename">devel/cpuflags</code></a> package if
+ the <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/cpuflags/README.html"; target="_top"><code class="filename">devel/cpuflags</code></a> package if
you're interested in optimization for the current CPU.</p>
</div>
<div class="sect2" lang="en">
@@ -2597,7 +2623,7 @@
it. Binary packages are created by default in
<code class="filename">/usr/pkgsrc/packages</code>, in the form of a
gzipped tar file. See <a href="#logs.package" title="B.2. Packaging figlet">Section B.2, “Packaging figlet”</a> for a
- continuation of the above <a href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/misc/figlet/README.html"; target="_top"><code class="filename">misc/figlet</code></a> example.</p>
+ continuation of the above <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/misc/figlet/README.html"; target="_top"><code class="filename">misc/figlet</code></a> example.</p>
Home |
Main Index |
Thread Index |
Old Index