diff options
Diffstat (limited to 'meson/docs/markdown/Gnome-module.md')
| -rw-r--r-- | meson/docs/markdown/Gnome-module.md | 378 |
1 files changed, 378 insertions, 0 deletions
diff --git a/meson/docs/markdown/Gnome-module.md b/meson/docs/markdown/Gnome-module.md new file mode 100644 index 000000000..2b90e0ceb --- /dev/null +++ b/meson/docs/markdown/Gnome-module.md @@ -0,0 +1,378 @@ +# GNOME module + +This module provides helper tools for build operations needed when +building Gnome/GLib programs. + +**Note**: the compilation commands here might not work properly when + you change the source files. This is a bug in the respective + compilers which do not expose the required dependency + information. This has been reported upstream in [this bug]. Until + this is fixed you need to be careful when changing your source + files. + + [this bug]: https://bugzilla.gnome.org/show_bug.cgi?id=745754 + +## Usage + +To use this module, just do: **`gnome = import('gnome')`**. The +following functions will then be available as methods on the object +with the name `gnome`. You can, of course, replace the name `gnome` +with anything else. + +### gnome.compile_resources() + +This function compiles resources specified in an XML file into code +that can be embedded inside the main binary. Similar a build target it +takes two positional arguments. The first one is the name of the +resource and the second is the XML file containing the resource +definitions. If the name is `foobar`, Meson will generate a header +file called `foobar.h`, which you can then include in your sources. + +* `c_name`: passed to the resource compiler as an argument after + `--c-name` +* `dependencies`: extra targets to depend upon for building +* `export`: (*Added 0.37.0*) if true, export the symbols of the + generated sources +* `extra_args`: extra command line arguments to pass to the resource +* `gresource_bundle`: (*Added 0.37.0*) if true, output a `.gresource` + file instead of source +* `install`: (*Added 0.37.0*) if true, install the gresource file +* `install_dir`: (*Added 0.37.0*) location to install the header or + bundle depending on previous options +* `install_header`: (*Added 0.37.0*) if true, install the header file +* `source_dir`: a list of directories where the resource compiler + should look up the files + +Returns an array containing: `[c_source, header_file]` or +`[gresource_bundle]` + +Example: + +```meson +gnome = import('gnome') + +asresources = gnome.compile_resources( + 'as-resources', 'data/asresources.gresource.xml', + source_dir: 'data', + c_name: 'as' +) + +executable( + meson.project_name(), + asresources, + dependencies: my_deps, + install: true +) +``` + +### gnome.generate_gir() + +Generates GObject introspection data. + +Takes one or more positional arguments: + +Either one or more library objects you want to build gir data for, or a single +executable object. + +There are several keyword arguments. Many of these map directly to the +`g-ir-scanner` tool so see its documentation for more information. + +* `dependencies`: deps to use during introspection scanning +* `extra_args`: command line arguments to pass to gir compiler +* `export_packages`: extra packages the gir file exports +* `sources`: the list of sources to be scanned for gir data +* `nsversion`: namespace version +* `namespace`: the namespace for this gir object which determines + output files +* `identifier_prefix`: the identifier prefix for the gir object, + e.g. `Gtk` +* `includes`: list of gir names to be included, can also be a GirTarget +* `header`: *(Added 0.43.0)* name of main c header to include for the library, e.g. `glib.h` +* `include_directories`: extra include paths to look for gir files +* `install`: if true, install the generated files +* `install_dir_gir`: (*Added 0.35.0*) which directory to install the + gir file into +* `install_dir_typelib`: (*Added 0.35.0*) which directory to install + the typelib file into +* `link_with`: list of libraries to link with +* `symbol_prefix`: the symbol prefix for the gir object, e.g. `gtk`, + (*Since 0.43.0*) an ordered list of multiple prefixes is allowed +* `fatal_warnings`: *Since 0.55.0* turn scanner warnings into fatal errors. + +Returns an array of two elements which are: `[gir_target, +typelib_target]` + +### gnome.genmarshal() + +Generates a marshal file using the `glib-genmarshal` tool. The first +argument is the basename of the output files. + +* `extra_args`: (*Added 0.42.0*) additional command line arguments to + pass +* `install_header`: if true, install the generated header +* `install_dir`: directory to install header to +* `nostdinc`: if true, don't include the standard marshallers from + glib +* `internal`: if true, mark generated sources as internal to + `glib-genmarshal` (*Requires GLib 2.54*) +* `prefix`: the prefix to use for symbols +* `skip_source`: if true, skip source location comments +* `stdinc`: if true, include the standard marshallers from glib +* `sources`: the list of sources to use as inputs +* `valist_marshallers`: if true, generate va_list marshallers + +*Added 0.35.0* + +Returns an array of two elements which are: `[c_source, header_file]` + +### gnome.mkenums() + +Generates enum files for GObject using the `glib-mkenums` tool. The +first argument is the base name of the output files, unless +`c_template` and `h_template` are specified. In this case, the output +files will be the base name of the values passed as templates. + +This method is essentially a wrapper around the `glib-mkenums` tool's +command line API. It is the most featureful method for enum creation. + +Typically you either provide template files or you specify the various +template sections manually as strings. + +Most libraries and applications will be using the same standard +template with only minor tweaks, in which case the +`gnome.mkenums_simple()` convenience method can be used instead. + +Note that if you `#include` the generated header in any of the sources +for a build target, you must add the generated header to the build +target's list of sources to codify the dependency. This is true for +all generated sources, not just `mkenums`. + +* `c_template`: template to use for generating the source +* `comments`: comment passed to the command +* `h_template`: template to use for generating the header +* `identifier_prefix`: prefix to use for the identifiers +* `install_header`: if true, install the generated header +* `install_dir`: directory to install the header +* `sources`: the list of sources to make enums with +* `symbol_prefix`: prefix to use for the symbols +* `eprod`: enum text +* `fhead`: file header +* `fprod`: file text +* `ftail`: file tail +* `vhead`: value text +* `vtail`: value tail + +*Added 0.35.0* + +Returns an array of two elements which are: `[c_source, header_file]` + +### gnome.mkenums_simple() + +Generates enum `.c` and `.h` files for GObject using the +`glib-mkenums` tool with the standard template used by most +GObject-based C libraries. The first argument is the base name of the +output files. + +Note that if you `#include` the generated header in any of the sources +for a build target, you must add the generated header to the build +target's list of sources to codify the dependency. This is true for +all generated sources, not just `mkenums_simple`. + +* `body_prefix`: additional prefix at the top of the body file, + e.g. for extra includes +* `decorator`: optional decorator for the function declarations, + e.g. `GTK_AVAILABLE` or `GST_EXPORT` +* `function_prefix`: additional prefix for function names, e.g. in + case you want to add a leading underscore to functions used only + internally +* `header_prefix`: additional prefix at the top of the header file, + e.g. for extra includes (which may be needed if you specify a + decorator for the function declarations) +* `install_header`: if true, install the generated header +* `install_dir`: directory to install the header +* `identifier_prefix`: prefix to use for the identifiers +* `sources`: the list of sources to make enums with +* `symbol_prefix`: prefix to use for the symbols + +Example: + +```meson +gnome = import('gnome') + +my_headers = ['myheader1.h', 'myheader2.h'] +my_sources = ['mysource1.c', 'mysource2.c'] + +# will generate myenums.c and myenums.h based on enums in myheader1.h and myheader2.h +enums = gnome.mkenums_simple('myenums', sources : my_headers) + +mylib = library('my', my_sources, enums, + include_directories: my_incs, + dependencies: my_deps, + c_args: my_cargs, + install: true) +``` + +*Added 0.42.0* + +Returns an array of two elements which are: `[c_source, header_file]` + +### gnome.compile_schemas() + +When called, this method will compile the gschemas in the current +directory. Note that this is not for installing schemas and is only +useful when running the application locally for example during tests. + +* `build_by_default`: causes, when set to true, to have this target be + built by default, that is, when invoking plain `meson compile`, the default + value is true for all built target types +* `depend_files`: files ([`string`](Reference-manual.md#string-object), + [`files()`](Reference-manual.md#files), or + [`configure_file()`](Reference-manual.md#configure_file)) of + schema source XML files that should trigger a re-compile if changed. + +### gnome.gdbus_codegen() + +Compiles the given XML schema into gdbus source code. Takes two +positional arguments, the first one specifies the base name to use +while creating the output source and header and the second specifies +one XML file. + +* `sources`: list of XML files +* `interface_prefix`: prefix for the interface +* `namespace`: namespace of the interface +* `extra_args`: (*Added 0.47.0*) additional command line arguments to pass +* `autocleanup`: *(Added 0.47.0)* if set generates autocleanup code. Can be one of `none`, `objects` or `all` +* `object_manager`: *(Added 0.40.0)* if true generates object manager code +* `annotations`: *(Added 0.43.0)* list of lists of 3 strings for the annotation for `'ELEMENT', 'KEY', 'VALUE'` +* `docbook`: *(Added 0.43.0)* prefix to generate `'PREFIX'-NAME.xml` docbooks +* `build_by_default`: causes, when set to true, to have this target be + built by default, that is, when invoking plain `meson compile`, the default + value is true for all built target types +* `install_dir`: (*Added 0.46.0*) location to install the header or + bundle depending on previous options +* `install_header`: (*Added 0.46.0*) if true, install the header file + +Starting *0.46.0*, this function returns a list of at least two custom +targets (in order): one for the source code and one for the header. +The list will contain a third custom target for the generated docbook +files if that keyword argument is passed. + +Earlier versions return a single custom target representing all the +outputs. Generally, you should just add this list of targets to a top +level target's source list. + +Example: + +```meson +gnome = import('gnome') + +# The returned source would be passed to another target +gdbus_src = gnome.gdbus_codegen('example-interface', + sources: 'com.example.Sample.xml', + interface_prefix : 'com.example.', + namespace : 'Sample', + annotations : [ + ['com.example.Hello()', 'org.freedesktop.DBus.Deprecated', 'true'] + ], + docbook : 'example-interface-doc' +) +``` + +### gnome.generate_vapi() + +Creates a VAPI file from gir. The first argument is the name of the +library. + +* `gir_dirs`: extra directories to include for gir files +* `install`: if true, install the VAPI file +* `install_dir`: location to install the VAPI file (defaults to datadir/vala/vapi) +* `metadata_dirs`: extra directories to include for metadata files +* `packages`: VAPI packages that are depended upon +* `sources`: the gir source to generate the VAPI from +* `vapi_dirs`: extra directories to include for VAPI files + +Returns a custom dependency that can be included when building other +VAPI or Vala binaries. + +*Added 0.36.0* + +### gnome.yelp() + +Installs help documentation using Yelp. The first argument is the +project id. + +This also creates two targets for translations +`help-$project-update-po` and `help-$project-pot`. + +* `languages`: list of languages for translations +* `media`: list of media such as images +* `sources`: list of pages +* `symlink_media`: if media should be symlinked not copied (defaults to `true` since 0.42.0) + +Note that very old versions of yelp may not support symlinked media; +At least 3.10 should work. + +*Added 0.36.0* + +### gnome.gtkdoc() + +Compiles and installs gtkdoc documentation into +`prefix/share/gtk-doc/html`. Takes one positional argument: The name +of the module. + +* `content_files`: a list of content files +* `dependencies`: a list of dependencies +* `fixxref_args`: a list of arguments to pass to `gtkdoc-fixxref` +* `gobject_typesfile`: a list of type files +* `include_directories`: extra include paths to pass to `gtkdoc-scangobj` +* `ignore_headers`: a list of header files to ignore +* `html_assets`: a list of assets for the HTML pages +* `html_args` a list of arguments to pass to `gtkdoc-mkhtml` +* `install`: if true, installs the generated docs +* `install_dir`: the directory to install the generated docs relative + to the gtk-doc html dir or an absolute path (default: module name) +* `main_xml`: specifies the main XML file +* `main_sgml`: equal to `main_xml` +* `mkdb_args`: a list of arguments to pass to `gtkdoc-mkdb` +* `namespace`: specifies the name space to pass to `gtkdoc-mkdb` +* `module_version`: the version of the module, affects the installed location and the devhelp2 file location +* `scan_args`: a list of arguments to pass to `gtkdoc-scan` +* `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj` +* `c_args`: (*Added 0.48.0*) additional compile arguments to pass +* `src_dir`: include_directories to include +* `check`: (*Since 0.52.0*) if `true` runs `gtkdoc-check` when running unit tests. + Note that this has the downside of rebuilding the doc for each build, which is + often very slow. It usually should be enabled only in CI. + +This also creates a `$module-doc` target that can be run to build +documentation. Normally the documentation is only built on install. + +*Since 0.52.0* Returns a target object that can be passed as +dependency to other targets using generated doc files (e.g. in +`content_files` of another doc). + +### gnome.gtkdoc_html_dir() + +Takes as argument a module name and returns the path where that +module's HTML files will be installed. Usually used with +`install_data` to install extra files, such as images, to the output +directory. + +### gnome.post_install() + +*Since 0.57.0* + +Post-install update of various system wide caches. Each script will be executed +only once even if `gnome.post_install()` is called multiple times from multiple +subprojects. If `DESTDIR` is specified during installation all scripts will be +skipped. + +It takes the following keyword arguments: +- `glib_compile_schemas`: If set to `true`, update `gschemas.compiled` file in + `<prefix>/<datadir>/glib-2.0/schemas`. +- `gio_querymodules`: List of directories relative to `prefix` where + `giomodule.cache` file will be updated. +- `gtk_update_icon_cache`: If set to `true`, update `icon-theme.cache` file in + `<prefix>/<datadir>/icons/hicolor`. +- `update_desktop_database`: *Since 0.59.0* If set to `true`, update cache of + MIME types handled by desktop files in `<prefix>/<datadir>/applications`. |