Skip to contentSkip to conversation

Make documentation optional

RFC PATCH In review Michael Renzmann 3 participants 7 messages Feb 10, 2006 Kbuild

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 Make documentation optional

Hi.

The compilation of the latest qemu CVS version aborted due to a missing texi2html package. In my opinion, the build shouldn't depend on texi2html and pod2man. I suggest to make the documentation optional and warn the user if any of the necessary tools are missing.

The attached patch modifies Makefile such that the documentation will only be generated when the necessary tools are available. The installation has been fixed such that missing documentation file won't break the compilation.

Comments welcome.

Bye, Mike

CVS/Entries +13 -1
diff -urN qemu-cvs/CVS/Entries qemu-cvs-o42/CVS/Entries
@@ -87,4 +87,16 @@
 /vl.c/1.163/Wed Feb  8 22:46:31 2006//
 /vl.h/1.104/Wed Feb  8 04:42:17 2006//
 /x86_64.ld/1.1/Thu Jan  6 20:50:00 2005//
-D
+D/audio////
+D/fpu////
+D/hw////
+D/keymaps////
+D/linux-user////
+D/pc-bios////
+D/slirp////
+D/target-arm////
+D/target-i386////
+D/target-mips////
+D/target-ppc////
+D/target-sparc////
+D/tests////
CVS/Entries.Log +0 -13
diff -urN qemu-cvs/CVS/Entries.Log qemu-cvs-o42/CVS/Entries.Log
@@ -1,13 +0,0 @@
-A D/audio////
-A D/fpu////
-A D/hw////
-A D/keymaps////
-A D/linux-user////
-A D/pc-bios////
-A D/slirp////
-A D/target-arm////
-A D/target-i386////
-A D/target-mips////
-A D/target-ppc////
-A D/target-sparc////
-A D/tests////
Makefile +31 -10

70 lines not on this page · raw message

#1 lore raw

Hi again.

Quoted 1 line · Michael Renzmann

The attached patch ...

... contained some stuff that should have been ignored by diff. Sorry, revised patch attached to this mail.

Bye, Mike

Makefile +31 -10
diff -urN qemu-cvs/Makefile qemu-cvs-o42/Makefile
@@ -28,6 +28,7 @@
 # avoid old build problems by removing potentially incorrect old files
 	rm -f config.mak config.h op-i386.h opc-i386.h gen-op-i386.h op-arm.h opc-arm.h gen-op-arm.h 
 	rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS *.pod *~ */*~
+	rm -f $(DOCS)
 	$(MAKE) -C tests clean
 	for d in $(TARGET_DIRS); do \
 	$(MAKE) -C $$d $@ || exit 1 ; \
@@ -43,7 +44,7 @@
 ar      de     en-us  fi  fr-be  hr     it  lv  nl         pl  ru     th \
 common  de-ch  es     fo  fr-ca  hu     ja  mk  nl-be      pt  sl     tr
 
-install: all 
+install: all
 	mkdir -p "$(bindir)"
 	install -m 755 -s $(TOOLS) "$(bindir)"
 	mkdir -p "$(datadir)"
@@ -52,11 +53,19 @@
                        pc-bios/ppc_rom.bin pc-bios/video.x \
                        pc-bios/proll.elf \
                        pc-bios/linux_boot.bin "$(datadir)"
-	mkdir -p "$(docdir)"
-	install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"
+	if [ -f "./*.html" ]; then \
+	    mkdir -p "$(docdir)" ; \
+	    install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)" ; \
+	else \
+	    echo "INFO: skipped installation of HTML documentation" ; \
+	fi
 ifndef CONFIG_WIN32
-	mkdir -p "$(mandir)/man1"
-	install qemu.1 qemu-img.1 "$(mandir)/man1"
+	if [ -f "./*.1" ]; then \
+	    mkdir -p "$(mandir)/man1" ; \
+	    install qemu.1 qemu-img.1 "$(mandir)/man1" ; \
+	else \
+	    echo "INFO: skipped installation of man pages" ; \
+	fi
 	mkdir -p "$(datadir)/keymaps"
 	install -m 644 $(addprefix keymaps/,$(KEYMAPS)) "$(datadir)/keymaps"
 endif
@@ -78,15 +87,27 @@
 
 # documentation
 %.html: %.texi
-	texi2html -monolithic -number $<
+	if [ -n "$(shell which texi2html)" ]; then \
+	    texi2html -monolithic -number $< ; \
+	else \
+	    echo "WARNING: texi2html not found, skipped generation of" $< ; \
+	fi
 
 qemu.1: qemu-doc.texi
-	./texi2pod.pl $< qemu.pod
-	pod2man --section=1 --center=" " --release=" " qemu.pod > $@
+	if [ -n "$(shell which pod2man)" ]; then \
+		./texi2pod.pl $< qemu.pod ; \
+		pod2man --section=1 --center=" " --release=" " qemu.pod > $@ ; \
+	else \
+		echo "WARNING: pod2man not found, skipped generation of" $@ ; \
+	fi
 
 qemu-img.1: qemu-img.texi
-	./texi2pod.pl $< qemu-img.pod
-	pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@
+	if [ -n "$(shell which pod2man)" ]; then \
+		./texi2pod.pl $< qemu-img.pod ; \
+		pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@ ; \
+	else \
+		echo "WARNING: pod2man not found, skipped generation of" $@ ; \
+	fi
 
 FILE=qemu-$(shell cat VERSION)
 
#2 lore raw
Quoted 12 lines · Michael Renzmann

Hi again.

Quoted 1 line · Michael Renzmann

The attached patch ...

... contained some stuff that should have been ignored by diff. Sorry, revised patch attached to this mail.

diff -urN qemu-cvs/Makefile qemu-cvs-o42/Makefile

Makefile line 56

Quoted 5 lines
Makefile +0 -2
@@ -52,11 +53,19 @@
                       pc-bios/ppc_rom.bin pc-bios/video.x \
                       pc-bios/proll.elf \
                       pc-bios/linux_boot.bin "$(datadir)"
-	mkdir -p "$(docdir)"
-	install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"

What about just doing this

	-install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"

Makefile line 91

Quoted 7 lines
Makefile +0 -0
@@ -78,15 +87,27 @@
 
 # documentation

%.html: %.texi

Makefile +2 -1
-	texi2html -monolithic -number $<
+	if [ -n "$(shell which texi2html)" ]; then \
+	    texi2html -monolithic -number $< ; \

same here:

	-texi2html -monolithic -number $< ;

Makefile line 89

Quoted 11 lines
Makefile +6 -1
-	pod2man --section=1 --center=" " --release=" " qemu.pod > $@
+	if [ -n "$(shell which pod2man)" ]; then \
+		./texi2pod.pl $< qemu.pod ; \
+		pod2man --section=1 --center=" " --release=" " qemu.pod > $@ ; \
+	else \
+		echo "WARNING: pod2man not found, skipped generation of" $@ ; \
+	fi

qemu-img.1: qemu-img.texi

Makefile +0 -2
-	./texi2pod.pl $< qemu-img.pod
-	pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@

ditto:

	-pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@
#3 lore raw

Hi.

Quoted 2 lines · Bernhard Fischer

What about just doing this

	-install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"

That would work, but the user won't be noticed of the fact that parts of the documentation isn't generated.

Bye, Mike

#4 lore raw
Quoted 8 lines · Michael Renzmann

Hi.

Quoted 2 lines · Bernhard Fischer

What about just doing this

	-install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"

That would work, but the user won't be noticed of the fact that parts of the documentation isn't generated.

Not quite, you'll get
texi2html -monolithic etc failed
make: Error (ignored)

and the build will move on.

#5 lore raw

Hi.

Quoted 7 lines · Bernhard Fischer
Quoted 2 lines

That would work, but the user won't be noticed of the fact that parts of the documentation isn't generated.

Not quite, you'll get
texi2html -monolithic etc failed
make: Error (ignored)

and the build will move on.

Uhm... yeah, you're right. /me is a bit out of order this morning, it seems :)

Attached is the revised patch. It makes make ignore errors related to texi2html and/or pod2man are not available. In addition, documentation files are now included in the "clean" target (forgot to mention that for the first version of the patch).

Bye, Mike

Makefile +7 -6
diff -urN qemu-cvs/Makefile qemu-cvs-o42/Makefile
@@ -28,6 +28,7 @@
 # avoid old build problems by removing potentially incorrect old files
 	rm -f config.mak config.h op-i386.h opc-i386.h gen-op-i386.h op-arm.h opc-arm.h gen-op-arm.h 
 	rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS *.pod *~ */*~
