| 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`. |