Lines Matching +full:- +full:- +full:option
1 <refentry id="gdbus-codegen" lang="en">
17 <refentrytitle>gdbus-codegen</refentrytitle>
23 <refname>gdbus-codegen</refname>
24 <refpurpose>D-Bus code and documentation generator</refpurpose>
29 <command>gdbus-codegen</command>
30 <arg><option>-h</option>, <option>--help</option></arg>
31 <arg><option>--interface-prefix</option> <replaceable>org.project.Prefix</replaceable></arg>
32 <arg><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></arg>
33 <arg><option>--c-namespace</option> <replaceable>YourProject</replaceable></arg>
34 <arg><option>--c-generate-object-manager</option></arg>
35 <arg><option>--c-generate-autocleanup</option> none|objects|all</arg>
36 <arg><option>--output-directory</option> <replaceable>OUTDIR</replaceable></arg>
37 <arg><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></arg>
38 <arg><option>--pragma-once</option></arg>
39 <arg><option>--xml-files</option> <replaceable>FILE</replaceable></arg>
40 <arg><option>--header</option></arg>
41 <arg><option>--body</option></arg>
42 <arg><option>--interface-info-header</option></arg>
43 <arg><option>--interface-info-body</option></arg>
44 <arg><option>--symbol-decorator</option> <replaceable>DECORATOR</replaceable></arg>
45 <arg><option>--symbol-decorator-header</option> <replaceable>HEADER</replaceable></arg>
46 <arg><option>--symbol-decorator-define</option> <replaceable>DEFINE</replaceable></arg>
47 <arg><option>--output</option> <replaceable>OUTFILE</replaceable></arg>
50 <option>--annotate</option>
56 <arg><option>--glib-min-required</option> <replaceable>VERSION</replaceable></arg>
57 <arg><option>--glib-max-allowed</option> <replaceable>VERSION</replaceable></arg>
68 <command>gdbus-codegen</command> is used to generate code and/or
69 documentation for one or more D-Bus interfaces.
72 <command>gdbus-codegen</command> reads
74 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
78 <option>--body</option>) or header (via <option>--header</option>)
79 and Docbook XML (via <option>--generate-docbook</option>). Alternatively,
82 structures) using <option>--interface-info-body</option> and
83 <option>--interface-info-header</option>.
91 #GInterface<!-- -->-derived type is generated for each D-Bus
103 For C code generation either <option>--body</option> that
104 generates source code, <option>--header</option> that
105 generates headers, <option>--interface-info-body</option> that generates
107 <option>--interface-info-header</option> that generates interface information
109 <option>--output</option>, which is used to specify the file to output to.
113 <option>--generate-c-code</option>, but this option is deprecated.
114 In this case <option>--output</option> cannot be used due to the
116 <option>--output-directory</option> to specify the directory to put
120 The name of each generated C type is derived from the D-Bus
122 <option>--interface-prefix</option> and with the dots removed and
123 initial characters capitalized. For example, for the D-Bus
125 <literal>ComAcmeCoyote</literal>. For the D-Bus interface
127 <option>--interface-prefix</option>
136 Two forms of the name are used - the CamelCase form and the
137 lower-case form. The CamelCase form is used for the #GType and
138 struct name, while lower-case form is used in function names. The
139 lower-case form is calculated by converting from CamelCase to
140 lower-case and inserting underscores at word boundaries (using
145 annotation or the <option>--c-namespace</option> option contains
147 then the camel-case name is derived by removing all underscores,
148 and the lower-case name is derived by lower-casing the
153 <literal>iSCSITarget</literal> while the lower-case form is
156 <literal>Eject_The_iPod</literal>, the lower-case form is
165 <option>--generate-docbook</option> option for details) is a <ulink
167 article describing the D-Bus interface.
179 <term><option>-h</option>, <option>--help</option></term>
188 <term><option>--xml-files</option> <replaceable>FILE</replaceable></term>
191 This option is deprecated; use positional arguments instead.
192 The D-Bus introspection XML file.
198 … <term><option>--interface-prefix</option> <replaceable>org.project.Prefix.</replaceable></term>
201 A prefix to strip from all D-Bus interface names when
211 <term><option>--generate-docbook</option> <replaceable>OUTFILES</replaceable></term>
214 Generate Docbook Documentation for each D-Bus interface and
215 put it in <filename>OUTFILES-NAME.xml</filename> where
216 <literal>NAME</literal> is a place-holder for the interface
220 Pass <option>--output-directory</option> to specify the directory
228 <term><option>--generate-c-code</option> <replaceable>OUTFILES</replaceable></term>
231 Generate C code for all D-Bus interfaces and put it in
233 <filename>OUTFILES.h</filename> including any sub-directories. If you want the files to
234 …be output in a different location use <option>--output-directory</option> as <filename>OUTFILES.h<…
235 including sub-directories will be referenced from <filename>OUTFILES.c</filename>.
244 <term><option>--c-namespace</option> <replaceable>YourProject</replaceable></term>
256 <term><option>--pragma-once</option></term>
259 If this option is passed, the
267 <term><option>--c-generate-object-manager</option></term>
270 If this option is passed, suitable #GDBusObject,
278 <term><option>--c-generate-autocleanup</option> none|objects|all</term>
281 This option influences what types autocleanup functions are
287 This option was added in GLib 2.50.
293 <term><option>--output-directory</option> <replaceable>OUTDIR</replaceable></term>
299 This option cannot be used with <option>--body</option>,
300 <option>--header</option>, <option>--interface-info-body</option> or
301 <option>--interface-info-header</option>; and
302 <option>--output</option> must be used.
309 <term><option>--header</option></term>
312 If this option is passed, it will generate the header code and write it to the disk by
313 using the path and file name provided by <option>--output</option>.
316 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
317 <option>--output-directory</option> are not allowed to be used along with
318 <option>--header</option> and <option>--body</option> options, because these options
325 <term><option>--body</option></term>
328 If this option is passed, it will generate the source code and write it to the disk by
329 using the path and file name provided by <option>--output</option>.
332 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
333 <option>--output-directory</option> are not allowed to be used along with
334 <option>--header</option> and <option>--body</option> options, because these options
341 <term><option>--interface-info-header</option></term>
344 If this option is passed, it will generate the header code for the
347 <option>--output</option>.
350 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
351 <option>--output-directory</option> are not allowed to be used along with
352 the <option>--interface-info-header</option> and
353 <option>--interface-info-body</option> options, because these options
360 <term><option>--interface-info-body</option></term>
363 If this option is passed, it will generate the source code for the
366 <option>--output</option>.
369 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
370 <option>--output-directory</option> are not allowed to be used along with
371 the <option>--interface-info-header</option> and
372 <option>--interface-info-body</option> options, because these options
379 <term><option>--symbol-decorator</option> <replaceable>DECORATOR</replaceable></term>
382 If a <literal>DECORATOR</literal> is passed in with this option, all the
385 symbols from code generated with <command>gdbus-codegen</command>.
386 This option is added in GLib-2.66
392 <term><option>--symbol-decorator-header</option> <replaceable>HEADER</replaceable></term>
395 If a <literal>HEADER</literal> is passed in with this option, the
398 (if <option>--pragma-once</option> is used). This is used if using another header file is
399 needed for the decorator passed in via <option>--symbol-decorator</option> to be defined.
400 This option is added in GLib-2.66.
403 This option can only be used if <option>--symbol-decorator</option> is used.
409 <term><option>--symbol-decorator-define</option> <replaceable>DEFINE</replaceable></term>
412 If a <literal>DEFINE</literal> is passed in with this option, the
415 passed in via <option>--symbol-decorator</option> uses the correct definition when the
416 generated source is being compiled. This option is added in GLib-2.66.
419 This option can only be used if <option>--symbol-decorator</option> is used.
425 <term><option>--output</option> <replaceable>OUTFILE</replaceable></term>
428 The full path where the header (<option>--header</option>,
429 <option>--interface-info-header</option>) or the source code
430 (<option>--body</option>, <option>--interface-info-body</option>) will
432 <option>--output</option>. The full path could be something like
436 Using <option>--generate-c-code</option>, <option>--generate-docbook</option> or
437 <option>--output-directory</option> is not allowed along with
438 <option>--output</option>, because the latter is used to generate only one file.
444 …<term><option>--annotate</option> <replaceable>ELEMENT</replaceable> <replaceable>KEY</replaceable…
447 Used to inject D-Bus annotations into the given XML
452 gdbus-codegen --c-namespace MyApp \
453 --generate-c-code myapp-generated \
454 --annotate "org.project.InterfaceName" \
456 --annotate "org.project.InterfaceName:Property" \
458 --annotate "org.project.InterfaceName.Method()" \
460 --annotate "org.project.InterfaceName.Method()[arg_name]" \
462 --annotate "org.project.InterfaceName::Signal" \
464 --annotate "org.project.InterfaceName::Signal[arg_name]" \
466 myapp-dbus-interfaces.xml
469 …Any UTF-8 string can be used for <replaceable>KEY</replaceable> and <replaceable>VALUE</replaceabl…
475 <term><option>--glib-min-required</option> <replaceable>VERSION</replaceable></term>
479 <command>gdbus-codegen</command> can depend on. This may be used to
480 make backwards-incompatible changes in the output or behaviour of
481 <command>gdbus-codegen</command> in future, which users may opt in to
482 by increasing the value they pass for <option>--glib-min-required</option>.
483 If this option is not passed, the output from <command>gdbus-codegen</command>
485 upwards, as that is when <command>gdbus-codegen</command> was first
514 <term><option>--glib-max-allowed</option> <replaceable>VERSION</replaceable></term>
518 <command>gdbus-codegen</command> can depend on. This may be used to
519 ensure that code generated by <command>gdbus-codegen</command> is
528 be greater than or equal to that passed to <option>--glib-min-required</option>.
529 It defaults to the version of GLib which provides this <command>gdbus-codegen</command>.
538 <title>Supported D-Bus Annotations</title>
540 The following D-Bus annotations are supported by
541 <command>gdbus-codegen</command>:
557 url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus
584 version (any free-form string but compared using a
585 version-aware sort function) the element appeared in.
590 linkend="gdbus-code-stability"/>.
644 If set to a non-empty string, a #GVariant instance will
656 If set to a non-empty string, the generated code will
669 parser used by <command>gdbus-codegen</command> parses XML
671 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink>:
673 <!--
680 -->
682 <!--
688 -->
694 <!--
701 -->
707 <!-- BazProperty: The docs for the property. -->
739 Consider the following D-Bus Introspection XML.
761 If <command>gdbus-codegen</command> is used on this file like this:
764 gdbus-codegen --generate-c-code myapp-generated \
765 --c-namespace MyApp \
766 --interface-prefix net.corp.MyApp. \
771 <filename>myapp-generated.[ch]</filename> are
773 #GTypeInterface<!-- -->-derived type called
797 /* Signal handler for the ::handle-hello-world signal */
830 /* Emits the ::notification signal / Notification() D-Bus signal */
837 /* Gets the :verbose GObject property / Verbose D-Bus property.
842 /* Sets the :verbose GObject property / Verbose D-Bus property.
854 /* Client-side proxy constructors.
879 Thus, for every D-Bus method, there will be three C functions for
882 D-Bus signal, there's one #GObject signal and one C function for
883 emitting it. For every D-Bus property, two C functions are
916 <entry>Implement #GObject<!-- -->'s <function>get_property()</function> vfunc.</entry>
921 <entry>Implement #GObject<!-- -->'s <function>set_property()</function> vfunc.</entry>
928 <title>Client-side usage</title>
953 D-Bus method, connect to the
956 D-Bus signal and get/set the
957 <parameter>net.Corp.MyApp.Frobber:Verbose</parameter> D-Bus
965 Note that all property access is via #GDBusProxy<!-- -->'s
968 …<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties…
976 <title>Server-side usage</title>
994 the <function>::handle-*</function> signals and instead of
995 overriding #GObject<!-- -->'s
1034 "handle-hello-world",
1053 <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
1056 …url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.f…
1071 (type-strings
1072 <link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link>,
1073 <link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link>,
1074 <link linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link>,
1075 <link linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link>,
1076 <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>,
1077 <link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link>,
1078 <link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link>,
1079 <link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link> and
1080 <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link>)
1082 strings (type-strings
1083 <link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>,
1084 <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>,
1085 <link linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link> and
1086 <link linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link>) and
1087 arrays of string (type-strings
1088 <link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>,
1089 <link linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> and
1090 <link linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link>)
1099 <literal>org.gtk.GDBus.C.ForceGVariant</literal> - if used then a
1103 bytestrings (type-string <link linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link>)
1108 <refsect1 id="gdbus-code-stability">
1118 The ABI of the generated #GType<!-- -->s will be preserved only if
1122 a D-Bus method, property or signal or is added to a D-Bus
1130 url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> / <ulink
1137 While the generated Docbook for D-Bus interfaces isn't expected to