gnome.gtkdoc uses -Wl,-rpath to ensure the scanner executable built by
gtkdoc-scangobj will load shared libraries from the correct directories.
However, FreeBSD configures its linker to use --enable-new-dtags by
default, which converts RPATH to RUNPATH. If users have LD_LIBRARY_PATH
environment variable set, RUNPATH will be overrided by LD_LIBRARY_PATH
and libraries will be loaded from wrong directories, causing undefined
symbol error when running the executable.
In order to solve the problem, we have to prepend directories specified
with -Wl,-rpath to LD_LIBRARY_PATH to avoid relying on the deprecated
RPATH attribute.
There are cases where we need to specify arguments to gtkdoc-mkdb, like
telling it to scan extensions that are not '.h' and '.c'. Let's add a
new named argument to gnome.gtkdoc(), as well as the plumbing needed for
the gtk-doc helper script.
'gtkdoc-scangobj' script was recently ported to Python (it was Perl), and it now requires providing '--type' option to specify the name of the file to store the types in. Without this option, 'gtkdockelper' will exit with error status 2 and will throw a message "gtkdoc-scangobj: error: unrecognized arguments: <typefile>"
Instead of adding it everywhere manually, create a wrapper called
mesonlib.Popen_safe and use that everywhere that we call an executable
and extract its output.
This will also allow us to tweak it to do more/different things if
needed for some locales and/or systems.
Closes#1079
Using 'mesonbuild' as the module can cause it to use the
system-installed module and can also break if we rename the directory,
so avoid that by always using relative imports.
Not all headers are public, or contain public types. GTK-Doc allows
adding headers to be ignored during the "scan" phase, by passing the
`--ignore-headers` command line argument to gtkdoc-scan.
Currently, you can do something like:
ignored_headers = [ 'foo-private.h', 'bar-private.h', ]
gnome.gtkdoc(...
scan_args: [
'--ignore-headers=' + ' '.join(ignored_headers),
],
...)
But it does not guarantee escaping rules and it's definitely not nice.
We can add a simpler version of that mechanism through a new positional
argument, `ignore_headers`, which behaves like `content_files` or
`html_assets`, and takes an array of header files to ignore:
gnome.gtkdoc(...
ignore_headers: ignored_headers,
...)
If a `<modulename>-overrides.txt` file exists in the docs directory it
means it's intended to be used in place of the one gtk-doc generates.
GLib and GTK+, for instance, ship with one because some of the types
they provide — like the thread primitives, or the platform macros —
contain architecture-dependent fields that should not be accessed
directly.
This commit should close the last bit of issue #550.
Allowing the object tree to be generated.
We need to add options to allow copying the ncesseary sources and
assets so the HTML generator can work with them (everything is
relative so we need to copy them in the build directory).
Until now the documentation was not generated from the user provided
main sgml file but it was using a generated one, which lead to a broken
documentation. Starting using it revealed the other bugs fixed in that
commit.
The extra arguments are typically used to specified the location of
installed API references that gtk-doc can use to create cross links
for symbols.
Fixes#555
Ting-Wei Lan