Bug: Hyperlinks in generated documentation may point to the wrong architecture

Bug: Hyperlinks in generated documentation may point to the wrong architecture

[Maximilian Engelhardt]

[-- Attachment #1: Type: text/plain, Size: 3342 bytes --]

Hello,

during working on packaging Xen in Debian I noticed the documentation becomes 
non-reproducible as hyperlinks may point to the wrong architecture.

Here an example as diff showing the problem:

/usr/share/doc/xen/html/hypercall/arm/include,public,arch-arm.h.html
@@ -313,15 +313,15 @@
     uint64_t sctlr;
     uint64_t ttbcr, ttbr0, ttbr1;
 };
 typedef <a href="include,public,arch-arm.h.html#Struct_vcpu_guest_context">struct vcpu_guest_context</a> <a  name="Typedef_vcpu_guest_context_t"><strong>vcpu_guest_context_t</strong></a>;
 DEFINE_XEN_GUEST_HANDLE(<a href="include,public,arch-arm.h.html#Struct_vcpu_guest_context">vcpu_guest_context_t</a>);
 
 /*
- * <a href="include,public,arch-arm.h.html#Struct_xen_arch_domainconfig">struct xen_arch_domainconfig</a>'s ABI is covered by
+ * <a href="include,public,arch-ppc.h.html#Struct_xen_arch_domainconfig">struct xen_arch_domainconfig</a>'s ABI is covered by
  * XEN_DOMCTL_INTERFACE_VERSION.
  */
 #define XEN_DOMCTL_CONFIG_GIC_NATIVE    0
 #define XEN_DOMCTL_CONFIG_GIC_V2        1
 #define XEN_DOMCTL_CONFIG_GIC_V3        2
 
 #define XEN_DOMCTL_CONFIG_TEE_NONE      0


As can be seen, the hyperlink in include,public,arch-arm.h.html points to 
include,public,arch-ppc.h.html while it should point to include,public,arch-
arm.h.html.
A similar problem can be found in many more places and files.

Corresponding to the problem described above, while building the documentation 
many messages similar to the last lines below can be seen in the build log:

/usr/bin/perl -w /build/reproducible-path/xen-4.19.1/docs/xen-headers -O html/hypercall/arm \
        -T 'arch-arm - Xen public headers' \
        -X arch-x86_32 -X arch-x86_64 \
        -X xen-x86_32 -X xen-x86_64 \
        -X arch-x86 \
        /build/reproducible-path/xen-4.19.1/docs/../xen include/public include/xen/errno.h
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-arm.h:300
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-ppc.h:85
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-arm.h:300
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-ppc.h:85
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-ppc.h:90
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-arm.h:305
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-ppc.h:90
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-arm.h:305
[...]


In Debian we worked around the problem for now by adding ppc and riscv to 
DOC_ARCHES in docs/Makefile as can be seen in [1]. This solves all the 
described problems and makes the build reproducible again. I assume another 
possible fix would be adding suitable ignore switches for ppc and riscv.

I did not send this as a patch as I'm not sure what the preferred upstream 
solution to this problem is, but can formally submit our fix as a patch if 
that's desired.

Thanks,
Maxi

[1] https://salsa.debian.org/xen-team/debian-xen/-/commit/d852c48d0df5c6ceba42d20652d1f9a05ad8989e 

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Bug: Hyperlinks in generated documentation may point to the wrong architecture

[Andrew Cooper]

On 30/12/2024 8:56 pm, Maximilian Engelhardt wrote:
> Hello,
>
> during working on packaging Xen in Debian I noticed the documentation becomes 
> non-reproducible as hyperlinks may point to the wrong architecture.
>
> Here an example as diff showing the problem:
>
> /usr/share/doc/xen/html/hypercall/arm/include,public,arch-arm.h.html
> @@ -313,15 +313,15 @@
>      uint64_t sctlr;
>      uint64_t ttbcr, ttbr0, ttbr1;
>  };
>  typedef <a href="include,public,arch-arm.h.html#Struct_vcpu_guest_context">struct vcpu_guest_context</a> <a  name="Typedef_vcpu_guest_context_t"><strong>vcpu_guest_context_t</strong></a>;
>  DEFINE_XEN_GUEST_HANDLE(<a href="include,public,arch-arm.h.html#Struct_vcpu_guest_context">vcpu_guest_context_t</a>);
>  
>  /*
> - * <a href="include,public,arch-arm.h.html#Struct_xen_arch_domainconfig">struct xen_arch_domainconfig</a>'s ABI is covered by
> + * <a href="include,public,arch-ppc.h.html#Struct_xen_arch_domainconfig">struct xen_arch_domainconfig</a>'s ABI is covered by
>   * XEN_DOMCTL_INTERFACE_VERSION.
>   */
>  #define XEN_DOMCTL_CONFIG_GIC_NATIVE    0
>  #define XEN_DOMCTL_CONFIG_GIC_V2        1
>  #define XEN_DOMCTL_CONFIG_GIC_V3        2
>  
>  #define XEN_DOMCTL_CONFIG_TEE_NONE      0
>
>
> As can be seen, the hyperlink in include,public,arch-arm.h.html points to 
> include,public,arch-ppc.h.html while it should point to include,public,arch-
> arm.h.html.
> A similar problem can be found in many more places and files.
>
> Corresponding to the problem described above, while building the documentation 
> many messages similar to the last lines below can be seen in the build log:
>
> /usr/bin/perl -w /build/reproducible-path/xen-4.19.1/docs/xen-headers -O html/hypercall/arm \
>         -T 'arch-arm - Xen public headers' \
>         -X arch-x86_32 -X arch-x86_64 \
>         -X xen-x86_32 -X xen-x86_64 \
>         -X arch-x86 \
>         /build/reproducible-path/xen-4.19.1/docs/../xen include/public include/xen/errno.h
> include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-arm.h:300
> include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-ppc.h:85
> include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-arm.h:300
> include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-ppc.h:85
> include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-ppc.h:90
> include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-arm.h:305
> include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-ppc.h:90
> include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-arm.h:305
> [...]
>
>
> In Debian we worked around the problem for now by adding ppc and riscv to 
> DOC_ARCHES in docs/Makefile as can be seen in [1]. This solves all the 
> described problems and makes the build reproducible again. I assume another 
> possible fix would be adding suitable ignore switches for ppc and riscv.
>
> I did not send this as a patch as I'm not sure what the preferred upstream 
> solution to this problem is, but can formally submit our fix as a patch if 
> that's desired.
>
> Thanks,
> Maxi
>
> [1] https://salsa.debian.org/xen-team/debian-xen/-/commit/d852c48d0df5c6ceba42d20652d1f9a05ad8989e 

This is a giant not-invented-here mess which needs filing in /dev/null.

The fact that you're the first to notice the incorrect linking (and only
via reproducible-build tooling) shows how many people read these docs.

I'm happy with that minimal fix, and it ought to be backported.  Please
submit it formally.

~Andrew