GNOME Bugzilla – Bug 674163
html-build.stamp rule broken for out-of-tree builds with absolute paths
Last modified: 2018-05-08 15:23:15 UTC
Bug-Debian: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=656803 When gtk+ is built with srcdir!=builddir, the resulting gtk-doc documentation is incomplete. It misses a lot of png files [1] and has broken XINCLUDE references. For gail and gdk the list of files being installed and the ones available in docs/*/html is identical. For gtk3, the diff is --- files-gtk3.orig 2012-04-16 01:23:36.370768359 +0200 +++ files-gtk.installed 2012-04-16 01:24:44.670770313 +0200 @@ -1,6 +1,4 @@ -aboutdialog.png AbstractObjects.html -accel-label.png Actions.html annotation-glossary.html api-index-3-0.html @@ -8,24 +6,9 @@ api-index-3-4.html api-index-deprecated.html api-index-full.html -appchooserbutton.png -appchooserdialog.png ApplicationChoosing.html -application-exit.png Application.html -arrows.png -assistant.png -background.png -bloatpad-gnome.png -bloatpad-osx.png -bloatpad-xfce.png -border1.png -border2.png -border3.png -box-expand.png -box-packing.png Builder.html -button.png ButtonWidgets.html ch02.html ch03.html @@ -34,97 +17,11 @@ ch28s02.html ch28s03.html chap-drawing-model.html -check-button.png checklist-gdkeventexpose-region.html checklist-modifiers.html checklist-named-icons.html -checks.png -color-button.png -colorchooser.png -colorsel.png -combo-box-entry.png -combo-box.png -dialog-error.png -dialog-information.png -dialog-password.png -dialog-question.png -dialog-warning.png DisplayWidgets.html -document-new.png -document-open.png -document-print.png -document-print-preview.png -document-properties.png -document-revert-ltr.png -document-revert-rtl.png -document-save-as.png -document-save.png -drawing.png -drive-harddisk.png -ease-in-out.png -ease-in.png -ease-out.png -ease.png -edit-clear.png -edit-copy.png -edit-cut.png -edit-delete.png -edit-find.png -edit-find-replace.png -edit-paste.png -edit-redo-ltr.png -edit-redo-rtl.png -edit-select-all.png -edit-undo-ltr.png -edit-undo-rtl.png -entry.png -expanders.png -extensions.png -figure-hierarchical-drawing.png -figure-windowed-label.png -file-button.png -filechooser.png -focus.png -folder.png -font-button.png -fontchooser.png -fontsel.png -format-indent-less-ltr.png -format-indent-less-rtl.png -format-indent-more-ltr.png -format-indent-more-rtl.png -format-justify-center.png -format-justify-fill.png -format-justify-left.png -format-justify-right.png -format-text-bold.png -format-text-italic.png -format-text-strikethrough.png -format-text-underline.png -frame-gap.png -frame.png -frames.png glossary.html -go-bottom.png -go-down.png -go-first-ltr.png -go-first-rtl.png -go-home.png -go-jump-ltr.png -go-jump-rtl.png -go-last-ltr.png -go-last-rtl.png -go-next-ltr.png -go-next-rtl.png -go-previous-ltr.png -go-previous-rtl.png -go-top.png -go-up.png -gradient1.png -gradient2.png -gradient3.png -gradient4.png -grid-packing.png gtk3-Accelerator-Maps.html gtk3-Bindings.html gtk3-Clipboards.html @@ -162,7 +59,6 @@ GtkAppChooserWidget.html GtkApplication.html GtkApplicationWindow.html -gtk-apply.png GtkArrow.html GtkAspectFrame.html GtkAssistant.html @@ -176,8 +72,6 @@ GtkButtonBox.html GtkButton.html GtkCalendar.html -gtk-cancel.png -gtk-caps-lock-warning.png GtkCellAreaBox.html GtkCellAreaContext.html GtkCellArea.html @@ -199,23 +93,16 @@ GtkColorChooserDialog.html GtkColorChooser.html GtkColorChooserWidget.html -gtk-color-picker.png GtkColorSelectionDialog.html GtkColorSelection.html GtkComboBox.html GtkComboBoxText.html gtk-compiling.html -gtk-connect.png GtkContainer.html -gtk-convert.png GtkCssProvider.html GtkDialog.html -gtk-disconnect.png -gtk-dnd-multiple.png -gtk-dnd.png GtkDrawingArea.html GtkEditable.html -gtk-edit.png GtkEntryBuffer.html GtkEntryCompletion.html GtkEntry.html @@ -231,7 +118,6 @@ GtkFontChooserDialog.html GtkFontChooser.html GtkFontChooserWidget.html -gtk-font.png GtkFontSelectionDialog.html GtkFontSelection.html GtkFrame.html @@ -253,7 +139,6 @@ GtkIMContext.html GtkIMContextSimple.html GtkIMMulticontext.html -gtk-index.png GtkInfoBar.html GtkInvisible.html GtkLabel.html @@ -280,25 +165,17 @@ gtk-migrating-theme-GtkStyleContext-engines.html gtk-migrating-unique-GtkApplication.html GtkMisc.html -gtk-no.png GtkNotebook.html GtkNumerableIcon.html gtkobjects.html GtkOffscreenWindow.html -gtk-ok.png -gtk-orientation-landscape.png -gtk-orientation-portrait.png -gtk-orientation-reverse-landscape.png -gtk-orientation-reverse-portrait.png gtk-osx.html GtkOverlay.html GtkPageSetup.html -gtk-page-setup.png GtkPageSetupUnixDialog.html GtkPaned.html GtkPaperSize.html GtkPlug.html -gtk-preferences.png GtkPrintContext.html GtkPrinter.html GtkPrintJob.html @@ -326,7 +203,6 @@ GtkScrollable.html GtkScrollbar.html GtkScrolledWindow.html -gtk-select-color.png GtkSeparator.html GtkSeparatorMenuItem.html GtkSeparatorToolItem.html @@ -369,8 +245,6 @@ GtkTreeViewColumn.html GtkTreeView.html GtkUIManager.html -gtk-undelete-ltr.png -gtk-undelete-rtl.png gtk-update-icon-cache.html GtkVBox.html GtkVButtonBox.html @@ -385,119 +259,28 @@ GtkWindow.html gtk-windows.html gtk-x11.html -gtk-yes.png -handles.png -hello-world.png -help-about.png -help-contents.png home.png -icon-view.png -image-missing.png -image.png index.html index.sgml -label.png -layout-btlr.png -layout-btrl.png LayoutContainers.html -layout-lrbt.png -layout-lrtb.png -layout-rlbt.png -layout-rltb.png -layout-tblr.png -layout-tbrl.png left.png -linear.png -link-button.png -list-add.png -list-and-tree.png -list-remove.png -lockbutton-locked.png -lock-button.png -lockbutton.png -lockbutton-sorry.png -lockbutton-unlocked.png -media-floppy.png -media-optical.png -media-playback-pause.png -media-playback-start-ltr.png -media-playback-start-rtl.png -media-playback-stop.png -media-record.png -media-seek-backward-ltr.png -media-seek-backward-rtl.png -media-seek-forward-ltr.png -media-seek-forward-rtl.png -media-skip-backward-ltr.png -media-skip-backward-rtl.png -media-skip-forward-ltr.png -media-skip-forward-rtl.png -menubar.png MenusAndCombos.html -messagedialog.png migrating.html MiscObjects.html -multiline-text.png -network-idle.png -notebook.png -numerableicon2.png -numerableicon.png NumericEntry.html -options.png Ornaments.html -pagesetupdialog.png -panes.png PlugSocket.html -printdialog.png -printer-error.png -printer-info.png -printer-paused.png -printer-warning.png Printing.html -process-stop.png -progressbar.png pt06.html -radio-group.png -recentchooserdialog.png RecentDocuments.html right.png -scales.png -scrolledwindow.png ScrollingWidgets.html SelectorWidgets.html -separator.png -slices.png -sliders.png -spinbutton.png -spinner.png -statusbar.png style.css -switch.png -system-run.png TextWidget.html TextWidgetObjects.html -text-x-generic.png theming.html -toggle-button.png -toolbar.png -toolpalette.png -tools-check-spelling.png -tree-view-coordinates.png TreeWidget.html TreeWidgetObjects.html up.png -view-fullscreen.png -view-refresh.png -view-restore.png -view-sort-ascending.png -view-sort-descending.png -volumebutton.png -widget-hvalign.png -window-close.png -window-default.png -window.png WindowWidgets.html -zoom-fit-best.png -zoom-in.png -zoom-original.png -zoom-out.png
From a cursory glance, this seems to be a problem for all images that are listed in docs/reference/gtk/Makefile.am under HTML_IMAGES as $(srcdir)/images/*.png Maybe gtk-doc has a problem with $(srcdir) or mixing $(top_srcdir) and $(srcdir)?
gtk-doc has never been very good about srcdir != builddir, so we haven't made any particular attempt at making this work
Some more info regarding this bug: Apparently simply using mkdir build-foo && cd build-foo && ../configure --enable-gtk-doc is not sufficient to trigger this particular bug. This bugs seems to happen when a *absolute* path to the configure script is used.
Looks like a bug in gtk-doc to me, so re-assigning
Digging a bit futher, the problem is that gtk-doc doesn't correctly handle absolute paths in the html-build.stamp rule. The relevant bits are for file in $(HTML_IMAGES) ; do \ if test -f $(abs_srcdir)/$$file ; then \ cp $(abs_srcdir)/$$file $(abs_builddir)/html; \ fi; \ if test -f $(abs_builddir)/$$file ; then \ cp $(abs_builddir)/$$file $(abs_builddir)/html; \ fi; \ done; Say, you have, like gtk+, the following in Makefile.am: HTML_IMAGES = \ $(top_srcdir)/gtk/stock-icons/24/help-about.png \ ... $(srcdir)/images/aboutdialog.png \ ... and you execute the following steps # cd /tmp # wget http://ftp.gnome.org/pub/GNOME/sources/gtk+/3.4/gtk+-3.4.1.tar.xz # tar xf gtk+-3.4.1.tar.xz # mkdir gtk+-3.4.1/build-abs && cd gtk+-3.4.1/build-abs # /tmp/gtk+-3.4.1/configure --enable-gtk-doc The resulting docs/reference/gtk/Makefile has abs_builddir = /tmp/gtk+-3.4.1/build-abs/docs/reference/gtk abs_srcdir = /tmp/gtk+-3.4.1/docs/reference/gtk top_srcdir = /tmp/gtk+-3.4.1 srcdir = /tmp/gtk+-3.4.1/docs/reference/gtk I guess it's pretty obvious now, why the above for loop doesn't work as expected $(abs_srcdir)/$$file → /tmp/gtk+-3.4.1/docs/reference/gtk/tmp/gtk+-3.4.1/gtk/stock-icons/24/help-about.png resp. /tmp/gtk+-3.4.1/docs/reference/gtk/tmp/gtk+-3.4.1/docs/reference/gtk/images/aboutdialog.png
Created attachment 212194 [details] [review] [PATCH] Fix installation of HTML images for absolute paths
The attached patch fixes this issue for me. I don't see why we would want to copy images from the builddir so I removed that rule. On the other hand, if absolute paths are used, I simply use $$file instead of combining that with $abs_srcdir. I tested in and out-of-tree builds, with absolute and relative paths to ./configure and absolute and relative paths in HTML_IMAGES, i.e. HTML_IMAGES = foo.png HTML_IMAGES= $(srcdir)/foo.png HTML_IMAGES= $(top_srcdir)/bar/foo.png
As I noticed that the builddir rule was for images generated in the build directory, I wanted that add that this should be correctly handled by my patch, e.g. HTML_IMAGES = foo.png, where foo.png is generated at builddir, will work just fine.
any comment?
Review of attachment 212194 [details] [review]: ::: gtk-doc.make @@ +178,3 @@ fi; \ + if test -f $$file ; then \ + cp $$file $(abs_builddir)/html; \ Wouldn't this break generated files? Maybe saver to just append this one to the previous two. This also needs to be done in gtk-doc.notmpl.make
Created attachment 345772 [details] [review] [PATCH] Fix installation of HTML images Thanks for the review Stefan. Updated patch attached.
Comment on attachment 345772 [details] [review] [PATCH] Fix installation of HTML images Herje. Totally missed the update. Sorry.