GNOME Bugzilla – Bug 503119
Add dependency on content_files to SGML target
Last modified: 2014-02-08 21:19:17 UTC
My gtk-doc documentation includes some Docbook files which are generated at build time. I'd like to simply add them to content_files but that variable isn't used as a dependency for sgml-build.stamp, so the build fails because the files haven't been created yet.
How and when are they generated? They are dependency for html-build.stamp. html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) and those listed in expand_content_files too are a dependency for sgml-build.stamp. sgml-build.stamp runs gtkdoc-mkdb and for that they should not be needed? If the project in online, can you add links to e.g. viewvc?
My doc/Makefile contains rules to generate them: content_files = ref-gypsy-client.xml ref-gypsy-server.xml ref-%.xml: $(top_srcdir)/interfaces/%-full.xml $(XSLT) -o $@ $(top_srcdir)/docs/tools/spec-to-docbook.xsl $< The generated files need to be available when the SGML is built because they are XIncluded from the -docs.sgml file. If they don't exist, parsing the -docs.sgml file fails. At the moment I'm also putting the files in expand_content_files, but this is a workaround.
Wouldn't it work if you do expand_content_files = ref-gypsy-client.xml ref-gypsy-server.xml content_files = $(expand_content_files) static.xml ...
Yes, that's effectively what I'm doing now, but that isn't what expand_content_files is for: # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded # These files must be listed here *and* in content_files Adding $(content_files) to the sgml-build.stamp target would mean that all content referred to by the documentation would be present before trying to generate it. More to the point, what if passing my generated documentation to --expand-content-files actually broke the documentation in some way? (say, it was a binary file).
Ok, I see. As expand-content-files are a subset of content_files anyway. I am changed the dependecy for sgml-build.stamp from expand-content-files to content_files. 2007-12-12 Stefan Kost <ensonic@users.sf.net> * gtk-doc.make: * gtk-doc.notmpl.make: Use content_files as a dependency the sgml-build.stamp.Fixes #503119.
So, every time someone edits some DocBook content files the *other* DocBook files get uselessly rebuilt too now? This makes no sense. Some projects have special needs (mine have too), but they should modify the makefiles to suit their needs then. If this kind of setup is common enough to warrant a direct support in gtk-doc, then all right, let's add another variable holding a subset of content_files that should cause DocBook rebuild. But the `fix' is just wrong.
I think you've misunderstood the fix. content_files is a list of files which are part of the documentation, this simply moves them to be built when the SGML is prepared. There is no change apart from when the files referred to by content_files don't exist yet (but there are rules to build them), when they are built before the SGML instead of before the HTML.
(In reply to comment #7) > content_files is a list of files which > are part of the documentation, this simply moves them to be built No. content_files are human written content added to the generated API reference. They may be generated too, of course, but the primary intent is human written files. This is exactly like .c files. They may be generated and many projects generate some and may want the build system to specifically support this case. This is legitimate. However, changing the behaviour on the bais on some assumptions that they are built in some random phase is not. The normal DocBook build step does not require them because it is *its* goal to generate the DocBook sources. So, if anywhere, generated extra DocBook files should be built in this step. Which means the step that comes *after* requires both gtk-doc-generated and whatever-else-generated DocBook files to exist. Not that the whatever-else-generated DocBook files are prerequisite for the gtk-doc-generated ones. > There is no change apart from when the files referred to by > content_files don't exist yet (but there are rules to build them), Yes, there is a change. Remember, the files are human written. So, before, if I edited some of them, only the HTML build step would be executed. Now, both DocBook and HTML are executed. > when they > are built before the SGML instead of before the HTML. And if I want to build them after? Though I admit this is not a very likely scenario, so this is not my main concern.
I agree with Yeti and will revert the change for now. The issue is that whenever you touch them, make will rerun gtkdoc-mkdb which is not what should happen.
Remove milestone, until someone has a better idea.
looking at this again. Is this still an issue? html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) so if any handwritten file changes the html gets rebuild. If the (generated) content-files not exists yet, they will be generated. We don't need them at the sgml-build.stamp, as there the $(DOC_MAIN_SGML_FILE) does not yet need to be complete. Please reopen if it is still an issue.