[XEN PATCH 0/1] Bug: Hyperlinks in generated documentation may point to the wrong architecture

[XEN PATCH 0/1] Bug: Hyperlinks in generated documentation may point to the wrong architecture

[Maximilian Engelhardt]

As suggested by Andrew Cooper in [1], I formally submit this patch for
fixing that documentation hyperlinks may point to the wrong
architecture. This fix also makes building the documentation
reproducible in Debian.

With this patch applied, I still get the following:

/usr/bin/perl -w /build/reproducible-path/xen-4.19.1/docs/xen-headers -O html/hypercall/ppc \
	-T 'arch-ppc - Xen public headers' \
	-X arch-arm -X arch-riscv -X arch-x86_32 -X arch-x86_64 \
	-X xen-arm -X xen-riscv -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/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:55
include/public/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:61
include/public/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:55
include/public/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:61

This seems to happen due to multiple "typedef uint64_t xen_ulong_t;"
in xen/include/public/arch-ppc.h (albeit in different if(n)def blocks).
It does not cause any problems for us at the moment, but probably should
still be addressed somehow.

[1] https://lists.xen.org/archives/html/xen-devel/2025-01/msg00324.html

Maximilian Engelhardt (1):
  docs/Makefile: Add ppc and riscv to DOC_ARCHES

 docs/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

-- 
2.39.5

[XEN PATCH 1/1] docs/Makefile: Add ppc and riscv to DOC_ARCHES

[Maximilian Engelhardt]

Not having ppc and riscv included in DOC_ARCHES causes "multiple
definitions of ..." message on documentation build, similar to the
example shown below:

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

It can also make the generated html documentation link to the header
files of another architecture. This is additionally a problem as it can
randomly make the documentation build non-reproducible.

Signed-off-by: Maximilian Engelhardt <maxi@daemonizer.de>
---
 docs/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/Makefile b/docs/Makefile
index b30cc619f8..9f8ba8acd9 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -5,7 +5,7 @@ include $(XEN_ROOT)/Config.mk
 VERSION		:= $(shell $(MAKE) -C $(XEN_ROOT)/xen --no-print-directory xenversion)
 DATE		:= $(shell date +%Y-%m-%d)
 
-DOC_ARCHES      := arm x86_32 x86_64
+DOC_ARCHES      := arm ppc riscv x86_32 x86_64
 MAN_SECTIONS    := 1 5 7 8
 
 # Documentation sources to build
-- 
2.39.5

Re: [XEN PATCH 0/1] Bug: Hyperlinks in generated documentation may point to the wrong architecture

[Andrew Cooper]

On 10/01/2025 9:19 pm, Maximilian Engelhardt wrote:
> As suggested by Andrew Cooper in [1], I formally submit this patch for
> fixing that documentation hyperlinks may point to the wrong
> architecture. This fix also makes building the documentation
> reproducible in Debian.
>
> With this patch applied, I still get the following:
>
> /usr/bin/perl -w /build/reproducible-path/xen-4.19.1/docs/xen-headers -O html/hypercall/ppc \
> 	-T 'arch-ppc - Xen public headers' \
> 	-X arch-arm -X arch-riscv -X arch-x86_32 -X arch-x86_64 \
> 	-X xen-arm -X xen-riscv -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/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:55
> include/public/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:61
> include/public/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:55
> include/public/hvm/dm_op.h:476: multiple definitions of Typedef xen_ulong_t: include/public/arch-ppc.h:61
>
> This seems to happen due to multiple "typedef uint64_t xen_ulong_t;"
> in xen/include/public/arch-ppc.h (albeit in different if(n)def blocks).
> It does not cause any problems for us at the moment, but probably should
> still be addressed somehow.
>
> [1] https://lists.xen.org/archives/html/xen-devel/2025-01/msg00324.html
>
> Maximilian Engelhardt (1):
>   docs/Makefile: Add ppc and riscv to DOC_ARCHES

Thanks for the patch.  I'll commit it in due course.

As an aside though, is there anything we could sensibly do in our own CI
(Gitlab) to not regress this?

https://salsa.debian.org/reproducible-builds/reprotest looks like it
might be good start, but I've never really played in this area before. 
Would this be suitable, or do you have any other suggestion?

~Andrew

Re: [XEN PATCH 1/1] docs/Makefile: Add ppc and riscv to DOC_ARCHES

[Andrew Cooper]

On 10/01/2025 9:19 pm, Maximilian Engelhardt wrote:
> Not having ppc and riscv included in DOC_ARCHES causes "multiple
> definitions of ..." message on documentation build, similar to the
> example shown below:
>
> 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
>
> It can also make the generated html documentation link to the header
> files of another architecture. This is additionally a problem as it can
> randomly make the documentation build non-reproducible.
>
> Signed-off-by: Maximilian Engelhardt <maxi@daemonizer.de>

Acked-by: Andrew Cooper <andrew.cooper3@citrix.com>

Re: [XEN PATCH 0/1] Bug: Hyperlinks in generated documentation may point to the wrong architecture

[Maximilian Engelhardt]

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

On Freitag, 10. Januar 2025 22:32:06 CET Andrew Cooper wrote:
> [...]
> Thanks for the patch.  I'll commit it in due course.
> 
> As an aside though, is there anything we could sensibly do in our own CI
> (Gitlab) to not regress this?
> 
> https://salsa.debian.org/reproducible-builds/reprotest looks like it
> might be good start, but I've never really played in this area before. 
> Would this be suitable, or do you have any other suggestion?

Hi Andrew,

thanks for merging all my patches. Having some upstream xen testing for 
reproducible builds would indeed be a good thing to have.

Reprotest is the tool the salsa CI currently runs as one step and I also have 
been using locally for testing. Salsa is the Debian gitlab instance and there 
is a CI pipeline provided for testing various Debian packaging related things, 
including reproducibility of the Debian package. We use this pipeline for 
testing our Debian xen package.
There is also the reproducible-builds project which among other things looks 
at being able to reproduce the whole Debian archive [1], but as far as i know 
they are using their own tooling for testing.

So to answer your question, I would say reprotest is a good tool for testing 
for reproducibility issues and I don't know any better alternative at the 
moment. There might be some issues e.g. faketime not working as intended in 
certain situations, but there is always the option to configure or disable a 
certain variation if it causes problems.

Maxi

[1] https://tests.reproducible-builds.org/debian/reproducible.html


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