[pkgsrc/trunk]: pkgsrc/doc Add a description of how to use and extend DESTDIR...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/00c0ad15fb3d
branches:  trunk
changeset: 531974:00c0ad15fb3d
user:      joerg <joerg%pkgsrc.org@localhost>
date:      Thu Aug 09 13:54:28 2007 +0000

description:
Add a description of how to use and extend DESTDIR support.
This should be merged into the guide by doc people.

diffstat:

 doc/HOWTO-destdir |  44 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 44 insertions(+), 0 deletions(-)

diffs (48 lines):

diff -r b7a4e4e9e264 -r 00c0ad15fb3d doc/HOWTO-destdir
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/HOWTO-destdir Thu Aug 09 13:54:28 2007 +0000
@@ -0,0 +1,44 @@
+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.