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
