Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Andrea Pappacoda]

Hi Helmut, I've added the dh-sequence-doxygen sequence and submitted it 
as a [Salsa MR]; it has been simpler than expected, as the doxygen.pm 
addon was already there. One issue I noticed though is that when 
building a package using dh_doxygen with `dpkg-buildpackage 
--build=binary` nothing happens, and I get the following warning:


   dh_doxygen: warning: No packages to build. Possible architecture 
mismatch: amd64, want: all any


Everything works as expected when using `--build=all`.

This is probably not directly related to the new dh-sequence-doxygen 
package, as it also happens when building [cubeb], a package I 
maintain; as you have some experience with cross builds, profiles, etc, 
I hope you might have an idea about what's going on :)


[Salsa MR]: https://salsa.debian.org/debian/doxygen/-/merge_requests/8
[cubeb]: 
https://salsa.debian.org/debian/cubeb/-/blob/7a17dcc60f413187b1e39c35bafd21d6bfaf3978/debian/rules#L38-43


--
OpenPGP key: 66DE F152 8299 0C21 99EF  A801 A8A1 28A8 AB1C EE49

Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Andrea Pappacoda]

Il giorno dom 25 set 2022 alle 15:10:40 +02:00:00, Helmut Grohne 
 ha scritto:

I fully agree that there now should be a sequence addon.
Build-Depends-Indep: dh-sequence-doxygen seems great. Will you do it?


Great! I honestly don't know where to start, but I'll look into it :)

Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Helmut Grohne]

Hi,

On Sun, Sep 25, 2022 at 01:13:25PM +0200, Andrea Pappacoda wrote:
> On Sun, 4 Sep 2016 14:16:02 +0200 Helmut Grohne  wrote:
> > Documentation generators such as doxygen or sphinxdoc typically create
> > architecture independent packages. Thus the required tools should reside
> > in Build-Depends-Indep. Having them there means that they cannot easily
> > be used as sequence addons (there is no dh --with-indep).
> 
> Hi Helmut, as debhelper now supports specifying sequence addons by adding a
> dh-sequence-name in Build-Depends{,-Arch,-Indep}, maybe this can be
> reconsidered?

Yes of course. I've written that at a time, when dh-sequence-name was
not a thing. I think part of the reason we invented dh-sequence-name was
me bugging Niels about this. Thus my earlier argument has become
invalid. I fully agree that there now should be a sequence addon.
Build-Depends-Indep: dh-sequence-doxygen seems great. Will you do it?

Helmut

Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Andrea Pappacoda]

On Sun, 4 Sep 2016 14:16:02 +0200 Helmut Grohne  
wrote:
> Documentation generators such as doxygen or sphinxdoc typically 
create
> architecture independent packages. Thus the required tools should 
reside
> in Build-Depends-Indep. Having them there means that they cannot 
easily

> be used as sequence addons (there is no dh --with-indep).

Hi Helmut, as debhelper now supports specifying sequence addons by 
adding a dh-sequence-name in Build-Depends{,-Arch,-Indep}, maybe this 
can be reconsidered?

Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Anders Kaseorg]

On Sun, 4 Sep 2016, Helmut Grohne wrote:
> Trying to use it anyway results in "beauty" such as:
> 
> https://bugs.debian.org/cgi-bin/bugreport.cgi?att=1;bug=807848;filename=jansson_2.7-3.1.debdiff;msg=29
>
> I believe that using the sequence addon correctly is simply too hard to 
> be worth it. The sphinxdoc addon is causing work on my end (#818115). 
> Thus I object to having it in the first place.

That makes sense.

I think the jansson fix could have been marginally less ugly, but still 
not great:

  %-arch:
  dh $@ --with=autoreconf
  %:
  dh $@ --with=autoreconf,sphinxdoc

I submitted https://bugs.debian.org/836699 for adding dh --with-indep.  
Perhaps this can be reconsidered if that happens.

Anders

Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Helmut Grohne]

Control: tags -1 - patch

I'm sorry for having left this unanswered for too long.

On Sun, Sep 04, 2016 at 05:31:18AM -0400, Anders Kaseorg wrote:
> Please consider the following fix, which also properly installs dh_doxygen 
> as a Debhelper sequence addon so that it can be invoked via ???dh $@ --with 
> doxygen???.

I considered these semantics when I added dh_doxygen to the doxygen
package, but concluded that it was a bad idea. Here is my rationale:

At that time, I was following dh_sphinxdoc which was also failing loudly
in this way (but has changed since). So the behaviour was consistent
with other tools at that time.

That has now changed and the behaviour change in dh_sphinxdoc is now
causing harm which I do not want to replicate for doxygen. Documentation
generators such as doxygen or sphinxdoc typically create architecture
independent packages. Thus the required tools should reside in
Build-Depends-Indep. Having them there means that they cannot easily be
used as sequence addons (there is no dh --with-indep). Trying to use it
anyway results in "beauty" such as:

https://bugs.debian.org/cgi-bin/bugreport.cgi?att=1;bug=807848;filename=jansson_2.7-3.1.debdiff;msg=29

