Add a description of how to use and extend DESTDIR support.

This should be merged into the guide by doc people.

1 files changed, 44 insertions, 0 deletions

diff --git a/doc/HOWTO-destdir b/doc/HOWTO-destdir
new file mode 100644
index 00000000000..aadda10b524
--- /dev/null
+++ b/doc/HOWTO-destdir
@@ -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.