Debian Codegraph @

subprojects/meson-docs/docs/markdown/Vala.md

raw
1 ---
2 title: Vala
3 short-description: Compiling Vala and Genie programs
4 ...
5
6 # Compiling Vala applications and libraries
7 Meson supports compiling applications and libraries written in
8 [Vala](https://vala-project.org/) and
9 [Genie](https://wiki.gnome.org/Projects/Genie) . A skeleton `meson.build` file:
10
11 ```meson
12 project('vala app', 'vala', 'c')
13
14 dependencies = [
15 dependency('glib-2.0'),
16 dependency('gobject-2.0'),
17 ]
18
19 sources = files('app.vala')
20
21 executable('app_name', sources, dependencies: dependencies)
22 ```
23
24 You must always specify the `glib-2.0` and `gobject-2.0` libraries as
25 dependencies, because all current Vala applications use them.
26 [GLib](https://developer.gnome.org/glib/stable/) is used for basic data types
27 and [GObject](https://developer.gnome.org/gobject/stable/) is used for the
28 runtime type system.
29
30
31 ## Using libraries
32
33 Meson uses the [[dependency]]
34 function to find the relevant VAPI, C headers and linker flags when it
35 encounters a Vala source file in a build target. Vala needs a VAPI
36 file and a C header or headers to use a library. The VAPI file helps
37 map Vala code to the library's C programming interface. It is the
38 [`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/)
39 tool that makes finding these installed files all work seamlessly
40 behind the scenes. When a `pkg-config` file doesn't exist for the
41 library then the `find_library()`
42 method of the [[@compiler]] object
43 needs to be used. Examples are given later.
44
45 Note Vala uses libraries that follow the C Application Binary Interface (C ABI).
46 The library, however, could be written in C, Vala, Rust, Go, C++ or any other
47 language that can generate a binary compatible with the C ABI and so provides C
48 headers.
49
50
51 ### The simplest case
52 This first example is a simple addition to the `meson.build` file because:
53
54 * the library has a `pkg-config` file, `gtk+-3.0.pc`
55 * the VAPI is distributed with Vala and so installed with the Vala compiler
56 * the VAPI is installed in Vala's standard search path
57 * the VAPI, `gtk+-3.0.vapi`, has the same name as the `pkg-config` file
58
59 Everything works seamlessly in the background and only a single extra line is
60 needed:
61
62 ```meson
63 project('vala app', 'vala', 'c')
64
65 dependencies = [
66 dependency('glib-2.0'),
67 dependency('gobject-2.0'),
68 dependency('gtk+-3.0'),
69 ]
70
71 sources = files('app.vala')
72
73 executable('app_name', sources, dependencies: dependencies)
74 ```
75
76 GTK+ is the graphical toolkit used by GNOME, elementary OS and other
77 desktop environments. The binding to the library, the VAPI file, is
78 distributed with Vala.
79
80 Other libraries may have a VAPI that is distributed with the library
81 itself. Such libraries will have their VAPI file installed along with
82 their other development files. The VAPI is installed in Vala's
83 standard search path and so works just as seamlessly using the
84 `dependency()` function.
85
86
87 ### Targeting a version of GLib
88
89 Meson's [[dependency]] function
90 allows a version check of a library. This is often used to check a
91 minimum version is installed. When setting a minimum version of GLib,
92 Meson will also pass this to the Vala compiler using the
93 `--target-glib` option.
94
95 This is needed when using GTK+'s user interface definition files with
96 Vala's `[GtkTemplate]`, `[GtkChild]` and `[GtkCallback]` attributes.
97 This requires `--target-glib 2.38`, or a newer version, to be passed
98 to Vala. With Meson this is simply done with:
99
100 ```meson
101 project('vala app', 'vala', 'c')
102
103 dependencies = [
104 dependency('glib-2.0', version: '>=2.38'),
105 dependency('gobject-2.0'),
106 dependency('gtk+-3.0'),
107 ]
108
109 sources = files('app.vala')
110
111 executable('app_name', sources, dependencies: dependencies)
112 ```
113
114 Using `[GtkTemplate]` also requires the GTK+ user interface definition
115 files to be built into the binary as GResources. For completeness,
116 the next example shows this:
117
118 ```meson
119 project('vala app', 'vala', 'c')
120
121 dependencies = [
122 dependency('glib-2.0', version: '>=2.38'),
123 dependency('gobject-2.0'),
124 dependency('gtk+-3.0'),
125 ]
126
127 sources = files('app.vala')
128
129 sources += import( 'gnome' ).compile_resources(
130 'project-resources',
131 'src/resources/resources.gresource.xml',
132 source_dir: 'src/resources',
133 )
134
135 executable('app_name', sources, dependencies: dependencies)
136 ```
137
138
139 ### Adding to Vala's search path
140
141 So far we have covered the cases where the VAPI file is either
142 distributed with Vala or the library. A VAPI can also be included in
143 the source files of your project. The convention is to put it in the
144 `vapi` directory of your project.
145
146 This is needed when a library does not have a VAPI or your project
147 needs to link to another component in the project that uses the C ABI.
148 For example if part of the project is written in C.
149
150 The Vala compiler's `--vapidir` option is used to add the project
151 directory to the VAPI search path. In Meson this is done with the
152 `add_project_arguments()` function:
153
154 ```meson
155 project('vala app', 'vala', 'c')
156
157 vapi_dir = meson.current_source_dir() / 'vapi'
158
159 add_project_arguments(['--vapidir', vapi_dir], language: 'vala')
160
161 dependencies = [
162 dependency('glib-2.0'),
163 dependency('gobject-2.0'),
164 dependency('foo'), # 'foo.vapi' will be resolved as './vapi/foo.vapi'
165 ]
166
167 sources = files('app.vala')
168
169 executable('app_name', sources, dependencies: dependencies)
170 ```
171
172 If the VAPI is for an external library then make sure that the VAPI
173 name corresponds to the pkg-config file name.
174
175 The [`vala-extra-vapis`
176 repository](https://gitlab.gnome.org/GNOME/vala-extra-vapis) is a
177 community maintained repository of VAPIs that are not distributed.
178 Developers use the repository to share early work on new bindings and
179 improvements to existing bindings. So the VAPIs can frequently change.
180 It is recommended VAPIs from this repository are copied into your
181 project's source files.
182
183 This also works well for starting to write new bindings before they
184 are shared with the `vala-extra-vapis` repository.
185
186
187 ### Libraries without pkg-config files
188
189 A library that does not have a corresponding pkg-config file may mean
190 `dependency()` is unsuitable for finding the C and Vala interface
191 files. In this case it is necessary to use the `find_library()` method
192 of the compiler object.
193
194 The first example uses Vala's POSIX binding. There is no pkg-config
195 file because POSIX includes the standard C library on Unix systems.
196 All that is needed is the VAPI file, `posix.vapi`. This is included
197 with Vala and installed in Vala's standard search path. Meson just
198 needs to be told to only find the library for the Vala compiler:
199
200 ```meson
201 project('vala app', 'vala', 'c')
202
203 dependencies = [
204 dependency('glib-2.0'),
205 dependency('gobject-2.0'),
206 meson.get_compiler('vala').find_library('posix'),
207 ]
208
209 sources = files('app.vala')
210
211 executable('app_name', sources, dependencies: dependencies)
212 ```
213
214 The next example shows how to link with a C library where no
215 additional VAPI is needed. The standard maths functions are already
216 bound in `glib-2.0.vapi`, but the GNU C library requires linking to
217 the maths library separately. In this example Meson is told to find
218 the library only for the C compiler:
219
220 ```meson
221 project('vala app', 'vala', 'c')
222
223 dependencies = [
224 dependency('glib-2.0'),
225 dependency('gobject-2.0'),
226 meson.get_compiler('c').find_library('m', required: false),
227 ]
228
229 sources = files('app.vala')
230
231 executable('app_name', sources, dependencies: dependencies)
232 ```
233
234 The `required: false` means the build will continue when using another
235 C library that does not separate the maths library. See [Add math
236 library (-lm) portably](howtox.md#add-math-library-lm-portably).
237
238 The final example shows how to use a library that does not have a
239 pkg-config file and the VAPI is in the `vapi` directory of your
240 project source files:
241
242 ```meson
243 project('vala app', 'vala', 'c')
244
245 vapi_dir = meson.current_source_dir() / 'vapi'
246
247 add_project_arguments(['--vapidir', vapi_dir], language: 'vala')
248
249 dependencies = [
250 dependency('glib-2.0'),
251 dependency('gobject-2.0'),
252 meson.get_compiler('c').find_library('foo'),
253 meson.get_compiler('vala').find_library('foo', dirs: vapi_dir),
254 ]
255
256 sources = files('app.vala')
257
258 executable('app_name', sources, dependencies: dependencies)
259 ```
260 The `find_library()` method of the C compiler object will try to find the C
261 header files and the library to link with.
262
263 The `find_library()` method of the Vala compiler object needs to have the `dir`
264 keyword added to include the project VAPI directory. This is not added
265 automatically by `add_project_arguments()`.
266
267 ### Working with the Vala Preprocessor
268
269 Passing arguments to [Vala's
270 preprocessor](https://wiki.gnome.org/Projects/Vala/Manual/Preprocessor)
271 requires specifying the language as `vala`. For example, the following
272 statement sets the preprocessor symbol `USE_FUSE`:
273
274 ```meson
275 add_project_arguments('-D', 'USE_FUSE', language: 'vala')
276 ```
277
278 If you need to pass an argument to the C pre-processor then specify
279 the language as c. For example to set FUSE_USE_VERSION to 26 use:
280
281 ```meson
282 add_project_arguments('-DFUSE_USE_VERSION=26', language: 'c')
283 ```
284
285 ## Building libraries
286
287
288 ### Changing C header and VAPI names
289
290 Meson's [[library]] target automatically
291 outputs the C header and the VAPI. They can be renamed by setting the
292 `vala_header` and `vala_vapi` arguments respectively:
293
294 ```meson
295 foo_lib = shared_library('foo', 'foo.vala',
296 vala_header: 'foo.h',
297 vala_vapi: 'foo-1.0.vapi',
298 dependencies: [glib_dep, gobject_dep],
299 install: true,
300 install_dir: [true, true, true])
301 ```
302
303 In this example, the second and third elements of the `install_dir`
304 array indicate the destination with `true` to use default directories
305 (i.e. `include` and `share/vala/vapi`).
306
307
308 ### GObject Introspection and language bindings
309
310 A 'binding' allows another programming language to use a library
311 written in Vala. Because Vala uses the GObject type system as its
312 runtime type system it is very easy to use introspection to generate a
313 binding. A Meson build of a Vala library can generate the GObject
314 introspection metadata. The metadata is then used in separate projects
315 with [language specific
316 tools](https://wiki.gnome.org/Projects/Vala/LibraryWritingBindings) to
317 generate a binding.
318
319 The main form of metadata is a GObject Introspection Repository (GIR)
320 XML file. GIRs are mostly used by languages that generate bindings at
321 compile time. Languages that generate bindings at runtime mostly use a
322 typelib file, which is generated from the GIR.
323
324 Meson can generate a GIR as part of the build. For a Vala library the
325 `vala_gir` option has to be set for the `library`:
326
327 ```meson
328 foo_lib = shared_library('foo', 'foo.vala',
329 vala_gir: 'Foo-1.0.gir',
330 dependencies: [glib_dep, gobject_dep],
331 install: true,
332 install_dir: [true, true, true, true])
333 ```
334
335 The `true` value in `install_dir` tells Meson to use the default
336 directory (i.e. `share/gir-1.0` for GIRs). The fourth element in the
337 `install_dir` array indicates where the GIR file will be installed.
338
339 To then generate a typelib file use a custom target with the
340 `g-ir-compiler` program and a dependency on the library:
341
342 ```meson
343 g_ir_compiler = find_program('g-ir-compiler')
344 custom_target('foo typelib', command: [g_ir_compiler, '--output', '@OUTPUT@', '@INPUT@'],
345 input: meson.current_build_dir() / 'Foo-1.0.gir',
346 output: 'Foo-1.0.typelib',
347 depends: foo_lib,
348 install: true,
349 install_dir: get_option('libdir') / 'girepository-1.0')
350 ```