Move DESTDIR documentation to guide.

2 files changed, 60 insertions, 2 deletions

diff --git a/doc/guide/files/configuring.xml b/doc/guide/files/configuring.xml
index e7da55ff679..b4ebf9fa9d9 100644
--- a/doc/guide/files/configuring.xml
+++ b/doc/guide/files/configuring.xml
@@ -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 @@ works.</para>
       </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 --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index fd54bf2ed07..cfc08860d03 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -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 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2
     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>