Debian Codegraph @

subprojects/meson-docs/docs/markdown/Gnome-module.md

raw
1 # GNOME module
2
3 This module provides helper tools for build operations needed when
4 building Gnome/GLib programs.
5
6 **Note**: the compilation commands here might not work properly when
7 you change the source files. This is a bug in the respective
8 compilers which do not expose the required dependency
9 information. This has been reported upstream in [this bug]. Until
10 this is fixed you need to be careful when changing your source
11 files.
12
13 [this bug]: https://bugzilla.gnome.org/show_bug.cgi?id=745754
14
15 ## Usage
16
17 To use this module, just do: **`gnome = import('gnome')`**. The
18 following functions will then be available as methods on the object
19 with the name `gnome`. You can, of course, replace the name `gnome`
20 with anything else.
21
22 ### gnome.compile_resources()
23
24 ```
25 gnome.compile_resources(id: string, input_file: string | File,
26 build_by_default: bool = false,
27 c_name: string | None = None,
28 dependencies: [](File, CustomTarget, CustomTargetIndex) = [],
29 export: bool = false,
30 extra_args: []string = [],
31 gresource_bundle: bool = false,
32 install_dir: string | None = None,
33 source_dir: [string] = [],
34 ): (CustomTarget, CustomTarget) | CustomTarget
35 ```
36
37 This function compiles resources specified in an XML file into code
38 that can be embedded inside the main binary. Similar a build target it
39 takes two positional arguments. The first one is the name of the
40 resource and the second is the XML file containing the resource
41 definitions. If the name is `foobar`, Meson will generate a header
42 file called `foobar.h`, which you can then include in your sources.
43 The resources specified are automatically added as dependencies of the
44 generated target.
45
46 * `c_name`: passed to the resource compiler as an argument after
47 `--c-name`
48 * `dependencies`: extra targets to depend upon for building
49 * `export`: (*Added 0.37.0*) if true, export the symbols of the
50 generated sources
51 * `extra_args`: extra command line arguments to pass to the resource
52 * `gresource_bundle`: (*Added 0.37.0*) if true, output a `.gresource`
53 file instead of source
54 * `install`: (*Added 0.37.0*) if true, install the gresource file
55 * `install_dir`: (*Added 0.37.0*) location to install the header or
56 bundle depending on previous options
57 * `install_header`: (*Added 0.37.0*) if true, install the header file
58 * `source_dir`: a list of directories where the resource compiler
59 should look up the files
60
61 Returns an array containing: `[c_source, header_file]` or
62 `[gresource_bundle]`
63
64 Example:
65
66 ```meson
67 gnome = import('gnome')
68
69 asresources = gnome.compile_resources(
70 'as-resources', 'data/asresources.gresource.xml',
71 source_dir: 'data',
72 c_name: 'as'
73 )
74
75 executable(
76 meson.project_name(),
77 asresources,
78 dependencies: my_deps,
79 install: true
80 )
81 ```
82
83 ### gnome.generate_gir()
84
85 Generates GObject introspection data.
86
87 Takes one or more positional arguments:
88
89 Either one or more library objects you want to build gir data for, or a single
90 executable object.
91
92 There are several keyword arguments. Many of these map directly to the
93 `g-ir-scanner` tool so see its documentation for more information.
94
95 * `dependencies`: deps to use during introspection scanning
96 * `extra_args`: command line arguments to pass to gir compiler
97 * `env`: (*Added 1.2.0*) environment variables to set, such as
98 `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`,
99 or an [[@env]] object which allows more sophisticated environment juggling.
100 * `export_packages`: extra packages the gir file exports
101 * `sources`: the list of sources to be scanned for gir data
102 * `nsversion`: namespace version
103 * `namespace`: the namespace for this gir object which determines
104 output files
105 * `identifier_prefix`: the identifier prefix for the gir object,
106 e.g. `Gtk`
107 * `includes`: list of gir names to be included, can also be a GirTarget
108 * `header`: *(Added 0.43.0)* name of main c header to include for the library, e.g. `glib.h`
109 * `include_directories`: extra include paths to look for gir files
110 * `install`: if true, install the generated files
111 * `install_gir`: (*Added 0.61.0*) overrides `install`, whether to install the
112 generated gir
113 * `install_dir_gir`: (*Added 0.35.0*) which directory to install the
114 gir file into; (*Deprecated since 0.61.0*) can be false to disable installation
115 * `install_typelib`: (*Added 0.61.0*) overrides `install`, whether to install the
116 generated typelib
117 * `install_dir_typelib`: (*Added 0.35.0*) which directory to install
118 the typelib file into; (*Deprecated since 0.61.0*) can be false to disable installation
119 * `link_with`: list of libraries to link with
120 * `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk`,
121 (*Since 0.43.0*) an ordered list of multiple prefixes is allowed
122 * `fatal_warnings`: *Since 0.55.0* turn scanner warnings into fatal errors.
123
124 Returns an array of two elements which are: `[gir_target,
125 typelib_target]`
126
127 ### gnome.genmarshal()
128
129 Generates a marshal file using the `glib-genmarshal` tool. The first
130 argument is the basename of the output files.
131
132 * `depends` [](BuildTarget | CustomTarget | CustomTargetIndex):
133 passed directly to CustomTarget (*since 0.61.0*)
134 * `depend_files` [](str | File): Passed directly to CustomTarget (*since 0.61.0*)
135 * `extra_args`: (*Added 0.42.0*) additional command line arguments to pass
136 * `install_dir`: directory to install header to
137 * `install_header`: if true, install the generated header
138 * `install_dir`: directory to install header to
139 * `install_header`: if true, install the generated header
140 * `internal`: if true, mark generated sources as internal to `glib-genmarshal`
141 (*Requires GLib 2.54*)
142 * `nostdinc`: if true, don't include the standard marshallers from glib
143 * `prefix`: the prefix to use for symbols
144 * `skip_source`: if true, skip source location comments
145 * `sources` [](str | File) *required*: the list of sources to use as inputs
146 * `stdinc`: if true, include the standard marshallers from glib
147 * `valist_marshallers`: if true, generate va_list marshallers
148
149 *Added 0.35.0*
150
151 Returns an array of two elements which are: `[c_source, header_file]`
152
153 ### gnome.mkenums()
154
155 Generates enum files for GObject using the `glib-mkenums` tool. The
156 first argument is the base name of the output files, unless
157 `c_template` and `h_template` are specified. In this case, the output
158 files will be the base name of the values passed as templates.
159
160 This method is essentially a wrapper around the `glib-mkenums` tool's
161 command line API. It is the most featureful method for enum creation.
162
163 Typically you either provide template files or you specify the various
164 template sections manually as strings.
165
166 Most libraries and applications will be using the same standard
167 template with only minor tweaks, in which case the
168 `gnome.mkenums_simple()` convenience method can be used instead.
169
170 Note that if you `#include` the generated header in any of the sources
171 for a build target, you must add the generated header to the build
172 target's list of sources to codify the dependency. This is true for
173
174 all generated sources, not just `mkenums`.
175
176 * `c_template`: template to use for generating the source
177 * `comments`: comment passed to the command
178 * `h_template`: template to use for generating the header
179 * `identifier_prefix`: prefix to use for the identifiers
180 * `install_header`: if true, install the generated header
181 * `install_dir`: directory to install the header
182 * `sources`: the list of sources to make enums with
183 * `symbol_prefix`: prefix to use for the symbols
184 * `eprod`: enum text
185 * `fhead`: file header
186 * `fprod`: file text
187 * `ftail`: file tail
188 * `vhead`: value text
189 * `vtail`: value tail
190
191 *Added 0.35.0*
192
193 Returns an array of two elements which are: `[c_source, header_file]`
194
195 ### gnome.mkenums_simple()
196
197 Generates enum `.c` and `.h` files for GObject using the
198 `glib-mkenums` tool with the standard template used by most
199 GObject-based C libraries. The first argument is the base name of the
200 output files.
201
202 Note that if you `#include` the generated header in any of the sources
203 for a build target, you must add the generated header to the build
204 target's list of sources to codify the dependency. This is true for
205 all generated sources, not just `mkenums_simple`.
206
207 The generated source file includes all headers passed to the sources keyword
208 argument, using paths relative to current build or source directory. That means
209 that targets that compile the generated source file must have the current
210 directory in its `include_directories`. *Since 1.3.0* `sources` outside of
211 current directory do not require adding those directories into
212 `include_directories` anymore.
213
214 * `body_prefix`: additional prefix at the top of the body file,
215 e.g. for extra includes
216 * `decorator`: optional decorator for the function declarations,
217 e.g. `GTK_AVAILABLE` or `GST_EXPORT`
218 * `function_prefix`: additional prefix for function names, e.g. in
219 case you want to add a leading underscore to functions used only
220 internally
221 * `header_prefix`: additional prefix at the top of the header file,
222 e.g. for extra includes (which may be needed if you specify a
223 decorator for the function declarations)
224 * `install_header`: if true, install the generated header
225 * `install_dir`: directory to install the header
226 * `identifier_prefix`: prefix to use for the identifiers
227 * `sources`: the list of sources to make enums with
228 * `symbol_prefix`: prefix to use for the symbols
229
230 Example:
231
232 ```meson
233 gnome = import('gnome')
234
235 my_headers = ['myheader1.h', 'myheader2.h']
236 my_sources = ['mysource1.c', 'mysource2.c']
237
238 # will generate myenums.c and myenums.h based on enums in myheader1.h and myheader2.h
239 enums = gnome.mkenums_simple('myenums', sources : my_headers)
240
241 mylib = library('my', my_sources, enums,
242 include_directories: my_incs,
243 dependencies: my_deps,
244 c_args: my_cargs,
245 install: true)
246 ```
247
248 *Added 0.42.0*
249
250 Returns an array of two elements which are: `[c_source, header_file]`
251
252 ### gnome.compile_schemas()
253
254 When called, this method will compile the gschemas in the current
255 directory. Note that this is not for installing schemas and is only
256 useful when running the application locally for example during tests.
257
258 * `build_by_default`: causes, when set to true, to have this target be
259 built by default, that is, when invoking plain `meson compile`, the default
260 value is true for all built target types
261 * `depend_files`: files ([[@str]],
262 [[files]], or
263 [[configure_file]]) of
264 schema source XML files that should trigger a re-compile if changed.
265
266 ### gnome.gdbus_codegen()
267
268 Compiles the given XML schema into gdbus source code. Takes two
269 positional arguments, the first one specifies the base name to use
270 while creating the output source and header and the second specifies
271 one XML file.
272
273 * `sources`: list of XML files
274 * `interface_prefix`: prefix for the interface
275 * `namespace`: namespace of the interface
276 * `extra_args`: (*Added 0.47.0*) additional command line arguments to pass
277 * `autocleanup`: *(Added 0.47.0)* if set generates autocleanup code. Can be one of `none`, `objects` or `all`
278 * `object_manager`: *(Added 0.40.0)* if true generates object manager code
279 * `annotations`: *(Added 0.43.0)* list of lists of 3 strings for the annotation for `'ELEMENT', 'KEY', 'VALUE'`
280 * `docbook`: *(Added 0.43.0)* prefix to generate `'PREFIX'-NAME.xml` docbooks
281 * `build_by_default`: causes, when set to true, to have this target be
282 built by default, that is, when invoking plain `meson compile`, the default
283 value is true for all built target types
284 * `install_dir`: (*Added 0.46.0*) location to install the header or
285 bundle depending on previous options
286 * `install_header`: (*Added 0.46.0*) if true, install the header file
287
288 Starting *0.46.0*, this function returns a list of at least two custom
289 targets (in order): one for the source code and one for the header.
290 The list will contain a third custom target for the generated docbook
291 files if that keyword argument is passed.
292
293 Earlier versions return a single custom target representing all the
294 outputs. Generally, you should just add this list of targets to a top
295 level target's source list.
296
297 Example:
298
299 ```meson
300 gnome = import('gnome')
301
302 # The returned source would be passed to another target
303 gdbus_src = gnome.gdbus_codegen('example-interface',
304 sources: 'com.example.Sample.xml',
305 interface_prefix : 'com.example.',
306 namespace : 'Sample',
307 annotations : [
308 ['com.example.Hello()', 'org.freedesktop.DBus.Deprecated', 'true']
309 ],
310 docbook : 'example-interface-doc'
311 )
312 ```
313
314 ### gnome.generate_vapi()
315
316 Creates a VAPI file from gir. The first argument is the name of the
317 library.
318
319 * `gir_dirs`: extra directories to include for gir files
320 * `install`: if true, install the VAPI file
321 * `install_dir`: location to install the VAPI file (defaults to datadir/vala/vapi)
322 * `metadata_dirs`: extra directories to include for metadata files
323 * `packages`: VAPI packages that are depended upon
324 * `sources`: the gir source to generate the VAPI from
325 * `vapi_dirs`: extra directories to include for VAPI files
326
327 Returns a custom dependency that can be included when building other
328 VAPI or Vala binaries.
329
330 *Added 0.36.0*
331
332 ### gnome.yelp()
333
334 ```meson
335 gnome.yelp(id: string, sources: ...string, sources: []string, media: []string,
336 languages: []string, symlink_media: bool = true): void
337 ```
338
339 Installs help documentation for Yelp using itstool and gettext. The first
340 argument is the project id.
341
342 Additionally, sources can be passed as additional positional arguments. This
343 was, however, undocumented and never officially supported. Due to a longstanding
344 bug, passing sources as a keyword argument will result in the positional
345 argument sources to be ignored. *since 0.60.0* A warning is raised in this case.
346
347 *Since 0.43.0* if "languages" is not specified, a
348 [LINGUAS](https://www.gnu.org/software/gettext/manual/html_node/po_002fLINGUAS.html)
349 file will be read instead.
350
351 *Since 0.60.0* the use of the positional argument sources has been deprecated,
352 and the "sources" keyword argument should be used instead. The passing of
353 sources as positional arguments will be removed in the future.
354
355 This also creates two targets for translations
356 `help-$project-update-po` and `help-$project-pot`.
357
358 * `languages`: *(deprecated since 0.43.0)* list of languages for translation, overrides the LINGUAS file
359 * `media`: list of media such as images
360 * `sources`: list of pages
361 * `symlink_media`: if media should be symlinked not copied (defaults to `true` since 0.42.0)
362
363 Note that very old versions of yelp may not support symlinked media;
364 At least 3.10 should work.
365
366 *Added 0.36.0*
367
368 ### gnome.gtkdoc()
369
370 Compiles and installs gtkdoc documentation into
371 `prefix/share/gtk-doc/html`. Takes one positional argument: The name
372 of the module.
373
374 * `content_files`: a list of content files
375 * `dependencies`: a list of dependencies
376 * `fixxref_args`: a list of arguments to pass to `gtkdoc-fixxref`
377 * `gobject_typesfile`: a list of type files
378 * `include_directories`: extra include paths to pass to `gtkdoc-scangobj`
379 * `ignore_headers`: a list of header files to ignore
380 * `html_assets`: a list of assets for the HTML pages
381 * `html_args` a list of arguments to pass to `gtkdoc-mkhtml`
382 * `install`: if true, installs the generated docs
383 * `install_dir`: the directory to install the generated docs relative
384 to the gtk-doc html dir or an absolute path (default: module name)
385 * `main_xml`: specifies the main XML file
386 * `main_sgml`: equal to `main_xml`
387 * `mkdb_args`: a list of arguments to pass to `gtkdoc-mkdb`
388 * `namespace`: specifies the name space to pass to `gtkdoc-mkdb`
389 * `module_version`: the version of the module, affects the installed location and the devhelp2 file location
390 * `scan_args`: a list of arguments to pass to `gtkdoc-scan`
391 * `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj`
392 * `c_args`: (*Added 0.48.0*) additional compile arguments to pass
393 * `src_dir`: include_directories to include
394 * `check`: (*Since 0.52.0*) if `true` runs `gtkdoc-check` when running unit tests.
395 Note that this has the downside of rebuilding the doc for each build, which is
396 often very slow. It usually should be enabled only in CI.
397
398 This also creates a `$module-doc` target that can be run to build
399 documentation. Normally the documentation is only built on install.
400
401 *Since 0.52.0* Returns a target object that can be passed as
402 dependency to other targets using generated doc files (e.g. in
403 `content_files` of another doc).
404
405 ### gnome.gtkdoc_html_dir()
406
407 Takes as argument a module name and returns the path where that
408 module's HTML files will be installed. Usually used with
409 `install_data` to install extra files, such as images, to the output
410 directory.
411
412 ### gnome.post_install()
413
414 *Since 0.57.0*
415
416 Post-install update of various system wide caches. Each script will be executed
417 only once even if `gnome.post_install()` is called multiple times from multiple
418 subprojects. If `DESTDIR` is specified during installation all scripts will be
419 skipped.
420
421 It takes the following keyword arguments:
422 - `glib_compile_schemas`: If set to `true`, update `gschemas.compiled` file in
423 `<prefix>/<datadir>/glib-2.0/schemas`.
424 - `gio_querymodules`: List of directories relative to `prefix` where
425 `giomodule.cache` file will be updated.
426 - `gtk_update_icon_cache`: If set to `true`, update `icon-theme.cache` file in
427 `<prefix>/<datadir>/icons/hicolor`.
428 - `update_desktop_database`: *Since 0.59.0* If set to `true`, update cache of
429 MIME types handled by desktop files in `<prefix>/<datadir>/applications`.
430 - `update_mime_database`: *Since 0.64.0* If set to `true`, update cache of
431 MIME types in `<prefix>/<datadir>/mime`.