GNOME Bugzilla – Bug 766400
Fail to build because of gtkdoc-scangobj and docs/reference/gspell-1.0-sections.txt
Last modified: 2016-06-10 16:04:06 UTC
Hello, Summary: The documentation build process relies on high resolution mtime in file metadata. This is not available on every platform, in particular on Debian GNU/kFreeBSD (yes, exotic platform, but there is a clean fix), where it cannot be built. This can be fixed by directly having docs/reference/gspell-1.0-sections.txt instead of copying it from docs/reference/gspell-sections.txt.in: it will not be overwritten by gtkdoc-scan or gtkdoc-cangobj, and that would simplify the Makefile.am. The documentation was failing to build on Debian GNU/kFreeBSD (yes, this is a rather exotic platform, but I think I have an explanation and a nice solution anyway). According to my findings, it was due to the way docs/reference/gspell-1.0-sections.txt is supposed to be generated according to the generated docs/reference/Makefile: 1. The all target indirectly depends on gspell-1.0-sections.txt, which depends on scan-build.stamp. Its recipe is therefore ran, which: 2.1 calls gtkdoc-scan and gtkdoc-cangobj, which generates an incorrect gspell-1.0-sections.txt; 2.2 then touches scan-build.stamp. 2. Since gspell-1.0-sections.txt is now older than its dependency scan-build.stamp, it is rebuilt. Its /override/ recipe is therefore ran, which copies a correct version of it from gspell-sections.txt.in. That relies on GNU Make being able to detect that gspell-1.0-sections.txt is a fraction of seconds older than its dependency scan-build.stamp, and this is only possible with high resolution mtime in file metadata (at least 1/100s to be safe, I would say). Unfortunately, this is not available everywhere, in particular on Debian GNU/kFreeBSD, where mtime is stored with a resolution of 1s. Now, I think there is a simple fix to that. I have just checked the behaviour of gtkdoc-scanobj, and it only generates the sections file if it does not exist. According to <https://developer.gnome.org/gtk-doc-manual/unstable/howdoesgtkdocwork.html.en>, this is meant to create it the first time, leaving it to the developer to maintain it afterwards. The fix would therefore be to: 1. rename docs/reference/gspell-sections.txt.in as docs/reference/gspell-1.0-sections.txt; 2. remove the corresponding override from docs/reference/Makefile.am:64. That would both: * make gspell more portable; * simplify the docs/reference/Makefile.am; * fit to the way GTK-Doc is supposed to be used, I think. I hope this is okay… Librement, -- Tanguy
The goal was to not hardcode the API version. I know GNU make triggers a warning about the overriding recipe. This is not very clean. So I've normally fixed the problem: https://git.gnome.org/browse/gspell/commit/?id=6a01d1da0dd5fd957fda0d9be46c59bb1fda6b24 With the commit backported to the gspell-1-0 branch. Can you test that it works with Debian/kFreeBSD? If it works, I'll roll a new tarball.
I see, too bad. I will test this soon and tell you. I also notice, when gtkdoc-san or gtkdoc-scangobj generate docs/reference/gspell-1.0-sections.txt, it is only wrong because it references files such as gspell-checker.xml that do not exist, and is in fact checker.xml. I am not sure of why that is, but it makes me think there may be another way to possibly fix that, though it is probably simpler and safer to just go on with docs/reference/gspell-1.0-sections.txt. Otherwise, I wonder if there could not be some Makefile rule, called before scan-build.stamp, that could cp gspell-sections.txt to gspell-1.0-sections.txt. I am not sure it is possible while using gtk-doc.make though.
I've tried using a all-local rule. -local Automake rules are normally executed before the target. So all-local is executed before 'all'. But it doesn't work, I don't know why. Even with make -j1. So it's simpler to name the file with the correct name directly. Bumping the API version is rare, so if it's hardcoded at 3 places, it is not a big deal.
I builds fine with your commit, thank you. No hurry to publish a new minor version though, at least for Debian GNU/kFreeBSD I have worked around the problem by copying gspell-sections.txt to gspell-1.0-sections.txt in debian/rules, which is the Makefile of a Debian package, so do as you see fit.
Ok, before doing the release I'll wait a little to see if there are other things to fix.
gspell 1.0.2 released. There was nothing else to fix. Either nobody uses the spell checking in gedit or latexila, or gspell is damn stable :-)
Great! I will package that soon, although, for the same reason, there is absolutely no emergency. :-)