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.

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()

    gnome.compile_resources(id: string, input_file: string | File,
                            build_by_default: bool = false,
                            c_name: string | None = None,
                            dependencies: [](File, CustomTarget, CustomTargetIndex) = [],
                            export: bool = false,
                            extra_args: []string = [],
                            gresource_bundle: bool = false,
                            install_dir: string | None = None,
                            source_dir: [string] = [],
                            ): (CustomTarget, CustomTarget) | CustomTarget

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. The resources specified are automatically added as dependencies of the generated target.

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:

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
env: (Added 1.2.0) environment variables to set, such as {'NAME1': 'value1', 'NAME2': 'value2'} or ['NAME1=value1', 'NAME2=value2'], or an env object which allows more sophisticated environment juggling.
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_gir: (Added 0.61.0) overrides install, whether to install the generated gir
install_dir_gir: (Added 0.35.0) which directory to install the gir file into; (Deprecated since 0.61.0) can be false to disable installation
install_typelib: (Added 0.61.0) overrides install, whether to install the generated typelib
install_dir_typelib: (Added 0.35.0) which directory to install the typelib file into; (Deprecated since 0.61.0) can be false to disable installation
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.

depends [](BuildTarget | CustomTarget | CustomTargetIndex): passed directly to CustomTarget (since 0.61.0)
depend_files [](str | File): Passed directly to CustomTarget (since 0.61.0)
extra_args: (Added 0.42.0) additional command line arguments to pass
install_dir: directory to install header to
install_header: if true, install the generated header
install_dir: directory to install header to
install_header: if true, install the generated header
internal: if true, mark generated sources as internal to glib-genmarshal (Requires GLib 2.54)
nostdinc: if true, don't include the standard marshallers from glib
prefix: the prefix to use for symbols
skip_source: if true, skip source location comments
sources [](str | File) required: the list of sources to use as inputs
stdinc: if true, include the standard marshallers from glib
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.

The generated source file includes all headers passed to the sources keyword argument, using paths relative to current build or source directory. That means that targets that compile the generated source file must have the current directory in its include_directories. Since 1.3.0 sources outside of current directory do not require adding those directories into include_directories anymore.

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:

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 (str, files(), or 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:

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()

  gnome.yelp(id: string, sources: ...string, sources: []string, media: []string,
             languages: []string, symlink_media: bool = true): void

Installs help documentation for Yelp using itstool and gettext. The first argument is the project id.

Additionally, sources can be passed as additional positional arguments. This was, however, undocumented and never officially supported. Due to a longstanding bug, passing sources as a keyword argument will result in the positional argument sources to be ignored. since 0.60.0 A warning is raised in this case.

Since 0.43.0 if "languages" is not specified, a LINGUAS file will be read instead.

Since 0.60.0 the use of the positional argument sources has been deprecated, and the "sources" keyword argument should be used instead. The passing of sources as positional arguments will be removed in the future.

This also creates two targets for translations help-$project-update-po and help-$project-pot.

languages: (deprecated since 0.43.0) list of languages for translation, overrides the LINGUAS file
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.
update_mime_database: Since 0.64.0 If set to true, update cache of MIME types in <prefix>/<datadir>/mime.

The results of the search are

Edit on GitHub