[debhelper-devel] [debhelper] 01/01: PROGRAMMING: Document how to write logging helpers

[Niels Thykier]

This is an automated email from the git hooks/post-receive script.

nthykier pushed a commit to branch master
in repository debhelper.

commit da3c31642941b2f9e5511c4bab9e39863fe30f87
Author: Niels Thykier <niels at thykier.net>
Date:   Sun Jul 9 08:13:53 2017 +0000

    PROGRAMMING: Document how to write logging helpers
    
    Signed-off-by: Niels Thykier <niels at thykier.net>
---
 debian/changelog |  2 ++
 dh_missing       |  3 +++
 doc/PROGRAMMING  | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 62 insertions(+)

diff --git a/debian/changelog b/debian/changelog
index 350347c..7c305ef 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -15,6 +15,8 @@ debhelper (10.6.3) UNRELEASED; urgency=medium
     files, but log what it would have done to avoid making
     dh_missing complain.  Thanks to Michael Stapelberg for
     reporting the issue and testing the fix.  (Closes: #867246)
+  * PROGRAMMING: Document how to write "logging" helpers that work
+    with dh_missing.
 
  -- Niels Thykier <niels at thykier.net>  Wed, 05 Jul 2017 15:51:48 +0000
 
diff --git a/dh_missing b/dh_missing
index f882fb8..68ccaee 100755
--- a/dh_missing
+++ b/dh_missing
@@ -164,6 +164,9 @@ if (@missing) {
 		nonquiet_print(" * ${helper}: " . join(', ', @results));
 	}
 	nonquiet_print("If the missing files are installed by another tool, please file a bug against it.");
+	nonquiet_print('When filing the report, if the tool is not part of debhelper itself, please reference the');
+	nonquiet_print('"Logging helpers and dh_missing" section from the "PROGRAMMING" guide for debhelper (10.6.3+).');
+	nonquiet_print('  (in the debhelper package: /usr/share/doc/debhelper/PROGRAMMING.gz)');
 	nonquiet_print("Be sure to test with dpkg-buildpackage -A/-B as the results may vary when only a subset is built");
 	nonquiet_print("For a short-term work-around: Add the files to debian/not-installed");
 	if ($dh{FAIL_MISSING}) {
diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index a6b47fe..fa87fc5 100644
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -433,6 +433,63 @@ remove_command_options($command, $opt1, $opt2, ...)
 	Remove $opt1, $opt2 etc. from the list of additional options which
 	dh passes when running the specified $command.
 
+Logging helpers and dh_missing:
+-------------------------------
+
+Since debhelper 10.3, debhelper has had a helper called "dh_missing".  It
+takes over the "--list-missing" and "--fail-missing" options from dh_install
+and as the advantage that it can "see" what other helpers have installed.
+
+Under the hood, this works by the helpers logging the source files
+they (would) install to a hidden log file.  When dh_missing is called,
+it reads all these log files to determine which files have would been
+installed and compare them to what is present.
+
+If you are writing a helper that need to integrate with dh_missing,
+here is what you do:
+
+Dh_Lib-based helpers:
+~~~~~~~~~~~~~~~~~~~~~
+
+ * Replace "@{$dh{DOPACKAGES}}" with "getpackages()" and use
+   "process_pkg($package)" to determine if the helper should actually
+   install anything.
+ * Call "log_installed_files" once per package (even once that are not to
+   be acted on) with a list of source files that would be installed.
+   - You can list entire directories even if there are files under
+     it that are ignored.
+   - Please call "log_installed_files" /even if/ the list is empty for that
+     packages.  This enables dh_missing to see that the helper has been run
+     and nothing should be installed for that package.
+ * If your helper has a PROMISE, it must use "pkgfile-logged(<file>)"
+   for its config files.  (See #867246)
+   - CAVEAT: This requires a dependency on "debhelper (>= 10.2.5)".  Prior
+     to that version, debhelper will wrongly optimize your helper out.
+ * Consider using dh_installman or dh_installexamples as examples.
+
+Other helpers:
+~~~~~~~~~~~~~~
+
+ * The helper must compile a list of files it would have installed for
+   each package (even packages that are not acted on).  The file list
+   should be relative to the source package root (e.g.
+   "debian/tmp/usr/bin/bar").
+    - This list can also contain directories.  They will be flagged as
+      installed along with their content (recursively).
+ * The helper must append to the file (create it if missing):
+     debian/.debhelper/generated/${package}/installed-by-${HELPER_NAME}
+   - Example: debian/.debhelper/generated/lintian/installed-by-dh_install
+   - The file should be created even if it is empty.  This enables dh_missing
+     to see that the helper has been run and nothing would be installed for
+     that package.
+ * Please append to the file if it exists as the helper may be called multiple
+   times (once with -a and once with -i).  It is completely fine if this leaves
+   duplicate entries as dh_missing will deduplicate these.
+ * If your helper has a PROMISE, it must use "pkgfile-logged(<file>)"
+   for its config files.  (See #867246)
+   - CAVEAT: This requires a dependency on "debhelper (>= 10.2.5)".  Prior
+     to that version, debhelper will wrongly optimize your helper out.
+
 Buildsystem Classes:
 -------------------
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debhelper/debhelper.git