dh: Skips running commands that it can tell do nothing.

This is determined by the presence of special PROMISE directives within
commands that provide a high-level description of the command.

Note that when dh is passed additional debhelper options, it cannot tell if
these change the behavior of commands, and so it stops skipping any
commands.

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index e1440c91..e7b6e355 100644
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -181,6 +181,16 @@ pkgfile($package, $basename)
 	package. The convention is that the files are named
 	debian/package.filename, and debian/filename is also allowable for
 	the $dh{MAINPACKAGE}. If the file does not exist, nothing is returned.
+
+	If the *entire* behavior of a command, when run without any special
+	options, is determined by the existence of 1 or more pkgfiles,
+	or by the existence of a file or directory in a location in the
+	tmpdir, it can be marked as such, which allows dh to automatically
+	skip running it. This is done by inserting a special comment,
+	of the form:
+
+	# PROMISE: DH NOOP WITHOUT pkgfilea pkgfileb tmp(need/this)
+
 pkgext($package)
 	Pass this command the name of a binary package, and it will return
 	the name to prefix to files in debian/ for this package. For the