GNOME Bugzilla – Bug 637090
Pass libraries in LDFLAGS to gtk-doc from gtkdoc doclet
Last modified: 2011-02-20 12:01:52 UTC
gtk-doc's gtkdoc-scangobj expects various environment variables to be modified for it to run. Most notably, it expects the libraries being linked to by its scanning program to be passed in LDFLAGS. Normally this is handled automatically by gtk-doc.make (line 83, in the scan-build.stamp rule), but it currently has to be handled manually by projects using the gtkdoc doclet with valadoc. It would be nice if valadoc automatically made the appropriate modifications to various environment variables before calling into gtk-doc, since it should have all the right information available.
This is handled automatically if you pass --pkg to valadoc.
That works for all the dependencies of the library the documentation's being built for, but not for the library itself. If I pass the library (and all its dependencies) to valadoc with a --pkg flag (and not in LDFLAGS), I get the following errors: aliasable.vala:27.1-27.41: error: `Folks' already contains a definition for `Aliasable' folks.vapi:134.2-134.41: note: previous definition of `Aliasable' was here avatar-owner.vala:27.1-27.43: error: `Folks' already contains a definition for `AvatarOwner' folks.vapi:138.2-138.43: note: previous definition of `AvatarOwner' was here … Whereas if I don't pass the library to valadoc with a --pkg flag (but do pass all its dependencies), I get the following errors from the linker: gtk-doc: Linking scanner folks-telepathy-scan.o: In function `get_object_types': /opt/gnome2/source/folks/docs/gtk-doc/folks-telepathy/folks-telepathy-scan.c:21: undefined reference to `folks_tp_lowlevel_get_type' /opt/gnome2/source/folks/docs/gtk-doc/folks-telepathy/folks-telepathy-scan.c:22: undefined reference to `tpf_persona_get_type' /opt/gnome2/source/folks/docs/gtk-doc/folks-telepathy/folks-telepathy-scan.c:23: undefined reference to `tpf_persona_store_get_type' It's only if I pass the library's dependencies to valadoc with --pkg flags, and list the library .so files themselves in LDFLAGS that everything (just about) seems to work. It's currently set up like this here, if you want to take a look: http://git.gnome.org/browse/folks/tree/docs/Makefile.am
Use -X -l -X your_library.so. For a reference Makefile.am see: http://gitorious.org/sqlheavy/sqlheavy/blobs/master/docs/Makefile.am There are other (yes, undocumented) options: -X --deprecated-guards, --ignore-decorators and --nohtml. Leaving the bug opened because of the missing documentation.
We were doing that already, but it turns out that we were passing: -X -l \ -X $(top_builddir)/folks/.libs/libfolks.so \ -X $(top_builddir)/backends/telepathy/lib/.libs/libfolks-telepathy.so \ instead of -X -l -X $(top_builddir)/folks/.libs/libfolks.so \ -X -l -X $(top_builddir)/backends/telepathy/lib/.libs/libfolks-telepathy.so \ and so the second library getting passed in was being ignored by the doclet, as it wasn't preceded by a -l flag. Thanks for your help!
Happens ;) Closing the bug, feel free to reopen it.
(In reply to comment #3) > Leaving the bug opened because of the missing documentation. I think some extra documentation would still be useful, unless I've overlooked some which already exists?