Update documentation and changelog to cover new sequence/addon features

Signed-off-by: Niels Thykier <niels@thykier.net>

3 files changed, 47 insertions, 6 deletions

diff --git a/debian/changelog b/debian/changelog
index b9560aec..f3939ce0 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -24,6 +24,17 @@ debhelper (12.5) UNRELEASED; urgency=medium
     exclude "udeb:" lines for libraries omitted from the udeb.  At the
     same time, verbosely fail if the udeb contains a library not present
     in the deb (overridable with --add-udeb).  (Closes: #934889)
+  * dh: Support making "dh-sequence-ADDON" Build-Depends relation
+    conditonal on build-profiles (etc.).  If the relation is ignored due
+    to the current build-profiles (etc.), then addon is silently skipped.
+  * dh: Support running addons in "arch-only" or "indep-only" mode by
+    adding "dh-sequence-ADDON" in Build-Depends-Arch or
+    Build-Depends-Indep (respectively).  Not all addons support this and
+    will trigger an error at load time.  Addon providers should ensure
+    that their package provde "dh-sequence-ADDON" and review the
+    doc/PROGRAMMING document (in the debhelper source) if they are
+    considering to make their addon compatible with these requirements.
+    (Closes: #836699)
 
   [ Frank Schaefer ]
   * dh_installmodules: Also lok for compressed kernel modules
diff --git a/dh b/dh
index f6f9ad7e..6c41d24e 100755
--- a/dh
+++ b/dh
@@ -62,12 +62,25 @@ the sequence addon interface.
 A B<Build-Depends> relation on the package B<dh-sequence->I<addon>
 implies a B<--with> I<addon>. This avoids the need for an explicit
 B<--with> in F<debian/rules> that only duplicates what is already
-declared via the build dependencies in F<debian/control>.  Note that
-only relations in the B<Build-Depends> field are considered
-(i.e. B<Build-Depends-Indep> and B<Build-Depends-Arch> are
-deliberately unsupported).  Please keep in mind that B<dh> insists on
-"simple" relations (e.g. a relation like "B<dh-sequence->I<addon> |
-B<some-other-pkg>" will I<not> imply B<--with> I<addon>).
+declared via the build dependencies in F<debian/control>.  The
+relation can (since 12.5) be made optional via e.g.
+build-profiles.  This enables you to easily disable an addon that
+is only useful with certain profiles (e.g. to facilitate
+bootstraping).
+
+Since debhelper 12.5, addons can also be activated in B<indep>-only
+mode (via B<Build-Depends-Indep>) or B<arch>-only mode (via
+B<Build-Depends-Arch>). Such addons are only active in the particular
+sequence (e.g. B<binary-indep>) which simplifies dependency
+management for cross-builds.
+
+Please note that addons activated via B<Build-Depends-Indep> or
+B<Build-Depends-Arch> are subject to additional limitations to
+ensure the result is deterministic even when the addon is
+unavailable (e.g. during clean).  This implies that some addons
+are incompatible with these restrictions and can only be used via
+B<Build-Depends> (or manually via F<debian/rules>).  Currently,
+such addons can only add commands to sequences.
 
 =item B<--without> I<addon>
 
diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index 893b87fc..ce13c53a 100644
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -431,30 +431,47 @@ calling some functions from Dh_Lib:
 insert_before($existing_command, $new_command)
 	Insert $new_command in sequences before $existing_command
 
+	Compatible with "arch-only"/"indep-only" modes if the command
+	appears only in a compatible sequence.
+
 insert_after($existing_command, $new_command)
 	Insert $new_command in sequences after $existing_command
 
+	Compatible with "arch-only"/"indep-only" modes if the command
+	appears only in a compatible sequence.
+
 remove_command($existing_command)
 	Remove $existing_command from the list of commands to run
 	in all sequences.
 
+	Cannot be used in "arch-only"/"indep-only" mode.
+
 add_command($new_command, $sequence)
 	Add $new_command to the beginning of the specified sequence.
 	If the sequence does not exist, it will be created.
 
+	Compatible with "arch-only"/"indep-only" modes if $sequence
+	is an "-arch" or "-indep" sequence (respectively).
+
 add_command_options($command, $opt1, $opt2, ...)
 	Append $opt1, $opt2 etc. to the list of additional options which
 	dh passes when running the specified $command. These options are
 	not relayed to debhelper commands called via $command override.
 
+	Cannot be used in "arch-only"/"indep-only" mode.
+
 remove_command_options($command)
 	Clear all additional $command options previously added with
 	add_command_options().
 
+	Cannot be used in "arch-only"/"indep-only" mode.
+
 remove_command_options($command, $opt1, $opt2, ...)
 	Remove $opt1, $opt2 etc. from the list of additional options which
 	dh passes when running the specified $command.
 
+	Cannot be used in "arch-only"/"indep-only" mode.
+
 Logging helpers and dh_missing:
 -------------------------------