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

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

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