[pkgsrc/trunk]: pkgsrc/doc Move DESTDIR documentation to guide.

[wiz <wiz%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/a3cd2692e914
branches:  trunk
changeset: 532018:a3cd2692e914
user:      wiz <wiz%pkgsrc.org@localhost>
date:      Fri Aug 10 00:51:50 2007 +0000

description:
Move DESTDIR documentation to guide.

diffstat:

 doc/HOWTO-destdir               |  44 -----------------------------------------
 doc/guide/files/configuring.xml |  36 ++++++++++++++++++++++++++++++++-
 doc/guide/files/fixes.xml       |  26 +++++++++++++++++++++++-
 3 files changed, 60 insertions(+), 46 deletions(-)

diffs (138 lines):

diff -r 49921b5551c7 -r a3cd2692e914 doc/HOWTO-destdir
--- a/doc/HOWTO-destdir Fri Aug 10 00:16:04 2007 +0000
+++ /dev/null   Thu Jan 01 00:00:00 1970 +0000
@@ -1,44 +0,0 @@
-DESTDIR support
----------------
-
-A growing number of packages support installation into a subdirectory of
-WRKDIR. This allows a package to be built, before the actual filesystem
-is touched. DESTDIR support exists in two variations:
-
-- basic DESTDIR support means that the package installation and
-packaging is still run as root.
-
-- full DESTDIR support can run the complete build, installation and
-packaging as normal user. Root privileges are only needed to add
-packages.
-
-To use the DESTDIR support, set either USE_DESTDIR=yes to use the basic
-support for packages that offer it or USE_DESTDIR=full to get the full
-support with fallback to basic support. USE_DESTDIR=full needs a
-pkg_install of 20070802. It might become the default DESTDIR support
-later.
-
-This changes the behaviour of various targets slightly. To install a
-package after building it, use package-install. package and install
-don't do that any longer. package-install can be used as DEPENDS_TARGET.
-bin-install will ask for the root password to install the package and
-fail, package-install will ask again.
-
-With basic DESTDIR support, make clean needs to be run as root.
-
-
-Adding DESTDIR support to packages
-----------------------------------
-
-- all installation operations have to be prefixed with ${DESTDIR}
-
-- automake gets this mostly right, manual rules and pre/post-install
-often not --> fix thix
-
-- if files are installed with special owner/group either use
-@owner/@group in the PLIST (prefered) or use SPECIAL_PERMS
-(discouraged). Note that @owner/@group are stic during install, keep
-this in mind.
-
-- in general, package should support UNPRIVILEGED to be able to use
-DESTDIR.
diff -r 49921b5551c7 -r a3cd2692e914 doc/guide/files/configuring.xml
--- a/doc/guide/files/configuring.xml   Fri Aug 10 00:16:04 2007 +0000
+++ b/doc/guide/files/configuring.xml   Fri Aug 10 00:51:50 2007 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: configuring.xml,v 1.27 2007/06/01 11:07:24 rillig Exp $ -->
+<!-- $NetBSD: configuring.xml,v 1.28 2007/08/10 00:51:51 wiz Exp $ -->
 
 <chapter id="configuring">
   <title>Configuring pkgsrc</title>
@@ -129,6 +129,40 @@
       </itemizedlist></para>
   </sect1>
 
+  <sect1 id="variables-affecting-installation">
+    <title>Variables affecting the installion process</title>
+
+    <para>A growing number of packages support installation into a
+    subdirectory of <varname>WRKDIR</varname>. This allows a package
+    to be built, before the actual filesystem is touched. DESTDIR
+    support exists in two variations:</para>
+    <itemizedlist>
+      <listitem><para>Basic DESTDIR support means that the package
+      installation and packaging is still run as
+      root.</para></listitem>
+      <listitem><para>Full DESTDIR support can run the complete build,
+      installation and packaging as normal user. Root privileges are
+      only needed to add packages.</para></listitem>
+    </itemizedlist>
+    <para>To use the DESTDIR support, set either
+    <varname>USE_DESTDIR=yes</varname> to use the basic support for
+    packages that offer it or <varname>USE_DESTDIR=full</varname> to
+    get the full support with fallback to basic
+    support. <varname>USE_DESTDIR=full</varname> needs <filename
+    role="pkg">pkgtools/pkg_install</filename> version 20070802 (or
+    newer). It might become the default DESTDIR support later.</para>
+    <para>DESTDIR support changes the behaviour of various targets
+    slightly. To install a package after building it, use
+    <literal>package-install</literal>. <literal>package</literal> and
+    <literal>install</literal> don't do that any
+    longer. <literal>package-install</literal> can be used as
+    <varname>DEPENDS_TARGET</varname>.  <literal>bin-install</literal>
+    will ask for the root password to install the package and fail,
+    <literal>package-install</literal> will ask again.</para>
+    <para>With basic DESTDIR support, <userinput>make
+    clean</userinput> needs to be run as root.</para>
+  </sect1>
+
 <sect1 id="conf.compiler">
 <title>Selecting and configuring the compiler</title>
 
diff -r 49921b5551c7 -r a3cd2692e914 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Fri Aug 10 00:16:04 2007 +0000
+++ b/doc/guide/files/fixes.xml Fri Aug 10 00:51:50 2007 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.87 2007/06/01 11:07:25 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.88 2007/08/10 00:51:51 wiz Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
@@ -1336,6 +1336,30 @@
     correctly.</para>
   </sect2>
 
+  <sect2 id="destdir-support">
+    <title>Adding DESTDIR support to packages</title>
+
+    <itemizedlist>
+      <listitem><para>All installation operations have to be prefixed with
+      <filename>${DESTDIR}</filename>.</para></listitem>
+
+      <listitem><para>automake gets this DESTDIR mostly right
+      automatically. Many manual rules and pre/post-install often are
+      incorrect; fix them.</para></listitem>
+
+      <listitem><para>If files are installed with special owner/group
+      either use @owner/@group in the <filename>PLIST</filename>
+      (preferred) or use <varname>SPECIAL_PERMS</varname>
+      (discouraged). Note that @owner/@group are sticky during
+      install, keep this in mind.</para></listitem>
+
+      <listitem><para>In general, packages should support
+      <varname>UNPRIVILEGED</varname> to be able to use
+      DESTDIR.</para></listitem>
+
+    </itemizedlist>
+  </sect2>
+
 
   <sect2 id="hardcoded-paths">
     <title>Packages with hardcoded paths to other interpreters</title>