16.4 DESTDIR: Support for Staged Installs

DESTDIR is a variable prepended to each installed target file, like this:

$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a

The DESTDIR variable is specified by the user on the make command line as an absolute file name. For example:

make DESTDIR=/tmp/stage install

DESTDIR should be supported only in the install* and uninstall* targets, as those are the only targets where it is useful.

If your installation step would normally install /usr/local/bin/foo and /usr/local/lib/libfoo.a, then an installation invoked as in the example above would install /tmp/stage/usr/local/bin/foo and /tmp/stage/usr/local/lib/libfoo.a instead.

Prepending the variable DESTDIR to each target in this way provides for staged installs, where the installed files are not placed directly into their expected location but are instead copied into a temporary location (DESTDIR). However, installed files maintain their relative directory structure and any embedded file names will not be modified.

You should not set the value of DESTDIR in your Makefile at all; then the files are installed into their expected locations by default. Also, specifying DESTDIR should not change the operation of the software in any way, so its value should not be included in any file contents.

DESTDIR support is commonly used in package creation. It is also helpful to users who want to understand what a given package will install where, and to allow users who don’t normally have permissions to install into protected areas to build and install before gaining those permissions. Finally, it can be useful with tools such as stow, where code is installed in one place but made to appear to be installed somewhere else using symbolic links or special mount operations. So, we strongly recommend GNU packages support DESTDIR, though it is not an absolute requirement.