I believe that using the sequence addon correctly is simply too hard to
be worth it. The sphinxdoc addon is causing work on my end (#818115).
Thus I object to having it in the first place. When there is no addon,
you can simply call dh_doxygen only when it is actually needed and then
the check really makes sense. If you only need it during indep builds, I
recommend using an override_*-indep target for doing so. Alternatively,
"ifneq (,$(filter foo-doc,$(shell dh_listpackages)))" can be used.

So given the above rationale, I object to the approach taken.
Nevertheless, I welcome more arguments for changing the current
behaviour. I understand that the current situation is not perfect, but I
think that the sequence addon will only move the pain. So simply put, my
requirement for this change is that the simplest way to use it should
not cause maintainers to move doxygen from Build-Depends-Indep to
Build-Depends.

I hope that this makes sense to you despite the work you put into a
patch.

> diff -Nru doxygen-1.8.11/debian/doxygen.install 
> doxygen-1.8.11/debian/doxygen.install
> --- doxygen-1.8.11/debian/doxygen.install 2015-04-29 09:22:08.0 
> -0400
> +++ doxygen-1.8.11/debian/doxygen.install 2016-09-04 05:06:57.0 
> -0400
> @@ -1 +1,2 @@
>  debian/dh-doxygen/dh_doxygen /usr/bin
> +debian/dh-doxygen/doxygen.pm /usr/share/perl5/Debian/Debhelper/Sequence

Removing the patch tag, because
 * the patch is incomplete as it lacks doxygen.pm and
 * I consider the addition of the sequence addon harmful as is.

Helmut

Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Anders Kaseorg]

Control: tags -1 + patch

Please consider the following fix, which also properly installs dh_doxygen 
as a Debhelper sequence addon so that it can be invoked via ‘dh $@ --with 
doxygen’.

Anders

diff -Nru doxygen-1.8.11/debian/changelog doxygen-1.8.11/debian/changelog
--- doxygen-1.8.11/debian/changelog 2016-06-24 10:22:04.0 -0400
+++ doxygen-1.8.11/debian/changelog 2016-09-04 05:06:57.0 -0400
@@ -1,3 +1,12 @@
+doxygen (1.8.11-4) UNRELEASED; urgency=medium
+
+  * dh_doxygen: Do not fail on packages with no doxygen documentation.
+(Closes: #799543)
+  * Install dh_doxygen as a Debhelper sequence addon so that it can be
+invoked via ‘dh $@ --with doxygen’.
+
+ -- Anders Kaseorg   Sun, 04 Sep 2016 05:06:57 -0400
+
 doxygen (1.8.11-3) unstable; urgency=medium
 
   * Applied upstream commit 9a2c7bbfb0c53b4532db7280e6804c7ce76d70a3:
diff -Nru doxygen-1.8.11/debian/dh-doxygen/dh_doxygen 
doxygen-1.8.11/debian/dh-doxygen/dh_doxygen
--- doxygen-1.8.11/debian/dh-doxygen/dh_doxygen 2015-04-29 09:22:08.0 
-0400
+++ doxygen-1.8.11/debian/dh-doxygen/dh_doxygen 2016-09-04 05:06:57.0 
-0400
@@ -138,11 +138,9 @@
 }, $pkgpath);
 }
 }
-if ($done == 0)
+if (defined $path && $done == 0)
 {
-my $message = 'Doxygen documentation not found';
-$message .= " at $path" if defined $path;
-error($message);
+error("Doxygen documentation not found at $path");
 }
 }
 
diff -Nru doxygen-1.8.11/debian/doxygen.install 
doxygen-1.8.11/debian/doxygen.install
--- doxygen-1.8.11/debian/doxygen.install   2015-04-29 09:22:08.0 
-0400
+++ doxygen-1.8.11/debian/doxygen.install   2016-09-04 05:06:57.0 
-0400
@@ -1 +1,2 @@
 debian/dh-doxygen/dh_doxygen /usr/bin
+debian/dh-doxygen/doxygen.pm /usr/share/perl5/Debian/Debhelper/Sequence

Bug#799543: dh_doxygen: fails if no docs found, even in binary-only builds

[Aaron M. Ucko]

Package: doxygen
Version: 1.8.9.1-5
Severity: important

Builds of signond covering only its architecture-dependent binary
packages (as on the autobuilders) have been failing:

  dh_doxygen
  dh_doxygen: Doxygen documentation not found
  make[2]: *** [override_dh_install] Error 2

I presume this error represents an intended sanity check, which could
be helpful in some circumstances.  However, the typical dh_*
convention is to treat having nothing to do as a (trivial) success
rather than a failure.  This convention is particularly appropriate
here, because many source packages (signond included) split
documentation into architecture-independent binary packages that not
all builds cover.

As such, please either downgrade this error to a warning or suppress
it altogether, at least in the case of builds covering only a subset
of possible binary packages.

See also sphinx-common bug https://bugs.debian.org/745690.

Thanks!