From 15a4cf4d3fdf4f824d50b9250a6129756f294298 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 21 May 2019 18:08:02 +0100 Subject: [PATCH 1/5] Ensure that we use @basename@ in the glib-mkenums docs The documentation for @filename@ is not accurate either. --- docs/reference/gobject/glib-mkenums.xml | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml index 4c8641657..6017001f2 100644 --- a/docs/reference/gobject/glib-mkenums.xml +++ b/docs/reference/gobject/glib-mkenums.xml @@ -153,15 +153,16 @@ The same as @type@ with all letters uppercased (e.g. @filename@ -The name of the input file currently being processed (e.g. foo.h). +The full path of the input file currently being processed (e.g. /build/environment/project/src/foo.h). @basename@ -The base name of the input file currently being processed (e.g. foo.h). Typically -you want to use @basename@ in place of @filename@ in your templates, to improve the reproducibility of the build. (Since: 2.22) +The base name of the input file currently being processed (e.g. foo.h). +Typically you want to use @basename@ in place of @filename@ +in your templates, to improve the reproducibility of the build. (Since: 2.22) @@ -448,7 +449,7 @@ G_BEGIN_DECLS /*** BEGIN file-production ***/ -/* enumerations from "@filename@" */ +/* enumerations from "@basename@" */ /*** END file-production ***/ /*** BEGIN value-header ***/ @@ -473,7 +474,7 @@ file, similar to this: /*** END file-header ***/ /*** BEGIN file-production ***/ -/* enumerations from "@filename@" */ +/* enumerations from "@basename@" */ /*** END file-production ***/ /*** BEGIN value-header ***/ From 040803b34df400a6b6006187b3d489a51704d81d Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 21 May 2019 18:10:24 +0100 Subject: [PATCH 2/5] Add example of using glib-mkenums with Meson We're using Meson for GLib itself, and we recommend people to use it for their own projects, so it would be good to have our documentation present examples on how to use Meson with our tools. Let's move the template example into its own section while we're at it, since it's referenced by both Meson and Autotools examples. Fixes: #1783 --- docs/reference/gobject/glib-mkenums.xml | 168 +++++++++++++++++------- 1 file changed, 123 insertions(+), 45 deletions(-) diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml index 6017001f2..216b71749 100644 --- a/docs/reference/gobject/glib-mkenums.xml +++ b/docs/reference/gobject/glib-mkenums.xml @@ -390,52 +390,15 @@ limit. For example, Windows has a limit of 8191 characters. -Using glib-mkenums with Autotools +Using templates -In order to use glib-mkenums in your project when using -Autotools as the build system, you will first need to modify your -configure.ac file to ensure you find the appropriate -command using pkg-config, similarly as to how you discover -the compiler and linker flags for GLib. +Instead of passing the various sections of the generated file to the command +line of glib-mkenums, it's strongly recommended to use a +template file, especially for generating C sources. - -PKG_PROG_PKG_CONFIG([0.28]) -PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums]) - -In your Makefile.am file you will typically use rules -like these: - - -# A list of headers to inspect -project_headers = \ - project-foo.h \ - project-bar.h \ - project-baz.h - -enum-types.h: $(project_headers) enum-types.h.in - $(AM_V_GEN)$(GLIB_MKENUMS) \ - --template=enum-types.h.in \ - --output=$@ \ - $(project_headers) - -enum-types.c: $(project_headers) enum-types.c.in enum-types.h - $(AM_V_GEN)$(GLIB_MKENUMS) \ - --template=enum-types.c.in \ - --output=$@ \ - $(project_headers) - -BUILT_SOURCES += enum-types.h enum-types.c -CLEANFILES += enum-types.h enum-types.c -EXTRA_DIST += enum-types.h.in enum-types.c.in - - -In the example above, we have a variable called project_headers -where we reference all header files we want to inspect for generating enumeration -GTypes. In the enum-types.h rule we use glib-mkenums -with a template called enum-types.h.in in order to generate the -header file; a header template file will typically look like this: +A C header template file will typically look like this: /*** BEGIN file-header ***/ @@ -461,10 +424,9 @@ GType @enum_name@_get_type (void) G_GNUC_CONST; G_END_DECLS /*** END file-tail ***/ + -The enum-types.c rule is similar to the rule for the -header file, but will use a different enum-types.c.in template -file, similar to this: +A C source template file will typically look like this: /*** BEGIN file-header ***/ @@ -506,6 +468,122 @@ GType /*** END value-tail ***/ + + +Template files are easier to modify and update, and can be used +to generate various types of outputs using the same command line +or tools during the build. + + + +Using glib-mkenums with Meson + +Meson supports generating enumeration types using glib-mkenums +out of the box in its "gnome" module. + + + +In your meson.build file you will typically call the +gnome.mkenums() method with a list of headers to inspect +and the template files to use: + + +project_headers = [ + 'project-foo.h', + 'project-bar.h', + 'project-baz.h', +] + +gnome = import('gnome') +enum_files = gnome.mkenums('enum-types', + sources: project_headers, + c_template: 'enum-types.c.in', + h_template: 'enum-types.h.in', +) + + + +The enum_files variable will contain an array of two elements +in the following order: + + + a build target for the source file + a build target for the header file + + +You should use the returned objects to provide a dependency on every other +build target that references the source or header file; for instance, if you +are using the source to build a library: + + +mainlib = library('project', + sources: project_sources + enum_files, + ... +) + + +Additionally, if you are including the generated header file inside a build +target that depends on the library you just built, you must ensure that the +internal dependency includes the generated header as a required source file: + + +mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib) + + +You should not include the generates source file, otherwise it will be built +twice. + + + +Using glib-mkenums with Autotools + +In order to use glib-mkenums in your project when using +Autotools as the build system, you will first need to modify your +configure.ac file to ensure you find the appropriate +command using pkg-config, similarly as to how you discover +the compiler and linker flags for GLib. + + +PKG_PROG_PKG_CONFIG([0.28]) + +PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums]) + + +In your Makefile.am file you will typically use rules +like these: + + +# A list of headers to inspect +project_headers = \ + project-foo.h \ + project-bar.h \ + project-baz.h + +enum-types.h: $(project_headers) enum-types.h.in + $(AM_V_GEN)$(GLIB_MKENUMS) \ + --template=enum-types.h.in \ + --output=$@ \ + $(project_headers) + +enum-types.c: $(project_headers) enum-types.c.in enum-types.h + $(AM_V_GEN)$(GLIB_MKENUMS) \ + --template=enum-types.c.in \ + --output=$@ \ + $(project_headers) + +# Build the enum types files before every other target +BUILT_SOURCES += enum-types.h enum-types.c +CLEANFILES += enum-types.h enum-types.c +EXTRA_DIST += enum-types.h.in enum-types.c.in + + +In the example above, we have a variable called project_headers +where we reference all header files we want to inspect for generating enumeration +GTypes. In the enum-types.h rule we use glib-mkenums +with a template called enum-types.h.in in order to generate the +header file; similarly, in the enum-types.c rule we use a +template called enum-types.c.in. + See also From 79cdd531d02fab6d6bbbc84eb521dbec93c1c2d8 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 21 May 2019 18:21:03 +0100 Subject: [PATCH 3/5] Add example of using glib-genmarshal with Meson We're using Meson for GLib itself, and we recommend people to use it for their own projects, so it would be good to have our documentation present examples on how to use Meson with our tools. --- docs/reference/gobject/glib-genmarshal.xml | 41 +++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/docs/reference/gobject/glib-genmarshal.xml b/docs/reference/gobject/glib-genmarshal.xml index bf72ba7fe..039953599 100644 --- a/docs/reference/gobject/glib-genmarshal.xml +++ b/docs/reference/gobject/glib-genmarshal.xml @@ -411,7 +411,46 @@ debugging information. This option is mutually exclusive with the -Using glib-genmarshal with Autotools +Using <command>glib-genmarshal</command> with Meson + +Meson supports generating closure marshallers using glib-genmarshal +out of the box in its "gnome" module. + + + +In your meson.build file you will typically call the +gnome.genmarshal() method with the source list of marshallers +to generate: + + +gnome = import('gnome') +marshal_files = gnome.genmarshal('marshal', + sources: 'marshal.list', + internal: true, +) + + +The marshal_files variable will contain an array of two elements +in the following order: + + + a build target for the source file + a build target for the header file + + +You should use the returned objects to provide a dependency on every other +build target that references the source or header file; for instance, if you +are using the source to build a library: + + +mainlib = library('project', + sources: project_sources + marshal_files, + ... +) + + + +Using <command>glib-genmarshal</command> with Autotools In order to use glib-genmarshal in your project when using Autotools as the build system, you will first need to modify your From 83c13e52d5df4d5a1853ee4c2e8f26b30a9b8c2e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 21 May 2019 18:25:34 +0100 Subject: [PATCH 4/5] docs: Mention Meson's gnome.mkenums_simple() The mkenums_simple() function generates idiomatic GObject code, and avoids templates and custom command line arguments. --- docs/reference/gobject/glib-mkenums.xml | 27 ++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml index 216b71749..adee4ecbe 100644 --- a/docs/reference/gobject/glib-mkenums.xml +++ b/docs/reference/gobject/glib-mkenums.xml @@ -484,8 +484,8 @@ out of the box in its "gnome" module. In your meson.build file you will typically call the -gnome.mkenums() method with a list of headers to inspect -and the template files to use: +gnome.mkenums_simple() method to generate idiomatic enumeration +types from a list of headers to inspect: project_headers = [ @@ -495,10 +495,8 @@ project_headers = [ ] gnome = import('gnome') -enum_files = gnome.mkenums('enum-types', +enum_files = gnome.mkenums_simple('enum-types', sources: project_headers, - c_template: 'enum-types.c.in', - h_template: 'enum-types.h.in', ) @@ -530,9 +528,24 @@ internal dependency includes the generated header as a required source file: mainlib_dep = declare_dependency(sources: enum_files[1], link_with: mainlib) -You should not include the generates source file, otherwise it will be built -twice. +You should not include the generated source file as well, otherwise it will +be built separately for every target that depends on it, causing build +failures. + + +If you are generating C header and source files that require special +templates, you can use gnome.mkenums() to provide those +headers, for instance: + + +enum_files = gnome.mkenums('enum-types', + sources: project_headers, + h_template: 'enum-types.h.in', + c_template: 'enum-types.c.in', + install_header: true, +) + Using glib-mkenums with Autotools From 653e0f0813f368a4d568c17dcc479eef8a340339 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 24 Feb 2020 15:05:46 +0000 Subject: [PATCH 5/5] Add links to Meson docs for genmarshal and mkenums --- docs/reference/gobject/glib-genmarshal.xml | 4 ++++ docs/reference/gobject/glib-mkenums.xml | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/reference/gobject/glib-genmarshal.xml b/docs/reference/gobject/glib-genmarshal.xml index 039953599..2b5ce0e9d 100644 --- a/docs/reference/gobject/glib-genmarshal.xml +++ b/docs/reference/gobject/glib-genmarshal.xml @@ -448,6 +448,10 @@ mainlib = library('project', ... ) + +For more information, see the Meson +documentation for gnome.genmarshal(). + Using <command>glib-genmarshal</command> with Autotools diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml index adee4ecbe..ef0d7347b 100644 --- a/docs/reference/gobject/glib-mkenums.xml +++ b/docs/reference/gobject/glib-mkenums.xml @@ -546,6 +546,10 @@ enum_files = gnome.mkenums('enum-types', install_header: true, ) + +For more information, see the Meson +documentation for gnome.mkenums(). + Using glib-mkenums with Autotools