Skip to contentSkip to conversation

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

PATCH In review Maximilian Engelhardt 2 participants 5 messages Jan 10, 2025 – Jan 17, 2025

lore
Share & tools
lore
#0 lore raw

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

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(-)
Signature · 1 line
2.39.5
#1 lore raw

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

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.

---
 docs/Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
docs/Makefile +1 -1
index b30cc619f8..9f8ba8acd9 100644
@@ -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
Signature · 1 line
2.39.5
#3 lore raw
In reply to Maximilian Engelhardt
Quoted 23 lines · 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.

Quoted 4 lines

[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

Acked-by on v1 1/1
#2 lore raw

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

In reply to Maximilian Engelhardt
Quoted 9 lines · 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

Quoted 5 lines

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.

#4 lore raw
In reply to Andrew Cooper
Quoted 9 lines · 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