'\" t .\" Title: glib-genmarshal .\" Author: Emmanuele Bassi .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 04/04/2023 .\" Manual: User Commands .\" Source: GObject .\" Language: English .\" .TH "GLIB\-GENMARSHAL" "1" "" "GObject" "User Commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" glib-genmarshal \- C code marshaller generation utility for GLib closures .SH "SYNOPSIS" .HP \w'\fBglib\-genmarshal\fR\ 'u \fBglib\-genmarshal\fR [OPTION...] [FILE...] .SH "DESCRIPTION" .PP \fBglib\-genmarshal\fR is a small utility that generates C code marshallers for callback functions of the GClosure mechanism in the GObject sublibrary of GLib\&. The marshaller functions have a standard signature, they get passed in the invoking closure, an array of value structures holding the callback function parameters and a value structure for the return value of the callback\&. The marshaller is then responsible to call the respective C code function of the closure with all the parameters on the stack and to collect its return value\&. .PP \fBglib\-genmarshal\fR takes a list of marshallers to generate as input\&. The marshaller list is either read from files passed as additional arguments on the command line; or from standard input, by using \- as the input file\&. .SS "Marshaller list format" .PP The marshaller lists are processed line by line, a line can contain a comment in the form of .sp .if n \{\ .RS 4 .\} .nf # this is a comment .fi .if n \{\ .RE .\} or a marshaller specification of the form .sp .if n \{\ .RS 4 .\} .nf \fIRTYPE\fR:\fIPTYPE\fR \fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR \fIRTYPE\fR:\fIPTYPE\fR,\fIPTYPE\fR,\fIPTYPE\fR .fi .if n \{\ .RE .\} .PP The \fIRTYPE\fR part specifies the callback\*(Aqs return type and the \fIPTYPE\fRs right to the colon specify the callback\*(Aqs parameter list, except for the first and the last arguments which are always pointers\&. .SS "Parameter types" .PP Currently, the following types are supported: .PP \fIVOID\fR .RS 4 indicates no return type, or no extra parameters\&. If \fIVOID\fR is used as the parameter list, no additional parameters may be present\&. .RE .PP \fIBOOLEAN\fR .RS 4 for boolean types (gboolean) .RE .PP \fICHAR\fR .RS 4 for signed char types (gchar) .RE .PP \fIUCHAR\fR .RS 4 for unsigned char types (guchar) .RE .PP \fIINT\fR .RS 4 for signed integer types (gint) .RE .PP \fIUINT\fR .RS 4 for unsigned integer types (guint) .RE .PP \fILONG\fR .RS 4 for signed long integer types (glong) .RE .PP \fIULONG\fR .RS 4 for unsigned long integer types (gulong) .RE .PP \fIINT64\fR .RS 4 for signed 64bit integer types (gint64) .RE .PP \fIUINT64\fR .RS 4 for unsigned 64bit integer types (guint64) .RE .PP \fIENUM\fR .RS 4 for enumeration types (gint) .RE .PP \fIFLAGS\fR .RS 4 for flag enumeration types (guint) .RE .PP \fIFLOAT\fR .RS 4 for single\-precision float types (gfloat) .RE .PP \fIDOUBLE\fR .RS 4 for double\-precision float types (gdouble) .RE .PP \fISTRING\fR .RS 4 for string types (gchar*) .RE .PP \fIBOXED\fR .RS 4 for boxed (anonymous but reference counted) types (GBoxed*) .RE .PP \fIPARAM\fR .RS 4 for GParamSpec or derived types (GParamSpec*) .RE .PP \fIPOINTER\fR .RS 4 for anonymous pointer types (gpointer) .RE .PP \fIOBJECT\fR .RS 4 for GObject or derived types (GObject*) .RE .PP \fIVARIANT\fR .RS 4 for GVariant types (GVariant*) .RE .PP \fINONE\fR .RS 4 deprecated alias for \fIVOID\fR .RE .PP \fIBOOL\fR .RS 4 deprecated alias for \fIBOOLEAN\fR .RE .SH "OPTIONS" .PP \fB\-\-header\fR .RS 4 Generate header file contents of the marshallers\&. This option is mutually exclusive with the \fB\-\-body\fR option\&. .RE .PP \fB\-\-body\fR .RS 4 Generate C code file contents of the marshallers\&. This option is mutually exclusive with the \fB\-\-header\fR option\&. .RE .PP \fB\-\-prefix=\fR\fB\fIPREFIX\fR\fR .RS 4 Specify marshaller prefix\&. The default prefix is `g_cclosure_user_marshal\*(Aq\&. .RE .PP \fB\-\-skip\-source\fR .RS 4 Skip source location remarks in generated comments\&. .RE .PP \fB\-\-stdinc\fR .RS 4 Use the standard marshallers of the GObject library, and include glib\-object\&.h in generated header files\&. This option is mutually exclusive with the \fB\-\-nostdinc\fR option\&. .RE .PP \fB\-\-nostdinc\fR .RS 4 Do not use the standard marshallers of the GObject library, and skip glib\-object\&.h include directive in generated header files\&. This option is mutually exclusive with the \fB\-\-stdinc\fR option\&. .RE .PP \fB\-\-internal\fR .RS 4 Mark generated functions as internal, using G_GNUC_INTERNAL\&. .RE .PP \fB\-\-valist\-marshallers\fR .RS 4 Generate valist marshallers, for use with \fBg_signal_set_va_marshaller()\fR\&. .RE .PP \fB\-v\fR, \fB\-\-version\fR .RS 4 Print version information\&. .RE .PP \fB\-\-g\-fatal\-warnings\fR .RS 4 Make warnings fatal, that is, exit immediately once a warning occurs\&. .RE .PP \fB\-h\fR, \fB\-\-help\fR .RS 4 Print brief help and exit\&. .RE .PP \fB\-v\fR, \fB\-\-version\fR .RS 4 Print version and exit\&. .RE .PP \fB\-\-output=FILE\fR .RS 4 Write output to \fIFILE\fR instead of the standard output\&. .RE .PP \fB\-\-prototypes\fR .RS 4 Generate function prototypes before the function definition in the C source file, in order to avoid a missing\-prototypes compiler warning\&. This option is only useful when using the \fB\-\-body\fR option\&. .RE .PP \fB\-\-pragma\-once\fR .RS 4 Use the once pragma instead of an old style header guard when generating the C header file\&. This option is only useful when using the \fB\-\-header\fR option\&. .RE .PP \fB\-\-include\-header=\fR\fB\fIHEADER\fR\fR .RS 4 Adds a #include directive for the given file in the C source file\&. This option is only useful when using the \fB\-\-body\fR option\&. .RE .PP \fB\-D \fR\fB\fISYMBOL[=VALUE]\fR\fR .RS 4 Adds a #define C pre\-processor directive for \fISYMBOL\fR and its given \fIVALUE\fR, or "1" if the value is unset\&. You can use this option multiple times; if you do, all the symbols will be defined in the same order given on the command line, before the symbols undefined using the \fB\-U\fR option\&. This option is only useful when using the \fB\-\-body\fR option\&. .RE .PP \fB\-U \fR\fB\fISYMBOL\fR\fR .RS 4 Adds a #undef C pre\-processor directive to undefine the given \fISYMBOL\fR\&. You can use this option multiple times; if you do, all the symbols will be undefined in the same order given on the command line, after the symbols defined using the \fB\-D\fR option\&. This option is only useful when using the \fB\-\-body\fR option\&. .RE .PP \fB\-\-quiet\fR .RS 4 Minimizes the output of \fBglib\-genmarshal\fR, by printing only warnings and errors\&. This option is mutually exclusive with the \fB\-\-verbose\fR option\&. .RE .PP \fB\-\-verbose\fR .RS 4 Increases the verbosity of \fBglib\-genmarshal\fR, by printing debugging information\&. This option is mutually exclusive with the \fB\-\-quiet\fR option\&. .RE .SH "USING GLIB\-GENMARSHAL WITH MESON" .PP Meson supports generating closure marshallers using \fBglib\-genmarshal\fR out of the box in its "gnome" module\&. .PP In your meson\&.build file you will typically call the gnome\&.genmarshal() method with the source list of marshallers to generate: .sp .if n \{\ .RS 4 .\} .nf gnome = import(\*(Aqgnome\*(Aq) marshal_files = gnome\&.genmarshal(\*(Aqmarshal\*(Aq, sources: \*(Aqmarshal\&.list\*(Aq, internal: true, ) .fi .if n \{\ .RE .\} .PP The marshal_files variable will contain an array of two elements in the following order: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} a build target for the source file .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} a build target for the header file .RE .PP 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: .sp .if n \{\ .RS 4 .\} .nf mainlib = library(\*(Aqproject\*(Aq, sources: project_sources + marshal_files, \&.\&.\&. ) .fi .if n \{\ .RE .\} .PP 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: .sp .if n \{\ .RS 4 .\} .nf mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib) .fi .if n \{\ .RE .\} .PP 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\&. To know more about why all this is required, please refer to the \m[blue]\fBcorresponding Meson FAQ entry\fR\m[]\&\s-2\u[1]\d\s+2\&. .PP For more information on how to use the method, see the \m[blue]\fBMeson documentation for gnome\&.genmarshal()\fR\m[]\&\s-2\u[2]\d\s+2\&. .SH "USING GLIB\-GENMARSHAL WITH AUTOTOOLS" .PP In order to use \fBglib\-genmarshal\fR 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 \fBpkg\-config\fR, similarly as to how you discover the compiler and linker flags for GLib\&. .sp .if n \{\ .RS 4 .\} .nf PKG_PROG_PKG_CONFIG([0\&.28]) PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib\-2\&.0], [glib_genmarshal]) .fi .if n \{\ .RE .\} .PP In your Makefile\&.am file you will typically need very simple rules to generate the C files needed for the build\&. .sp .if n \{\ .RS 4 .\} .nf marshal\&.h: marshal\&.list $(AM_V_GEN)$(GLIB_GENMARSHAL) \e \-\-header \e \-\-output=$@ \e $< marshal\&.c: marshal\&.list marshal\&.h $(AM_V_GEN)$(GLIB_GENMARSHAL) \e \-\-include\-header=marshal\&.h \e \-\-body \e \-\-output=$@ \e $< BUILT_SOURCES += marshal\&.h marshal\&.c CLEANFILES += marshal\&.h marshal\&.c EXTRA_DIST += marshal\&.list .fi .if n \{\ .RE .\} .PP In the example above, the first rule generates the header file and depends on a marshal\&.list file in order to regenerate the result in case the marshallers list is updated\&. The second rule generates the source file for the same marshal\&.list, and includes the file generated by the header rule\&. .SH "EXAMPLE" .PP To generate marshallers for the following callback functions: .sp .if n \{\ .RS 4 .\} .nf void foo (gpointer data1, gpointer data2); void bar (gpointer data1, gint param1, gpointer data2); gfloat baz (gpointer data1, gboolean param1, guchar param2, gpointer data2); .fi .if n \{\ .RE .\} .PP The marshaller\&.list file has to look like this: .sp .if n \{\ .RS 4 .\} .nf VOID:VOID VOID:INT FLOAT:BOOLEAN,UCHAR .fi .if n \{\ .RE .\} .PP and you call glib\-genmarshal like this: .sp .if n \{\ .RS 4 .\} .nf glib\-genmarshal \-\-header marshaller\&.list > marshaller\&.h glib\-genmarshal \-\-body marshaller\&.list > marshaller\&.c .fi .if n \{\ .RE .\} .PP The generated marshallers have the arguments encoded in their function name\&. For this particular list, they are .sp .if n \{\ .RS 4 .\} .nf g_cclosure_user_marshal_VOID__VOID(\&.\&.\&.), g_cclosure_user_marshal_VOID__INT(\&.\&.\&.), g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(\&.\&.\&.)\&. .fi .if n \{\ .RE .\} .PP They can be used directly for GClosures or be passed in as the GSignalCMarshaller c_marshaller; argument upon creation of signals: .sp .if n \{\ .RS 4 .\} .nf GClosure *cc_foo, *cc_bar, *cc_baz; cc_foo = g_cclosure_new (NULL, foo, NULL); g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID); cc_bar = g_cclosure_new (NULL, bar, NULL); g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT); cc_baz = g_cclosure_new (NULL, baz, NULL); g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR); .fi .if n \{\ .RE .\} .SH "SEE ALSO" .PP \fBglib-mkenums\fR(1) .SH "NOTES" .IP " 1." 4 corresponding Meson FAQ entry .RS 4 \%https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers .RE .IP " 2." 4 Meson documentation for gnome.genmarshal() .RS 4 \%https://mesonbuild.com/Gnome-module.html#gnomegenmarshal .RE