+	rm -f $(DOCS)
 	$(MAKE) -C tests clean
 	for d in $(TARGET_DIRS); do \
 	$(MAKE) -C $$d $@ || exit 1 ; \
@@ -43,7 +44,7 @@
 ar      de     en-us  fi  fr-be  hr     it  lv  nl         pl  ru     th \
 common  de-ch  es     fo  fr-ca  hu     ja  mk  nl-be      pt  sl     tr
 
-install: all 
+install: all
 	mkdir -p "$(bindir)"
 	install -m 755 -s $(TOOLS) "$(bindir)"
 	mkdir -p "$(datadir)"
@@ -53,10 +54,10 @@
                        pc-bios/proll.elf \
                        pc-bios/linux_boot.bin "$(datadir)"
 	mkdir -p "$(docdir)"
-	install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"
+	-install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"
 ifndef CONFIG_WIN32
 	mkdir -p "$(mandir)/man1"
-	install qemu.1 qemu-img.1 "$(mandir)/man1"
+	-install qemu.1 qemu-img.1 "$(mandir)/man1"
 	mkdir -p "$(datadir)/keymaps"
 	install -m 644 $(addprefix keymaps/,$(KEYMAPS)) "$(datadir)/keymaps"
 endif
@@ -78,15 +79,15 @@
 
 # documentation
 %.html: %.texi
-	texi2html -monolithic -number $<
+	-texi2html -monolithic -number $<
 
 qemu.1: qemu-doc.texi
 	./texi2pod.pl $< qemu.pod
-	pod2man --section=1 --center=" " --release=" " qemu.pod > $@
+	-pod2man --section=1 --center=" " --release=" " qemu.pod > $@
 
 qemu-img.1: qemu-img.texi
 	./texi2pod.pl $< qemu-img.pod
-	pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@
+	-pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@
 
 FILE=qemu-$(shell cat VERSION)
 
#6 lore raw
In reply to Bernhard Fischer

The user still wont know the documentation has failed, or he will have to search through the build logs.

Quoted 14 lines · --- Bernhard Fischer
Quoted 8 lines · Michael Renzmann

Hi.

Quoted 2 lines · Bernhard Fischer

What about just doing this

	-install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"

That would work, but the user won't be noticed of the fact that parts of the documentation isn't generated.

Not quite, you'll get
texi2html -monolithic etc failed
make: Error (ignored)

Quoted 8 lines

and the build will move on.

_______________________________________________
Qemu-devel mailing list
[email protected]
http://lists.nongnu.org/mailman/listinfo/qemu-devel

Kind regards,
Sylvain Petreolle (aka Usurp)
--- --- --- --- --- --- --- --- --- --- --- --- --- Tired of a proprietary Windows on your computer ? Use free ReactOS instead ( http://www.reactos.org )