docs: Explain how to use a Vala project's VAPI files with find_library() [skip ci]
The Vala compiler object's find_libary() method needs the 'dir' keyword to
add a project's local vapi dir to the VAPI search path.
See
@@ -53,7 +53,7 @@ This first example is a simple addition to the `meson.build` file because:
* the library has a `pkg-config` file, `gtk+-3.0.pc`
* the VAPI is distributed with Vala and so installed with the Vala compiler
* the VAPI is installed in Vala's standard search path
- * the VAPI has the same name as the `pkg-config` file, `gtk+-3.0.vapi`
+ * the VAPI, `gtk+-3.0.vapi`, has the same name as the `pkg-config` file
Everything works seamlessly in the background and only a single extra line is
needed:
@@ -146,10 +146,11 @@ the VAPI search path. In Meson this is done with the `add_project_arguments()`
function:
```meson
-project('vala app', 'c', 'vala')
+project('vala app', 'vala', 'c')
+
+vapi_dir = join_paths(meson.current_source_dir(), 'vapi')
-add_project_arguments(['--vapidir', join_paths(meson.current_source_dir(), 'vapi')],
- language: 'vala')
+add_project_arguments(['--vapidir', vapi_dir], language: 'vala')
dependencies = [
dependency('glib-2.0'),
@@ -179,7 +180,7 @@ with the `vala-extra-vapis` repository.
### Libraries without pkg-config files
A library that does not have a corresponding pkg-config file may mean
`dependency()` is unsuitable for finding the C and Vala interface files. In this
-case it is necessary to use `find_library()`.
+case it is necessary to use the `find_library()` method of the compiler object.
The first example uses Vala's POSIX binding. There is no pkg-config file because
POSIX includes the standard C library on Unix systems. All that is needed is the
@@ -219,6 +220,37 @@ sources = files('app.vala')
executable('app_name', sources, dependencies: dependencies)
```
+The `required: false` means the build will continue when using another C library
+that does not separate the maths library. See [Add math library (-lm)
+portably](howtox.md#add-math-library-lm-portably).
+
+The final example shows how to use a library that does not have a pkg-config
+file and the VAPI is in the `vapi` directory of your project source files:
+```meson
+project('vala app', 'vala', 'c')
+
+vapi_dir = join_paths(meson.current_source_dir(), 'vapi')
+
+add_project_arguments(['--vapidir', vapi_dir], language: 'vala')
+
+dependencies = [
+ dependency('glib-2.0'),
+ dependency('gobject-2.0'),
+ meson.get_compiler('c').find_library('foo'),
+ meson.get_compiler('vala').find_library('foo', dir: vapi_dir),
+]
+
+sources = files('app.vala')
+
+executable('app_name', sources, dependencies: dependencies)
+```
+The `find_library()` method of the C compiler object will try to find the C
+header files and the library to link with.
+
+The `find_library()` method of the Vala compiler object needs to have the `dir`
+keyword added to include the project VAPI directory. This is not added
+automatically by `add_project_arguments()`.
+
## Building libraries
@@ -260,7 +292,7 @@ Meson can generate a GIR as part of the build. For a Vala library the
`vala_gir` option has to be set for the `library`:
```meson
-foo_lib = library('foo', 'foo.vala',
+foo_lib = shared_library('foo', 'foo.vala',
vala_gir: 'Foo-1.0.gir',
dependencies: [glib_dep, gobject_dep],
install: true,
