From 539dfca540759b8a97e6906981d4240ca044af9f Mon Sep 17 00:00:00 2001 From: Christoph Reiter Date: Sun, 10 Jun 2018 11:24:47 +0200 Subject: Sphinx based user documentation The current output (more or less a straight copy of the wiki) is available here: https://gi.readthedocs.io This contains two changes: * Converts all (not completely outdated) wiki pages to a sphinx based documentation. * Converts the man pages to reST and adds a Makefile for building them using rst2man. So they can be easily exposed in the sphinx docs. Goals: * Have a user focused/compact documentation instead of random wiki pages with various todo/ideas pages. * Take advantage of the gitlab MR workflow by * allowing large documentation changes/refactorings with reviews * allowing to combine features changes with documentation changes in MRs --- docs/g-ir-compiler.1 | 78 +- docs/g-ir-generate.1 | 66 +- docs/g-ir-scanner.1 | 251 ++++--- docs/website/.gitignore | 1 + docs/website/Makefile | 10 + docs/website/annotations/giannotations.rst | 790 +++++++++++++++++++++ docs/website/annotations/gtkdoc.rst | 170 +++++ docs/website/annotations/index.rst | 10 + docs/website/architecture.rst | 64 ++ docs/website/buildsystems/autotoolsintegration.rst | 122 ++++ docs/website/buildsystems/index.rst | 10 + docs/website/buildsystems/meson.rst | 49 ++ docs/website/conf.py | 33 + docs/website/extra.css | 49 ++ docs/website/goals.rst | 72 ++ docs/website/images/architecture.svg | 120 ++++ docs/website/images/overview.svg | 540 ++++++++++++++ docs/website/index.rst | 71 ++ docs/website/tools/Makefile | 11 + docs/website/tools/g-ir-compiler.rst | 68 ++ docs/website/tools/g-ir-generate.rst | 54 ++ docs/website/tools/g-ir-scanner.rst | 171 +++++ docs/website/tools/index.rst | 21 + docs/website/users.rst | 52 ++ docs/website/writingbindableapis.rst | 163 +++++ docs/website/writingbindings/guidelines.rst | 45 ++ docs/website/writingbindings/index.rst | 10 + docs/website/writingbindings/libgirepository.rst | 15 + 28 files changed, 2965 insertions(+), 151 deletions(-) create mode 100644 docs/website/.gitignore create mode 100644 docs/website/Makefile create mode 100644 docs/website/annotations/giannotations.rst create mode 100644 docs/website/annotations/gtkdoc.rst create mode 100644 docs/website/annotations/index.rst create mode 100644 docs/website/architecture.rst create mode 100644 docs/website/buildsystems/autotoolsintegration.rst create mode 100644 docs/website/buildsystems/index.rst create mode 100644 docs/website/buildsystems/meson.rst create mode 100644 docs/website/conf.py create mode 100644 docs/website/extra.css create mode 100644 docs/website/goals.rst create mode 100644 docs/website/images/architecture.svg create mode 100644 docs/website/images/overview.svg create mode 100644 docs/website/index.rst create mode 100644 docs/website/tools/Makefile create mode 100644 docs/website/tools/g-ir-compiler.rst create mode 100644 docs/website/tools/g-ir-generate.rst create mode 100644 docs/website/tools/g-ir-scanner.rst create mode 100644 docs/website/tools/index.rst create mode 100644 docs/website/users.rst create mode 100644 docs/website/writingbindableapis.rst create mode 100644 docs/website/writingbindings/guidelines.rst create mode 100644 docs/website/writingbindings/index.rst create mode 100644 docs/website/writingbindings/libgirepository.rst (limited to 'docs') diff --git a/docs/g-ir-compiler.1 b/docs/g-ir-compiler.1 index c2197b44..65c439bb 100644 --- a/docs/g-ir-compiler.1 +++ b/docs/g-ir-compiler.1 @@ -1,41 +1,77 @@ -.TH "g-ir-compiler" 1 -.nh +.\" Man page generated from reStructuredText. +. +.TH G-IR-COMPILER 1 "" "" "" .SH NAME -g-ir-compiler \- typelib compiler. +g-ir-compiler \- Typelib compiler +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. .SH SYNOPSIS -.B g-ir-compiler -[OPTION...] GIRFILE +.sp +\fBg\-ir\-compiler\fP [OPTION...] GIRFILE .SH DESCRIPTION -g-ir-compiler converts one or more GIR files into one or more typelib. -The output will be written to standard output unless the --output -is specified. +.sp +g\-ir\-compiler converts one or more GIR files into one or more typelib. The +output will be written to standard output unless the \fB\-\-output\fP is +specified. .SH OPTIONS +.INDENT 0.0 .TP -.B \--help +.B \-\-help Show help options .TP -.B \--output=FILENAME +.BI \-\-output\fB= FILENAME Save the resulting output in FILENAME. .TP -.B \--verbose +.B \-\-verbose Show verbose messages .TP -.B \--debug +.B \-\-debug Show debug messages .TP -.B \--includedir=DIRECTORY +.BI \-\-includedir\fB= DIRECTORY Adds a directory which will be used to find includes inside the GIR format. .TP -.B \--module=MODULE +.BI \-\-module\fB= MODULE FIXME .TP -.B \--shared-library=FILENAME -Specifies the shared library where the symbols in the typelib can be found. -The name of the library should not contain the ending shared library suffix. -.TP +.BI \-\-shared\-library\fB= FILENAME +Specifies the shared library where the symbols in the typelib can be +found. The name of the library should not contain the ending shared +library suffix. +.UNINDENT .SH BUGS -Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues. -.SH HOMEPAGE and CONTACT -http://live.gnome.org/GObjectIntrospection +.sp +Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP +.SH HOMEPAGE AND CONTACT +.sp +\fI\%http://live.gnome.org/GObjectIntrospection\fP .SH AUTHORS +.sp Mattias Clasen +.\" Generated by docutils manpage writer. +. diff --git a/docs/g-ir-generate.1 b/docs/g-ir-generate.1 index ffe4904a..fb07de75 100644 --- a/docs/g-ir-generate.1 +++ b/docs/g-ir-generate.1 @@ -1,29 +1,63 @@ -.TH "g-ir-generate" 1 -.nh +.\" Man page generated from reStructuredText. +. +.TH G-IR-GENERATE 1 "" "" "" .SH NAME -g-ir-generate \- typelib generator +g-ir-generate \- Typelib generator +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. .SH SYNOPSIS -.B g-ir-generate -[OPTION...] FILES... +.sp +\fBg\-ir\-generate\fP [OPTION...] FILES... .SH DESCRIPTION -g-ir-generate is an GIR generator, using the repository API. It generates -GIR files from a raw typelib or in a shared library (--shlib). -The output will be written to standard output unless the --output -is specified. +.sp +g\-ir\-generate is an GIR generator, using the repository API. It generates GIR +files from a raw typelib or in a shared library (\fB\-\-shlib\fP). The output will +be written to standard output unless the \fB\-\-output\fP is specified. .SH OPTIONS +.INDENT 0.0 .TP -.B \, --help +.B \-\-help Show help options .TP -.B \, --shlib=FILENAME +.BI \-\-shlib\fB= FILENAME The shared library to read the symbols from. .TP -.B \, --output=FILENAME +.BI \-\-output\fB= FILENAME Save the resulting output in FILENAME. -.TP +.UNINDENT .SH BUGS -Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues. -.SH HOMEPAGE and CONTACT -http://live.gnome.org/GObjectIntrospection +.sp +Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP +.SH HOMEPAGE AND CONTACT +.sp +\fI\%http://live.gnome.org/GObjectIntrospection\fP .SH AUTHORS +.sp Mattias Clasen +.\" Generated by docutils manpage writer. +. diff --git a/docs/g-ir-scanner.1 b/docs/g-ir-scanner.1 index d38241f1..2078d927 100644 --- a/docs/g-ir-scanner.1 +++ b/docs/g-ir-scanner.1 @@ -1,154 +1,177 @@ -.TH "g-ir-scanner" 1 -.nh +.\" Man page generated from reStructuredText. +. +.TH G-IR-SCANNER 1 "" "" "" .SH NAME -g-ir-scanner \- extracting C metadata from sources and headers +g-ir-scanner \- Extracting C metadata from sources and headers +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. .SH SYNOPSIS -.B g-ir-scanner -[OPTION...] FILES... +.sp +\fBg\-ir\-scanner\fP [OPTION...] FILES... .SH DESCRIPTION -g-ir-scanner is a tool which generates GIR XML files by parsing headers -and introspecting GObject based libraries. -It is usually invoked during the normal build step for a project and -the information is saved to disk and later installed, so that language bindings -and other applications can use it. -Header files and source files are passed in as arguments on the command line. -The suffix determines whether a file be treated as a source file (.c) or a -header file (.h). Currently only C based libraries are supported by the scanner. +.sp +g\-ir\-scanner is a tool which generates GIR XML files by parsing headers and +introspecting GObject based libraries. It is usually invoked during the normal +build step for a project and the information is saved to disk and later +installed, so that language bindings and other applications can use it. Header +files and source files are passed in as arguments on the command line. The +suffix determines whether a file be treated as a source file (.c) or a header +file (.h). Currently only C based libraries are supported by the scanner. .SH OPTIONS +.INDENT 0.0 .TP -.B \--help +.B \-\-help Show help options .TP -.B \--quiet +.B \-\-quiet If passed, do not print details of normal operation. .TP -.B \--warn-all +.B \-\-warn\-all Display warnings for public API which is not introspectable. .TP -.B \--warn-error +.B \-\-warn\-error Make warnings be fatal errors. .TP -.B \--format=FORMAT -This parameters decides which the resulting format will be used. -The default value is gir. +.BI \-\-format\fB= FORMAT +This parameters decides which the resulting format will be used. The +default value is gir. .TP -.B \--include=NAME +.BI \-\-include\fB= NAME Add the specified introspection dependency to the scanned namespace. -NAME is of the form NAMESPACE-VERSION, like Gtk-3.0. +NAME is of the form NAMESPACE\-VERSION, like Gtk\-3.0. .TP -.B \--include-uninstalled=PATH +.BI \-\-include\-uninstalled\fB= PATH Add the specified introspection dependency to the scanned namespace. -This differs from \--include in that it takes a file path, and -does not process the pkg-config dependencies (since they may not -be installed yet). +This differs from \fB\-\-include\fP in that it takes a file path, and does not +process the pkg\-config dependencies (since they may not be installed yet). .TP -.B \--add-include-path=PATH -Add a directory to the path which the scanner uses to find GIR files. -Can be used multiple times to specify multiple directories +.BI \-\-add\-include\-path\fB= PATH +Add a directory to the path which the scanner uses to find GIR files. Can +be used multiple times to specify multiple directories .TP -.B \-i, --library=LIBRARY +.BI \-i\fP,\fB \-\-library\fB= LIBRARY Specifies a library that will be introspected. This means that the -*_get_type() functions in it will be called for GObject data types. -The name of the library should not contain the leading lib prefix nor -the ending shared library suffix. +*_get_type() functions in it will be called for GObject data types. The +name of the library should not contain the leading lib prefix nor the +ending shared library suffix. .TP -.B \-L, --library-path=PATH -Include this directory when searching for a library. -This option can be specified multiple times to include more than one -directory to look for libraries in. +.BI \-L\fP,\fB \-\-library\-path\fB= PATH +Include this directory when searching for a library. This option can be +specified multiple times to include more than one directory to look for +libraries in. .TP -.B \-Idirectory +.BI \-I\fB directory Include this directory in the list of directories to be searched for -header files. You need to pass to the scanner all the directories -you'd normally pass to the compiler when using the specified source -files. +header files. You need to pass to the scanner all the directories you\(aqd +normally pass to the compiler when using the specified source files. .TP -.B \-n, --namespace=NAME +.BI \-n\fP,\fB \-\-namespace\fB= NAME The namespace name. This name should be capitalized, eg the first letter should be upper case. Examples: Gtk, Clutter, WebKit. .TP -.B \--no-libtool -Disable usage of libtool for compiling stub introspection binary. Use this +.B \-\-no\-libtool +Disable usage of libtool for compiling stub introspection binary. Use this if your build system does not require libtool. .TP -.B \--libtool -Full path to libtool executable. Typically used for Automake systems. +.B \-\-libtool +Full path to libtool executable. Typically used for Automake systems. .TP -.B \--nsversion=VERSION -The namespace version. For instance 1.0. This is usually the platform version, -eg 2.0 for Gtk+, not 2.12.7. +.BI \-\-nsversion\fB= VERSION +The namespace version. For instance 1.0. This is usually the platform +version, eg 2.0 for Gtk+, not 2.12.7. .TP -.B \-p, --program=PROGRAM +.BI \-p\fP,\fB \-\-program\fB= PROGRAM Specifies a binary that will be introspected. This means that the -*_get_type() functions in it will be called for GObject data types. -The binary must be modified to take a --introspect-dump= option, and -to pass the argument to this function to g_irepository_dump. +*_get_type() functions in it will be called for GObject data types. The +binary must be modified to take a \fB\-\-introspect\-dump=\fP option, and to pass +the argument to this function to g_irepository_dump. .TP -.B \--program-arg=ARG +.BI \-\-program\-arg\fB= ARG Additional argument to pass to program for introspection. .TP -.B \--identifier-prefix=PREFIX -This option may be specified multiple times. Each one -gives a prefix that will be stripped from all C identifiers. -If none specified, the namespace will be used. -Eg, an identifier prefix of -.B Foo -will export the identifier -.B typdef struct _FooBar FooBar; -as -.B Foo.Bar. -.TP -.B \--symbol-prefix=PREFIX -This option may be specified multiple times. Each one -gives a prefix that will be stripped from all C symbols. -Eg, an symbol prefix of -.B foo -will export the symbol -.B foo_bar_do_something -as -.B Foo.Bar.do_something. -.TP -.B \--accept-unprefixed -If specified, the scanner will accept identifiers and symbols which -do not match the namespace prefix. Try to avoid using this if possible. -.TP -.B \--output=FILENAME -Name of the file to output. Normally namespace + format extension. -Eg, GLib-2.0.gir. -.TP -.B \--pkg=PACKAGE -List of pkg-config packages to get compiler and linker flags from. -This option can be specified multiple times to include flags from -several pkg-config packages. -.TP -.B \--pkg-export=PACKAGE -List of pkg-config packages that are provided by the generated gir. -This option can be specified multiple times if the gir provides more -packages. -If not specified, the packages specified with --pkg= will be used. -.TP -.B \--verbose +.BI \-\-identifier\-prefix\fB= PREFIX +This option may be specified multiple times. Each one gives a prefix that +will be stripped from all C identifiers. If none specified, the namespace +will be used. Eg, an identifier prefix of Foo will export the identifier +typdef struct _FooBar FooBar; as Foo.Bar. +.TP +.BI \-\-symbol\-prefix\fB= PREFIX +This option may be specified multiple times. Each one gives a +prefix that will be stripped from all C symbols. Eg, an symbol +prefix of foo will export the symbol foo_bar_do_something as +Foo.Bar.do_something. +.TP +.B \-\-accept\-unprefixed +If specified, the scanner will accept identifiers and symbols which do not +match the namespace prefix. Try to avoid using this if possible. +.TP +.BI \-\-output\fB= FILENAME +Name of the file to output. Normally namespace + format extension. Eg, +GLib\-2.0.gir. +.TP +.BI \-\-pkg\fB= PACKAGE +List of pkg\-config packages to get compiler and linker flags from. This +option can be specified multiple times to include flags from several +pkg\-config packages. +.TP +.BI \-\-pkg\-export\fB= PACKAGE +List of pkg\-config packages that are provided by the generated gir. This +option can be specified multiple times if the gir provides more packages. +If not specified, the packages specified with \fB\-\-pkg=\fP will be used. +.TP +.B \-\-verbose Be verbose, include some debugging information. -.TP +.UNINDENT .SH ENVIRONMENT VARIABLES -The g-ir-scanner uses the XDG_DATA_DIRS variable to check for dirs, -the girs are located in XDG_DATA_DIRS/gir-1.0. It is normally -set on a distribution so you shouldn't need to set it yourself. - -The variable GI_SCANNER_DISABLE_CACHE ensures that the scanner will -not write cache data to $HOME. - -The variable GI_SCANNER_DEBUG can be used to debug issues in the build-system that -involve g-ir-scanner. When it is set to 'save-temps', then g-ir-scanner will not remove -temporary files and directories after it terminates. - -The variable GI_HOST_OS can be used to control the OS name on the -host that runs the scanner. It has the same semantics as the Python -os.name property. +.sp +The g\-ir\-scanner uses the \fBXDG_DATA_DIRS\fP variable to check for dirs, the +girs are located in \fBXDG_DATA_DIRS/gir\-1.0\fP\&. It is normally set on a +distribution so you shouldn\(aqt need to set it yourself. +.sp +The variable \fBGI_SCANNER_DISABLE_CACHE\fP ensures that the scanner will not +write cache data to \fB$HOME\fP\&. +.sp +The variable \fBGI_SCANNER_DEBUG\fP can be used to debug issues in the +build\-system that involve g\-ir\-scanner. When it is set to \fBsave\-temps\fP, then +g\-ir\-scanner will not remove temporary files and directories after it +terminates. +.sp +The variable \fBGI_HOST_OS\fP can be used to control the OS name on the host +that runs the scanner. It has the same semantics as the Python \fBos.name\fP +property. .SH BUGS -Report bugs at https://gitlab.gnome.org/GNOME/gobject\-introspection/issues. -.SH HOMEPAGE and CONTACT -http://live.gnome.org/GObjectIntrospection +.sp +Report bugs at \fI\%https://gitlab.gnome.org/GNOME/gobject\-introspection/issues\fP +.SH HOMEPAGE AND CONTACT +.sp +\fI\%http://live.gnome.org/GObjectIntrospection\fP .SH AUTHORS +.sp Johan Dahlin - +.\" Generated by docutils manpage writer. +. diff --git a/docs/website/.gitignore b/docs/website/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/docs/website/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/website/Makefile b/docs/website/Makefile new file mode 100644 index 00000000..928ef6a3 --- /dev/null +++ b/docs/website/Makefile @@ -0,0 +1,10 @@ +all: _build + +_build: Makefile *.rst images/*.svg */*.rst conf.py + python3 -m sphinx -b html . _build + +linkcheck: + python3 -m sphinx -b linkcheck -n . _build + +clean: + rm -Rf _build diff --git a/docs/website/annotations/giannotations.rst b/docs/website/annotations/giannotations.rst new file mode 100644 index 00000000..cacc20de --- /dev/null +++ b/docs/website/annotations/giannotations.rst @@ -0,0 +1,790 @@ +GObject-Introspection annotations +--------------------------------- + +Symbol visibility +~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(skip)`` + - identifier + - Omit the symbol from the introspected output. + - :commit:`v0.6.4 <7549c8053d0229a12d9196cc8abae54a01a555d0>` + :bzbug:`556628` + * - + - paremeters, return value + - Indicate that the parameter or return value is only useful in C and + should be skipped. + - :commit:`v1.29.0 <9c6797e0478b5025c3f2f37b1331c1328cf34f4d>` + :bzbug:`649657` + * - ``(rename-to SYMBOL)`` + - identifier + - Rename the original symbol's name to ``SYMBOL``. If ``SYMBOL`` resolves + to a symbol name that is already used, the original binding for that + name is removed. + - :commit:`v0.6.3 <23e6fa6993c046de032598127ea48d4a7ee00935>` + :bzbug:`556475` + + +Memory and lifecycle management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(transfer MODE)`` + - identifier (only properties) + - Transfer ownership for the property, (see below) + - :commit:`v0.9.0 <22ae017ffd3052c0b81822b2ca6e41626b76b9c4>` + :bzbug:`620484` + * - + - parameters, return value + - Transfer mode for the parameter or return value (see below). + - v0.5.0 unknown + +Transfer modes: + +* ``none``: the recipient does not own the value +* ``container``: the recipient owns the container, but not the elements. + (Only meaningful for container types.) +* ``full``: the recipient owns the entire value. For a refcounted type, + this means the recipient owns a ref on the value. For a container type, + this means the recipient owns both container and elements. +* ``floating``: alias for none, can be used for floating objects. + +``container`` is usually a pointer to a list or hash table, eg GList, GSList, +GHashTable etc. + +``elements`` is what is contained inside the list: integers, strings, GObjects +etc. + + +Support for GObject objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(constructor)`` + - identifier + - The annotated symbol should not become available as a static methods + but as a constructor. + - :commit:`v0.10.2 <2c36790c>` + :bzbug:`561264` + * - ``(method)`` + - identifier + - This function is a method. + - :commit:`v0.10.2 <09bca85d>` + :bzbug:`639945` + * - ``(virtual SLOT)`` + - identifier + - This function is the invoker for a virtual method. + - :commit:`v0.6.3 ` + :bzbug:`557383` + + +Support for GObject closures +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(destroy)`` + - parameters + - The parameter is a "``destroy_data``" for callbacks. + - :commit:`v0.6.3 ` + :bzbug:`574284` + * - ``(destroy DESTROY)`` + - parameters + - The parameter is a "``destroy_data``" for callbacks, the + ``DESTROY`` option points to a paramter name other than + ``destroy_data``. + - + * - ``(closure)`` + - parameters + - The parameter is a "``user_data``" for callbacks. + Many bindings can pass ``NULL`` here. + - + * - ``(closure CLOSURE)`` + - parameters + - The parameter is a "``user_data``" for callbacks, the ``CLOSURE`` option + points to a different parameter that is the actual callback. + - + + +Support for non-GObject fundamental objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(ref-func FUNC)`` + - identifier + - ``FUNC`` is the function used to ref a struct, must be a GTypeInstance + - :commit:`v0.9.2 <1e9822c7>` + :bzbug:`568913` + * - ``(unref-func FUNC)`` + - identifier + - ``FUNC`` is the function used to unref a struct, must be a GTypeInstance + - + * - ``(get-value-func FUNC)`` + - identifier + - ``FUNC`` is the function used to convert a struct from a GValue, + must be a GTypeInstance + - + * - ``(set-value-func FUNC)`` + - identifier + - ``FUNC`` is the function used to convert from a struct to a GValue, + must be a GTypeInstance + - + + +Type signature +~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(nullable)`` + - parameters, return value + - Indicates that ``NULL`` may be a valid value for a parameter + (in, out, inout), or return value (though note that return values which + are only ``NULL`` when throwing an error should not be annotated as + ``(nullable)``). + - :commit:`1.42 <1459ff3e>` + :bzbug:`660879` + * - ``(not nullable)`` + - parameters, return value + - Indicates that ``NULL`` is not a valid value for a parameter + (in, out, inout), or return value. + - :commit:`1.48 <10cb665f>` + :bzbug:`729660` + * - ``(optional)`` + - parameters + - For ``(out)`` or ``(inout)`` parameters, signifies that the caller + can pass ``NULL`` to ignore this output parameter. + - :commit:`1.42 <1459ff3e>` + :bzbug:`660879` + * - ``(in)`` + - parameters + - In parameter. + - v0.5.0 + unknown + * - ``(out)`` + - parameters + - Out parameter (automatically determine allocation). + - v0.5.0 + unknown + * - ``(out caller-allocates)`` + - parameters + - Out parameter, where the calling code must allocate storage. + - :commit:`v0.6.13 <5589687a>` + :bzbug:`604749` + * - ``(out callee-allocates)`` + - parameters + - Out parameter, where the receiving function must allocate storage. + - + * - ``(inout)`` + - parameters + - In/out parameter. + - v0.5.0 + unknown + * - ``(type TYPE)`` + - identifier + - Override the default type, used for properties + - :commit:`v0.6.2 <6de1b296>` + :bzbug:`546739` + * - + - parameters, return value + - override the parsed C type with given type + - + * - ``(array)`` + - parameters, return value + - Arrays. + - v0.5.0 + unknown + * - ``(array fixed-size=N)`` + - parameters, return value + - array of fixed length N + - v0.5.0 + unknown + * - ``(array length=PARAM)`` + - parameters, return value + - array, fetch the length from parameter PARAM + - v0.5.0 + unknown + * - ``(array zero-terminated=1)`` + - parameters, return value + - array which is NULL terminated + - :commit:`v0.6.0 ` + :bzbug:`557786` + * - ``(element-type TYPE)`` + - parameters, return value + - Specify the type of the element inside a container. + Can be used in combination with (array). + - v0.5.0 + unknown + * - ``(element-type KTYPE VTYPE)`` + - parameters, return value + - Specify the types of the keys and values in a dictionary-like container + (eg, ``GHashTable``). + - v0.5.0 + unknown + * - ``(foreign)`` + - identifier + - The annotated symbol is a foreign struct, meaning it is not available + in a g-i supported library. + - :commit:`v0.6.12 <1edeccd2>` + :bzbug:`619450` + * - ``(scope TYPE)`` + - parameters + - The parameter is a callback, the ``TYPE`` option indicates the lifetime + of the call. It is mainly used by language bindings wanting to know when + the resources required to do the call (for instance ffi closures) can be + freed. + - :commit:`v0.6.2 ` + :bzbug:`556489` + +Scope types: + +* ``call`` (default) - Only valid for the duration of the call. + Can be called multiple times during the call. +* ``async`` - Only valid for the duration of the first callback invocation. + Can only be called once. +* ``notified`` - valid until the GDestroyNotify argument is called. + Can be called multiple times before the GDestroyNotify is called. + +An example of a function using the ``call`` scope is ``g_slist_foreach()``. +For ``async`` there is ``g_file_read_async()`` and for notified +``g_idle_add_full()``. + +Default Annotations: To avoid having the developers annotate everything the +introspection framework is providing sane default annotation values for a +couple of situations: + +* ``(in)`` parameters: ``(transfer none)`` +* ``(inout)`` and ``(out)`` parameters: ``(transfer full)`` + + * if ``(caller allocates)`` is set: ``(transfer none)`` + +* ``gchar*`` means ``(type utf8)`` +* return values: ``(transfer full)`` + + * ``gchar*`` means ``(type utf8) (transfer full)`` + * ``const gchar*`` means ``(type utf8) (transfer none)`` + * ``GObject*`` defaults to ``(transfer full)`` + + +Data annotations +~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(value VALUE)`` + - identifier + - Used to override constants for defined values, + VALUE contains the evaluated value + - v0.5.0 + unknown + * - ``(attributes my.key=val my.key2)`` + - identifier, parameters, return value + - Attributes are free-form "key=value" annotations. When present, at least + one key has to be specified. Assigning values to keys is optional. + - :commit:`v0.9.0 <11cfe386>` + :bzbug:`571548` + + +Deprecated GObject-Introspection annotations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 1 10 1 + + * - Annotation + - Description + - Since + * - ``(null-ok)`` + - Replaced by ``(allow-none)`` + - :commit:`v0.6.0 ` + :bzbug:`557405` + * - ``(in-out)`` + - Replaced by ``(inout)`` + - :commit:`1.39.0 ` + :bzbug:`688897` + * - ``(allow-none)`` + - Replaced by ``(nullable)`` and ``(optional)`` + - :commit:`1.42 <1459ff3e>` + :bzbug:`660879` + + +Possible future GObject-Introspection annotations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These proposed additions are currently being discussed and in various stages +of development. + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 1 + + * - Annotation + - Applies to + - Description + - Since + * - ``(default VALUE)`` + - parameters + - Default value for a parameter. + - :bzbug:`558620` + * - ``(error-domains DOM1 DOM2)`` + - parameters + - Typed errors, similar to ``throws`` in Java. + - unknown + + +Default Basic Types +------------------- + +Basic types: + +* gpointer: pointer to anything +* gboolean:boolean +* gint[8,16,32,64]: integer +* guint[8,16,32,64]: unsigned integer +* glong: long +* gulong: unsigned long +* GType: a gtype +* gfloat: float +* gdouble: double +* utf8: string encoded in UTF-8, not containing any embedded nuls +* filename: filename string (see below) +* guint8 array: binary data + +Filename type: + +The filename type represents an utf-8 string on Windows and a zero terminated +guint8 array on Unix. It should be used for filenames, environment variables +and process arguments. + + +Reference to Object Instances +----------------------------- + +Instances: + +* Object: a GObject instance +* Gtk.Button: a Gtk.Button instance + + +Examples +-------- + +Transfer +~~~~~~~~ + +:: + + /** + * mylib_get_constant1: + * + * Returns: (transfer full): a constant, free when you used it + */ + gchar * + mylib_get_constant1 (void) + { + return g_strdup("a constant"); + } + +:: + + /** + * mylib_get_constant2: + * + * Returns: (transfer none): another constant + */ + const gchar * + mylib_get_string2 (void) + { + return "another constant"; + } + +:: + + /** + * mylib_get_string_list1: + * + * Returns: (element-type utf8) (transfer full): list of constants, + * free the list with g_slist_free and the elements with g_free when done. + */ + GSList * + mylib_get_string_list1 (void) + { + GSList *l = NULL; + l = g_slist_append (l, g_strdup ("foo")); + l = g_slist_append (l, g_strdup ("bar")); + return l; + } + +:: + + /** + * mylib_get_string_list2: + * + * Returns: (element-type utf8) (transfer container): list of constants + * free the list with g_slist_free when done. + */ + GSList * + mylib_get_string_list2 (void) + { + GSList *l = NULL; + l = g_slist_append (l, "foo"); + l = g_slist_append (l, "bar"); + return l; + } + + +Array length +~~~~~~~~~~~~ + +:: + + /** + * gtk_list_store_set_column_types: + * @store: a #GtkListStore + * @n_columns: Length of @types + * @types: (array length=n_columns): List of types + */ + void + gtk_list_store_set_column_types (GtkListStore *list_store, + gint n_columns, + GType *types); + + +Nullable parameters +~~~~~~~~~~~~~~~~~~~ + +A number of things are nullable by convention, which means that you do not +have to add a ``(nullable)`` annotation to your code for them to be marked as +nullable in a GIR file. If you need to mark a parameter or return value as not +nullable, use ``(not nullable)`` to override the convention. Conventionally, +the following are automatically nullable: + +* ``(closure)`` parameters and their corresponding user data parameters +* ``gpointer`` parameters and return types, unless also annotated with + ``(type)`` + +:: + + /** + * gtk_link_button_new_with_label: + * @uri: A URI + * @label: (nullable): A piece of text or NULL + */ + GtkWidget * + gtk_link_button_new_with_label (const gchar *uri, + const gchar *label); + +:: + + /** + * g_source_add_unix_fd: + * @source: a #GSource + * @fd: the fd to monitor + * @events: an event mask + * + * Returns: (not nullable): an opaque tag + */ + gpointer + g_source_add_unix_fd (GSource *source, + gint fd, + GIOCondition events); + + /** + * g_source_remove_unix_fd: + * @source: a #GSource + * @tag: (not nullable): the tag from g_source_add_unix_fd() + */ + void + g_source_remove_unix_fd (GSource *source, + gpointer tag); + + +G(S)List contained types +~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + /** + * gtk_container_get_children: + * @container: A #GtkContainer + * + * Returns: (element-type Gtk.Widget) (transfer container): List of #GtkWidget + */ + GList* + gtk_container_get_children (GtkContainer *container); + +:: + + /** + * FooBar:alist: (type GSList(NiceObj)) + * + * This property is a GSList of NiceObj GOjects. + */ + g_object_class_install_property (object_class, + FOO_BAR_PROP_ALIST, + g_param_spec_pointer ("alist", + "Alist", + "A list of nice objects", + G_PARAM_READWRITE)); + + +Direction +~~~~~~~~~ + +:: + + /** + * gtk_widget_get_size_request: + * @width: (out): Int to store width in + * @height: (out): Int to store height in + */ + + +Out parameters +~~~~~~~~~~~~~~ + +This is a callee-allocates example; the (out) annotation automatically infers +this from the fact that there's a double indirection on a structure parameter. + + +:: + + typedef struct _FooSubObj FooSubObj + + /** + * foo_obj_get_sub_obj: + * @obj: A #FooObj + * @subobj: (out): A #FooSubObj + * + * Get a sub object. + */ + void + foo_obj_get_sub_obj (FooObj *obj, + FooSubObj **subobj) + { + *subobj = foo_sub_object_new (); + } + +This is a caller-allocates example; the (out) annotation automatically infers +this from the fact that there's only a single indirection on a structure +parameter. + +:: + + typedef struct _FooIter FooIter; + + /** + * foo_obj_get_iter: + * @obj: A #FooObj + * @iter: (out): An iterator, will be initialized + * + * Get an iterator. + */ + void + foo_obj_get_iter (FooObj *obj, + FooIter *iter) + { + iter->state = 0; + } + +An example which demonstrates an (optional) parameter: an (out) parameter +where the caller can pass NULL if they don’t want to receive the (out) value. + +:: + + /** + * g_file_get_contents: + * @filename: name of a file to read contents from, in the GLib file name encoding + * @contents: (out): location to store an allocated string, use g_free() to free the returned string + * @length: (out) (optional): location to store length in bytes of the contents, or NULL + * @error: return location for a GError, or NULL + * + * [...] + * + * Returns: TRUE on success, FALSE if an error occurred + */ + gboolean g_file_get_contents (const gchar *filename, + gchar **contents, + gsize *length, + GError **error); + + /* this is valid because length has (optional) */ + g_file_get_contents ("/etc/motd", &motd, NULL, &error); // VALID + /* but this is not valid, according to those annotations */ + g_file_get_contents ("/etc/motd", NULL, NULL, &error); // NOT VALID + + +g_hash_table_iter_next() demonstrates the difference between (nullable) and +(optional) for (out) parameters. For an (out) parameter, (optional) indicates +that NULL may be passed by the caller to indicate they don’t want to receive +the (out) value. (nullable) indicates that NULL may be passed out by the +callee as the returned value. + +:: + + /** + * g_hash_table_iter_next: + * @iter: an initialized #GHashTableIter + * @key: (out) (optional): a location to store the key + * @value: (out) (optional) (nullable): a location to store the value + * + * [...] + * + * Returns: %FALSE if the end of the #GHashTable has been reached. + */ + gboolean + g_hash_table_iter_next (GHashTableIter *iter, + gpointer *key, + gpointer *value); + + /* this is valid because value and key have (optional) */ + g_hash_table_iter_next (iter, NULL, NULL); + + gpointer key, value; + g_hash_table_iter_next (iter, &key, &value); + + if (value == NULL) + /* this is valid because value has (nullable) */ + if (key == NULL) + /* this is NOT VALID because key does not have (nullable) */ + + +Rename to +~~~~~~~~~ + +Rename to is an advisory annotation. It's not required to fulfill the advisory +when generating or making a language binding. The way it is currently +implemented, if you rename a function to a name already in use, it will remove +the other binding. This is useful to eliminate unwanted/deprecated functions +from the binding. + +Another (currently unimplemented) use for the rename annotation would be +overloading; for example, overloading of constructors or, like in this +example, overloading a method to be both an asynchronous and a synchronous one +(depending on the amount and what kind of parameters). + +:: + + /** + * my_type_perform_async: (rename-to my_type_perform) + * @self: The this ptr + * @data: data + * @callback: callback when async operation finished + * @user_data: user_data for @callback + * + * Asynchronously perform + **/ + void + my_type_perform_async (MyType *self, gpointer data, + GFunc callback, + gpointer user_data); + + /** + * my_type_perform: + * @self: The this ptr + * @data: data + * + * Perform + **/ + void + my_type_perform (MyType *self, gpointer data); + +In a language supporting method overloading, because we advised to rename to +perform, and because we have another perform already, this could be bound like +this: + +:: + + class MyType { + public void perform (Pointer data) { } + public void perform (Pointer data, GFunc callback, Pointer user_data) { } + } + +However, currently the generated gir/typelib will only contain information +about my_type_perform_async, which will shadow (ie, remove) the binding of +my_type_perform. + + +Attributes +~~~~~~~~~~ + +Attributes are arbitrary key/value pairs that can be attached to almost any +item including classes, methods, signals, properties, parameters and return +values. These attributes appear in both the .gir and the .typelib files. +Attributes can serve as a mechanism for software higher in the toolchain. +Attributes are name-spaced using dot as a separator. At least one dot must +appear in the key name. + +:: + + /** + * my_frobnicator_poke_path: (attributes gdbus.method PokePath) + * @frobnicator: A #MyFrobnicator + * @object_path: (gdbus.signature o): An object path. + * + * Manipulate an object path. + * + * Returns: (gdbus.signature o): A new object path. Free with g_free(). + */ + gchar * + my_frobnicator_poke_path (MyFrobnicator *frobnicator, + const gchar *object_path) + + +Constants +~~~~~~~~~ + +:: + + /** + * MY_CONSTANT: (value 100) + * A constant. + */ + #define MY_CONSTANT 10 * 10 diff --git a/docs/website/annotations/gtkdoc.rst b/docs/website/annotations/gtkdoc.rst new file mode 100644 index 00000000..14057366 --- /dev/null +++ b/docs/website/annotations/gtkdoc.rst @@ -0,0 +1,170 @@ +===================== +GTK-Doc Format Primer +===================== + +GObject-Introspection annotations are built on top of GTK-Doc comment +blocks. These are plain old C comment blocks, but formatted in a special +way. Each GTK-Doc comment block starts with a ``/**`` on its own line +end ends with ``*/``, again on its own line. + +The basic format of a GTK-Doc comment block looks like this: + +:: + + /** + * identifier_name: (annotations) + * @parameter_name: (annotations): description + * + * symbol description + * + * tag_name: (annotations): description + */ + +As we can see, a GTK-Doc comment block can be broken down into a couple of +parts. Each part is built out of one or more fields, separated by a ``:`` +character. Each part has to start on its own line. Fields cannot span multiple +lines except the various ``description`` fields. + +The order in which parts are written is important. For example, putting a +``tag`` part before the ``symbol description`` part is invalid as it would +result in the symbol description to be mistaken for the tag description. + +In the above example we have: + +* the start of a GTK-Doc comment block on line 1 +* the identifier part on line 2 +* a parameter part on line 3 +* the symbol description on line 5 +* a tag part on line 7 +* the end of the comment block on line 8 + +identifier part +~~~~~~~~~~~~~~~ + +:: + + /** + * identifier_name: (annotations) + * ... + */ + +The identifier part is required as it identifies the symbol you want to +annotate. It is always written on the line immediately following the start of +your GTK-Doc comment block (``/**``). + +The ``identifier`` part is constructed from: + +* a required ``identifier_name`` field + + * different kinds of symbols that can be documented and annotated are + described in the GTK-Doc manual. + +* an optional ``annotations`` field + +parameter part +~~~~~~~~~~~~~~ + +:: + + /** + * ... + * @parameter_name: (annotations): description + * ... + */ + +The ``parameter`` part is optional. This means that there can be 0 or more +parameters, depending on the symbol you are annotating. + +``parameter`` parts are constructed from: + +* a required ``parameter_name`` which starts with a ``@`` character + + * this name should correspond with the parameter name of you function's + signature. + +* an optional ``annotations`` field +* a required description field (can be "empty") + + * can contain a single paragraph (multiple lines but no empty lines) of + text. + +Note that multiple ``parameter`` parts are never separated by an empty line. + +symbol description part +~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + /** + * ... + * + * symbol description + * ... + */ + +The ``symbol description`` part is optional. When present, it must always be +preceded with an empty line. It can contain multiple paragraphs (multiple +lines and empty lines) describing what the function, property, signal, enum or +constant does. + +tag part +~~~~~~~~ + +:: + + /** + * ... + * tag_name: (annotations)||value: description + * ... + */ + +The ``tag`` part is optional. There can be 0 or more tags, depending on the +symbol you are annotating. + +``tag`` parts are constructed from: + +* a required ``tag_name`` + + * There are only four valid tags: ``Returns``, ``Since``, ``Deprecated``, + and ``Stability``. + +* an optional ``annotations`` field (``Returns``) + **OR** + an optional ``value`` field (``Since``, ``Deprecated``, and ``Stability``) +* a required description field (can be "empty") + + * can contain multiple paragraphs (multiple lines and empty lines) of text. + +``tag`` parts can safely be preceded or followed by an empty line. + +Tags taking an optional ``value`` field accept the following values: + +.. list-table:: + :header-rows: 1 + :widths: 1 1 10 + + * - Tag + - Value field + - Description + * - ``Since`` + - ``VERSION`` + - This symbol was added in version ``VERSION``. + * - ``Deprecated`` + - ``VERSION`` + - This symbol has been deprecated since version ``VERSION``. + * - ``Stability`` + - ``Stable``, ``Unstable``, or ``Private`` + - An informal description of the stability level of this symbol. + + +GTK-Doc support +--------------- + +If GTK-Doc doesn't seem to understand your introspection annotations, you may +need to do two things: + +#. make sure you are running GTK-Doc >= v1.12 (also try latest version from + git) +#. add ```` + to your master GTK-Doc document; e.g. see the end of `tester-docs.xml + `__ diff --git a/docs/website/annotations/index.rst b/docs/website/annotations/index.rst new file mode 100644 index 00000000..8a522a7d --- /dev/null +++ b/docs/website/annotations/index.rst @@ -0,0 +1,10 @@ +=========== +Annotations +=========== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + gtkdoc + giannotations diff --git a/docs/website/architecture.rst b/docs/website/architecture.rst new file mode 100644 index 00000000..dce8a0a0 --- /dev/null +++ b/docs/website/architecture.rst @@ -0,0 +1,64 @@ +============ +Architecture +============ + +.. figure:: images/architecture.svg + :align: center + + +:: + + BUILD TIME: + + +-----------------------------------------------------------+ + | foo.c | + | foo.h | + | | + | Library sources, with type annotations | + +-----------------------------------------------------------+ + | | + gcc g-ir-scanner + | | + | V + | +------------------------+ + | | Foo.gir | + | | | + | | .gir | + | | | + | | XML file | + | | | + | | Invocation information | + | | Required .gir files | + | | API docs | + | | | + | +------------------------+ + | | + | g-ir-compiler + | | + DEPLOYMENT TIME: | + | | + V V + +-----------------------------+ +---------------------------+ + | libfoo.so | | Foo.typelib | + | | | | + | | | Binary version of the | + | ELF file | | invocation info and | + | | | required .typelib files | + | Machine code, plus | +---------------------------+ + | dynamic linkage information | A + | (DWARF debug data, etc) | | + +-----------------------------+ | + A | + | +---------------------------+ + | | libgirepository.so | + +-----------+ | | + | libffi.so | | Can read typelibs and | + | |<-------+------>| present them in a | + +-----------+ | | libffi-based way | + | | | + | +---------------------------+ + | + | + +----------------------------+ + | Specific language bindings | + +----------------------------+ diff --git a/docs/website/buildsystems/autotoolsintegration.rst b/docs/website/buildsystems/autotoolsintegration.rst new file mode 100644 index 00000000..6948833b --- /dev/null +++ b/docs/website/buildsystems/autotoolsintegration.rst @@ -0,0 +1,122 @@ +===================== +Autotools Integration +===================== + +The gobject-introspection package provides the following two macros for use in +your configure.ac file: + +GOBJECT_INTROSPECTION_CHECK([version]) + This macro adds a ``--enable-introspection=yes|no|auto`` configure + option which defaults to ``auto``. + + * ``auto`` - Will set ``HAVE_INTROSPECTION`` if gobject-introspection is available + and the version requirement is satisfied. + * ``yes`` - Will error out if gobject-introspection is missing or the version + requirement is not satisfied. ``HAVE_INTROSPECTION`` will always be true. + * ``no`` - Will never error out and ``HAVE_INTROSPECTION`` will always be false. + +GOBJECT_INTROSPECTION_REQUIRE([version]) + This macro does not add a configure option and behaves as if + ``--enable-introspection=yes``. + + +Example +------- + +You'll need to adapt this for the library you're adding introspection support +to. + +* configure.ac (or configure.in if no .ac file is used) + + .. code-block:: none + + GOBJECT_INTROSPECTION_CHECK([1.40.0]) + +* Makefile.am + + .. code-block:: none + + DISTCHECK_CONFIGURE_FLAGS = --enable-introspection + + or just add to the existing DISTCHECK_CONFIGURE_FLAGS + +* foo/Makefile.am - must be near the end (after CLEANFILES has been set) + + .. code-block:: none + + -include $(INTROSPECTION_MAKEFILE) + INTROSPECTION_GIRS = + INTROSPECTION_SCANNER_ARGS = --add-include-path=$(srcdir) --warn-all + INTROSPECTION_COMPILER_ARGS = --includedir=$(srcdir) + + if HAVE_INTROSPECTION + introspection_sources = $(libfoo_1_0_la_SOURCES) + + Foo-1.0.gir: libfoo-1.0.la + Foo_1_0_gir_INCLUDES = GObject-2.0 + Foo_1_0_gir_CFLAGS = $(INCLUDES) + Foo_1_0_gir_LIBS = libfoo-1.0.la + Foo_1_0_gir_FILES = $(introspection_sources) + INTROSPECTION_GIRS += Foo-1.0.gir + + girdir = $(datadir)/gir-1.0 + gir_DATA = $(INTROSPECTION_GIRS) + + typelibdir = $(libdir)/girepository-1.0 + typelib_DATA = $(INTROSPECTION_GIRS:.gir=.typelib) + + CLEANFILES += $(gir_DATA) $(typelib_DATA) + endif + + You can also check out a complete example at + https://gitlab.gnome.org/GNOME/gtk/blob/c0ba041c73214f82d2c32b2ca1fa8f3c388c6170/gtk/Makefile.am#L1571 + + +Makefile variable documentation +------------------------------- + +``INTROSPECTION_GIRS`` is the entry point, you should list all the gir files +you want to build there in the XXX-Y.gir format where X is the name of the gir +(for example Gtk) and Y is the version (for example 2.0). + +If output is Gtk-3.0.gir then you should name the variables like +``Gtk_3_0_gir_NAMESPACE``, ``Gtk_3_0_gir_VERSION`` etc. + +* Required variables: + + * ``FILES`` - C sources and headers which should be scanned + +* One of these variables are required: + + * ``LIBS`` - Library where the symbol represented in the gir can be found + * ``PROGRAM`` - Program where the symbol represented in the gir can be found + +* Optional variables, commonly used: + + * ``INCLUDES`` - Gir files to include without the .gir suffix, for instance + GLib-2.0, Gtk-3.0. This is needed for all libraries which you depend on + that provides introspection information. + * ``SCANNERFLAGS`` - Flags to pass in to the scanner, see g-ir-scanner(1) + for a list + * ``PACKAGES`` - list of pkg-config names which cflags are required to parse + the headers of this gir. Note that ``INCLUDES`` will already fetch the + packages and thus the cflags for all dependencies. + * ``EXPORT_PACKAGES`` - List of pkg-config names which are provided by this + Gir. + * ``CFLAGS`` - Flags to pass in to the parser when scanning headers. + Normally ``INCLUDES`` and ``PACKAGES`` will fetch the cflags for all + dependencies. This is normally used for project specific CFLAGS. + * ``LDFLAGS`` - Linker flags used by the scanner. Normally ``INCLUDES`` and + ``PACKAGES`` will fetch the ldflags for all dependencies. This is normally + used for project-specific LDFLAGS (for instance if you're building several + libraries and typelibs). + +* Optional variables, seldomly used: + + * ``NAMESPACE`` - Namespace of the gir, first letter capital, rest should be + lower case, for instance: 'Gtk', 'Clutter', 'ClutterGtk'. If not present + the namespace will be fetched from the gir filename, the part before the + first dash. For 'Gtk-3.0', namespace will be 'Gtk'. + * ``VERSION`` - Version of the gir, if not present, will be fetched from gir + filename, the part after the first dash. For 'Gtk-3.0', version will be + '3.0'. diff --git a/docs/website/buildsystems/index.rst b/docs/website/buildsystems/index.rst new file mode 100644 index 00000000..c15e592e --- /dev/null +++ b/docs/website/buildsystems/index.rst @@ -0,0 +1,10 @@ +======================== +Build System Integration +======================== + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + meson + autotoolsintegration diff --git a/docs/website/buildsystems/meson.rst b/docs/website/buildsystems/meson.rst new file mode 100644 index 00000000..9bb2504a --- /dev/null +++ b/docs/website/buildsystems/meson.rst @@ -0,0 +1,49 @@ +================= +Meson Integration +================= + +Support for generating GObject introspection data is included in Meson +directly and accessible through the ``gnome.generate_gir()`` function. See +the `meson documentation +`__ for details. + +For some real examples, see the meson build definitions of various GNOME +modules: + +Pango: + https://gitlab.gnome.org/GNOME/pango/blob/master/pango/meson.build + + .. code-block:: python + + pango_gir = gnome.generate_gir( + libpango, + sources: pango_sources + pango_headers + [ pango_enum_h ], + namespace: 'Pango', + nsversion: pango_api_version, + identifier_prefix: 'Pango', + symbol_prefix: 'pango', + export_packages: 'pango', + includes: [ 'GObject-2.0', 'cairo-1.0', ], + header: 'pango/pango.h', + install: true, + extra_args: gir_args, + ) + +json-glib: + https://gitlab.gnome.org/GNOME/json-glib/blob/master/json-glib/meson.build + + .. code-block:: python + + json_glib_gir = gnome.generate_gir( + json_lib, + sources: source_c + source_h + json_glib_enums + [ json_version_h ], + namespace: 'Json', + nsversion: json_api_version, + identifier_prefix: 'Json', + symbol_prefix: 'json', + export_packages: json_api_name, + includes: [ 'GObject-2.0', 'Gio-2.0', ], + header: 'json-glib/json-glib.h', + install: true, + extra_args: gir_args, + ) diff --git a/docs/website/conf.py b/docs/website/conf.py new file mode 100644 index 00000000..98a51412 --- /dev/null +++ b/docs/website/conf.py @@ -0,0 +1,33 @@ +# -*- coding: utf-8 -*- + +extensions = [ + 'sphinx.ext.extlinks', +] +source_suffix = '.rst' +master_doc = 'index' +exclude_patterns = ['_build'] + +html_theme = 'sphinx_rtd_theme' +html_show_copyright = False +project = "GObject Introspection" +html_title = project +highlight_language = 'c' + +html_theme_options = { + "display_version": False, +} + +html_static_path = [ + "extra.css", +] + +html_context = { + 'extra_css_files': [ + '_static/extra.css', + ], +} + +extlinks = { + 'bzbug': ('https://bugzilla.gnome.org/show_bug.cgi?id=%s', 'bz#'), + 'commit': ('https://gitlab.gnome.org/GNOME/gobject-introspection/commit/%s', ''), +} diff --git a/docs/website/extra.css b/docs/website/extra.css new file mode 100644 index 00000000..f8f6de81 --- /dev/null +++ b/docs/website/extra.css @@ -0,0 +1,49 @@ +h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend { + font-family: inherit; +} + +.wy-nav-content a:visited { + color: #3091d1; +} + +.wy-side-nav-search { + background-color: initial; +} + +.wy-nav-side, .wy-nav-top { + background-color: #272525; +} + +.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal { + color: #272525; +} + +.wy-side-nav-search input[type="text"] { + border-color: transparent; +} + +.wy-nav-content { + margin: initial; +} + +.rst-content div[role=navigation], footer { + font-size: 0.85em; + color: #999; +} + +.rst-content div[role=navigation] hr { + margin-top: 6px; +} + +footer hr { + margin-bottom: 6px; +} + +.rst-footer-buttons { + display: none; +} + +table td, table th { + white-space: normal !important; + line-height: 20px; +} diff --git a/docs/website/goals.rst b/docs/website/goals.rst new file mode 100644 index 00000000..a8ebe92e --- /dev/null +++ b/docs/website/goals.rst @@ -0,0 +1,72 @@ +===== +Goals +===== + +The introspection project has two major goals, and a variety of more minor +ones. + + +Two level applications - C and +------------------------------------------------------ + +It makes sense to build many kinds of applications using (at least) two +different levels and languages — one for the low level elements, interfacing +with the OS and/or the hardware; and one for the high level application logic. +C is good for graphics, multimedia, and lower level systems work. However, +writing complex software in C is difficult and error-prone. A managed runtime +such as `JavaScript `__, Python, Perl, +Java, Lua, .NET, Scheme etc. makes a lot of sense for non-fast-path +application logic such as configuration, layout, dialogs, etc. + + +.. note:: + + To achieve this goal you need to write your code using GObject convention. + For more information about that, see the `GObject tutorial + `__ + +Thus, one of the major goals of the GObject introspection project is to be a +convenient bridge between these two worlds, and allow you to choose the right +tool for the job, rather than being limited inside one or the other. With the +introspection project, you can write for example a ClutterActor or GtkWidget +subclass in C, and then without any additional work use that class inside the +high level language of your choice. + + +Sharing binding infrastructure work, and making the platform even more binding-friendly +--------------------------------------------------------------------------------------- + +Historically in GNOME, the core platform has been relatively binding-friendly, +but there are several details not captured in the C+GObject layer that +bindings have needed. For example, reference counting semantics and the item +type inside GList's. Up until now various language bindings such as Python, +Mono, java-gnome etc. had duplicated copies of hand-maintained metadata, and +this led to a situation where bindings tended to lag behind until these manual +fixups were done, or were simply wrong, and your application would crash when +calling a more obscure function. + +The introspection project solves this by putting all of the metadata inside +the GObject library itself, using annotations in the comments. This will lead +to less duplicate work from binding authors, and a more reliable experience +for binding consumers. + +Additionally, because the introspection build process will occur inside the +GObject libraries themselves, a goal is to encourage GObject authors to +consider shaping their APIs to be more binding friendly from the start, rather +than as an afterthought. + + +Additional goals and uses +------------------------- + +* API verification - Sometimes the API of a library in our stack changes by + accident. Usually by a less experienced developer making a change without + realizing it will break applications. Introspecting the available API in + each release of the library and comparing it to the last one makes it easy + to see what changed +* Documentation tools - The tools written inside of the GObjectIntrospection + can easily be reused to improve that problem. Essentially; replacing + gtk-doc. We want to document what we export so it makes sense to glue this + together with API verification mentioned above +* UI Designer infrastructure +* Serialization/RPC/DBus diff --git a/docs/website/images/architecture.svg b/docs/website/images/architecture.svg new file mode 100644 index 00000000..a5011db8 --- /dev/null +++ b/docs/website/images/architecture.svg @@ -0,0 +1,120 @@ + + + + GObject Introspection Architecture + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + GObject Introspection Architecture + 2012-02-13 + + + Antono Vasiljev + + + + + http://creativecommons.org/licenses/by-sa/3.0/ + + + English + + + GObject + GLib + GTK + Bindings + + + + + http://antono.info/ + + + + + + + + + + + + + foo.c + + libfoo.so + + + Foo.gir + + g-ir-scanner + gcc + + g-ir-compiler + Foo.typelib + bindings + libgirrepository.so + + libffi.so + + + + Deployment + Consumption + Development + + foo.vala + + valac + + + \ No newline at end of file diff --git a/docs/website/images/overview.svg b/docs/website/images/overview.svg new file mode 100644 index 00000000..f78e5398 --- /dev/null +++ b/docs/website/images/overview.svg @@ -0,0 +1,540 @@ + + + + + + + + + + + + image/svg+xml + + + + + + + + + Introspected GType's + + + Sources .c + + + + Headers .h + + + + + GIR - XML format withintrospectable metadataa language binding needfunction,class,enum,docstrings, struct fieldsetc + g-ir-scanner(1) + g-ir-compiler(1) + + + + + + Typelib - binaryformat for fastdisk-access andlow memory + + Build time + Runtime +   +   + How a language binding uses introspection + How a library enables introspection + + Typelib - mmap()shared betweenprocesses + + + libgirepository + + + + libffi + + + + + dlopen:ed library + + + + diff --git a/docs/website/index.rst b/docs/website/index.rst new file mode 100644 index 00000000..9b46fe5d --- /dev/null +++ b/docs/website/index.rst @@ -0,0 +1,71 @@ +===================== +GObject Introspection +===================== + +.. title:: Overview + +.. toctree:: + :hidden: + :titlesonly: + :maxdepth: 1 + + goals + architecture + users + writingbindableapis + buildsystems/index + annotations/index + writingbindings/index + tools/index + +GObject introspection is a middleware layer between C libraries (using +GObject) and language bindings. The C library can be scanned at compile time +and generate metadata files, in addition to the actual native C library. Then +language bindings can read this metadata and automatically provide bindings to +call into the C library. + +.. figure:: images/overview.svg + :width: 85% + :align: center + +The GI project consists of: + +* an XML format called GIR containing introspection information in a machine parseable format +* a Python package to create and parse the GIR format +* a scanner to generate GIR format from C source and headers +* a typelib similar to xpcom/msole which stores the information on disk in a binary format +* a compiler to compile the typelib from a xml format (and vice versa) +* C library to read the typelib, :doc:`writingbindings/libgirepository`. + + +Getting the code +---------------- + +The latest stable release is available from +https://download.gnome.org/sources/gobject-introspection + +GObject Introspection is stored in git and can be fetched: + +.. code-block:: text + + git clone https://gitlab.gnome.org/GNOME/gobject-introspection.git + +You can browse the repository online `here `__. + + +Reporting bugs +-------------- + +For a list of existing bugs and feature requests, see the `issues page +`__. You can also +`open an issue +`__. + + +Contact +------- + +For questions or additional information, please use: + +* Mailing list: gtk-devel-list@gnome.org +* IRC: #introspection on irc.gnome.org diff --git a/docs/website/tools/Makefile b/docs/website/tools/Makefile new file mode 100644 index 00000000..6fb8baff --- /dev/null +++ b/docs/website/tools/Makefile @@ -0,0 +1,11 @@ +# update man pages + +all: ../../g-ir-compiler.1 ../../g-ir-generate.1 ../../g-ir-scanner.1 + +../../%.1:%.rst + rst2man $< > $@ + +.PHONY: clean + +clean: + rm -f ../../g-ir-compiler.1 ../../g-ir-generate.1 ../../g-ir-scanner.1 diff --git a/docs/website/tools/g-ir-compiler.rst b/docs/website/tools/g-ir-compiler.rst new file mode 100644 index 00000000..e87a9abd --- /dev/null +++ b/docs/website/tools/g-ir-compiler.rst @@ -0,0 +1,68 @@ +============= +g-ir-compiler +============= + +---------------- +Typelib compiler +---------------- + +:Manual section: 1 + + +SYNOPSIS +======== + +**g-ir-compiler** [OPTION...] GIRFILE + + +DESCRIPTION +=========== + +g-ir-compiler converts one or more GIR files into one or more typelib. The +output will be written to standard output unless the ``--output`` is +specified. + + +OPTIONS +======= + +--help + Show help options + +--output=FILENAME + Save the resulting output in FILENAME. + +--verbose + Show verbose messages + +--debug + Show debug messages + +--includedir=DIRECTORY + Adds a directory which will be used to find includes inside the GIR format. + +--module=MODULE + FIXME + +--shared-library=FILENAME + Specifies the shared library where the symbols in the typelib can be + found. The name of the library should not contain the ending shared + library suffix. + + +BUGS +==== + +Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues + + +HOMEPAGE and CONTACT +==================== + +http://live.gnome.org/GObjectIntrospection + + +AUTHORS +======= + +Mattias Clasen diff --git a/docs/website/tools/g-ir-generate.rst b/docs/website/tools/g-ir-generate.rst new file mode 100644 index 00000000..662ec10b --- /dev/null +++ b/docs/website/tools/g-ir-generate.rst @@ -0,0 +1,54 @@ +============= +g-ir-generate +============= + +----------------- +Typelib generator +----------------- + +:Manual section: 1 + + +SYNOPSIS +======== + +**g-ir-generate** [OPTION...] FILES... + + +DESCRIPTION +=========== + +g-ir-generate is an GIR generator, using the repository API. It generates GIR +files from a raw typelib or in a shared library (``--shlib``). The output will +be written to standard output unless the ``--output`` is specified. + + +OPTIONS +======= + +--help + Show help options + +--shlib=FILENAME + The shared library to read the symbols from. + +--output=FILENAME + Save the resulting output in FILENAME. + + +BUGS +==== + +Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues + + +HOMEPAGE and CONTACT +==================== + +http://live.gnome.org/GObjectIntrospection + + +AUTHORS +======= + +Mattias Clasen diff --git a/docs/website/tools/g-ir-scanner.rst b/docs/website/tools/g-ir-scanner.rst new file mode 100644 index 00000000..d59e7ccc --- /dev/null +++ b/docs/website/tools/g-ir-scanner.rst @@ -0,0 +1,171 @@ +============ +g-ir-scanner +============ + +---------------------------------------------- +Extracting C metadata from sources and headers +---------------------------------------------- + +:Manual section: 1 + + +SYNOPSIS +======== + +**g-ir-scanner** [OPTION...] FILES... + + +DESCRIPTION +=========== + +g-ir-scanner is a tool which generates GIR XML files by parsing headers and +introspecting GObject based libraries. It is usually invoked during the normal +build step for a project and the information is saved to disk and later +installed, so that language bindings and other applications can use it. Header +files and source files are passed in as arguments on the command line. The +suffix determines whether a file be treated as a source file (.c) or a header +file (.h). Currently only C based libraries are supported by the scanner. + + +OPTIONS +======= + +--help + Show help options + +--quiet + If passed, do not print details of normal operation. + +--warn-all + Display warnings for public API which is not introspectable. + +--warn-error + Make warnings be fatal errors. + +--format=FORMAT + This parameters decides which the resulting format will be used. The + default value is gir. + +--include=NAME + Add the specified introspection dependency to the scanned namespace. + NAME is of the form NAMESPACE-VERSION, like Gtk-3.0. + +--include-uninstalled=PATH + Add the specified introspection dependency to the scanned namespace. + This differs from ``--include`` in that it takes a file path, and does not + process the pkg-config dependencies (since they may not be installed yet). + +--add-include-path=PATH + Add a directory to the path which the scanner uses to find GIR files. Can + be used multiple times to specify multiple directories + +-i, --library=LIBRARY + Specifies a library that will be introspected. This means that the + \*_get_type() functions in it will be called for GObject data types. The + name of the library should not contain the leading lib prefix nor the + ending shared library suffix. + +-L, --library-path=PATH + Include this directory when searching for a library. This option can be + specified multiple times to include more than one directory to look for + libraries in. + +-Idirectory + Include this directory in the list of directories to be searched for + header files. You need to pass to the scanner all the directories you'd + normally pass to the compiler when using the specified source files. + +-n, --namespace=NAME + The namespace name. This name should be capitalized, eg the first letter + should be upper case. Examples: Gtk, Clutter, WebKit. + +--no-libtool + Disable usage of libtool for compiling stub introspection binary. Use this + if your build system does not require libtool. + +--libtool + Full path to libtool executable. Typically used for Automake systems. + +--nsversion=VERSION + The namespace version. For instance 1.0. This is usually the platform + version, eg 2.0 for Gtk+, not 2.12.7. + +-p, --program=PROGRAM + Specifies a binary that will be introspected. This means that the + \*_get_type() functions in it will be called for GObject data types. The + binary must be modified to take a ``--introspect-dump=`` option, and to pass + the argument to this function to g_irepository_dump. + +--program-arg=ARG + Additional argument to pass to program for introspection. + +--identifier-prefix=PREFIX + This option may be specified multiple times. Each one gives a prefix that + will be stripped from all C identifiers. If none specified, the namespace + will be used. Eg, an identifier prefix of Foo will export the identifier + typdef struct _FooBar FooBar; as Foo.Bar. + +--symbol-prefix=PREFIX + This option may be specified multiple times. Each one gives a + prefix that will be stripped from all C symbols. Eg, an symbol + prefix of foo will export the symbol foo_bar_do_something as + Foo.Bar.do_something. + +--accept-unprefixed + If specified, the scanner will accept identifiers and symbols which do not + match the namespace prefix. Try to avoid using this if possible. + +--output=FILENAME + Name of the file to output. Normally namespace + format extension. Eg, + GLib-2.0.gir. + +--pkg=PACKAGE + List of pkg-config packages to get compiler and linker flags from. This + option can be specified multiple times to include flags from several + pkg-config packages. + +--pkg-export=PACKAGE + List of pkg-config packages that are provided by the generated gir. This + option can be specified multiple times if the gir provides more packages. + If not specified, the packages specified with ``--pkg=`` will be used. + +--verbose + Be verbose, include some debugging information. + + +ENVIRONMENT VARIABLES +===================== + +The g-ir-scanner uses the ``XDG_DATA_DIRS`` variable to check for dirs, the +girs are located in ``XDG_DATA_DIRS/gir-1.0``. It is normally set on a +distribution so you shouldn't need to set it yourself. + +The variable ``GI_SCANNER_DISABLE_CACHE`` ensures that the scanner will not +write cache data to ``$HOME``. + +The variable ``GI_SCANNER_DEBUG`` can be used to debug issues in the +build-system that involve g-ir-scanner. When it is set to ``save-temps``, then +g-ir-scanner will not remove temporary files and directories after it +terminates. + +The variable ``GI_HOST_OS`` can be used to control the OS name on the host +that runs the scanner. It has the same semantics as the Python ``os.name`` +property. + + +BUGS +==== + +Report bugs at https://gitlab.gnome.org/GNOME/gobject-introspection/issues + + +HOMEPAGE and CONTACT +==================== + +http://live.gnome.org/GObjectIntrospection + + +AUTHORS +======= + +Johan Dahlin diff --git a/docs/website/tools/index.rst b/docs/website/tools/index.rst new file mode 100644 index 00000000..44897b6c --- /dev/null +++ b/docs/website/tools/index.rst @@ -0,0 +1,21 @@ +================== +Command Line Tools +================== + +.. toctree:: + :hidden: + :titlesonly: + :maxdepth: 1 + + g-ir-compiler + g-ir-generate + g-ir-scanner + +:doc:`g-ir-compiler` + Typelib compiler + +:doc:`g-ir-generate` + Typelib generator + +:doc:`g-ir-scanner` + Extracting C metadata from sources and headers diff --git a/docs/website/users.rst b/docs/website/users.rst new file mode 100644 index 00000000..ca7c133d --- /dev/null +++ b/docs/website/users.rst @@ -0,0 +1,52 @@ +===== +Users +===== + +Bindings based on GObject-Introspection +--------------------------------------- + +* `Vala `__ - Compiler for the GObject type system (compile time) +* `Genie `__ - Genie Language (compile time) +* `PyGObject `__ - Python bindings (runtime) +* `pygir-ctypes `__ - Pure Python GObject Introspection Repository (GIR) wrapper using ctypes (runtime) +* `pgi `__ - Pure Python GObject Introspection Bindings (runtime) +* `GTK2-Perl/Introspection `__ - Perl bindings (runtime) +* `JGIR `__ - Java/JVM bindings (compile time, using typelib) +* `GJS `__ - Javascript (spidermonkey) bindings (runtime) +* `Seed `__ - Javascript (JSCore, WebKit JS engine) bindings (runtime) +* `sbank `__ - Scheme binding for gobject-introspection (runtime) +* `GObjectIntrospection/GObjectConsume `__ - Qt bindings (compile time) +* `GirFFI `__ - Ruby bindings (runtime) +* `lgob `__ - Lua bindings (compile time?) +* `guile-gir `__ - Guile bindings (runtime) +* `factor-gir `__ - Factor bindings (runtime) +* `lgi `__ - Lua bindings (runtime) +* `GObject for PHP `__ +* `cl-gir `__ GIR for Common Lisp (work in progress) +* `GNU Smalltalk `__ - A branch of GNU Smalltalk which adds GObject Introspection bindings. +* `node-gir `__ - Node.js bindings to the girepository +* `go-gir-generator `__ - Go bindings (compile time) (Forked from `gogobject `__ which is unmaintained) +* `haskell-gi `__ - a Haskell binding for the GIRepository C library, and a Haskell code generator built upon it. It is very much a work in progress. +* `cl-gobject-introspection `__ - A bridge between Common Lisp and GObject. +* `ocaml-gir `__ - An automatic binding generator for gtk-related libraries +* `gir2pascal `__ - gir2pascal is a program to convert gir files into into pascal files +* `PLGI `__ - Prolog bindings (runtime) +* `hbgi `__ - Harbour bindings for GObject Introspection (runtime) + +Projects using GObject Introspection +------------------------------------ + + * `Folks `__ - the Gnome contact aggregator + * `GnomeShell `__ - prototyping the future gnome shell + * `Midgard2 `__ - language bindings to the Midgard content repository + * `libpeas `__ - library providing a generic plugin framework + * `telepathy-glib `__ - GLib bindings for Telepathy + * `gir2xmi `__ - UML model generator for GObject-Introspection Gir files. + * `playerctl `__ - a library and cli for controlling media players that implement the MPRIS DBus interface + * `i3ipc-glib `__ - a library for extensions to the i3 window manager + +Projects that could use GObject-Introspection +--------------------------------------------- + + * `Mono GAPI `__ could replace its gapi2-parser by using GOject-Introspection. + * `gtkmm `__ could use GObject-Introspection in its `gmmproc `__ to generate C++ library bindings diff --git a/docs/website/writingbindableapis.rst b/docs/website/writingbindableapis.rst new file mode 100644 index 00000000..9ab11b47 --- /dev/null +++ b/docs/website/writingbindableapis.rst @@ -0,0 +1,163 @@ +===================== +Writing Bindable APIs +===================== + +Things to avoid +--------------- + +Structures with custom memory management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Avoid creating C structures with custom memory management unless they are +registered as a `boxed type +`__. +If you don't register them as a boxed type bindings will fall back to +simple memory copying, which might not be what you want. + +Also consider using a full `GObject +`__ +as that allows bindings to better integrate those objects with the binding +language, like for example preserve user defined state across language +boundaries. + +Example to avoid: + +.. code-block:: c + + struct _GstMiniObject { + GTypeInstance instance; + /*< public >*/ /* with COW */ + gint refcount; + guint flags; + + +Functionality only accessible through a C macro +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The scanner does not support C macros as API. Solution - add a function +accessor rather than a macro. This also has the side effect of making +debugging in C code easier. + +Example: + +.. code-block:: c + + #define GTK_WIDGET_FLAGS(wid) (GTK_OBJECT_FLAGS (wid)) + + GtkWidgetFlags gtk_widget_get_flags (GtkWidget *widget); /* Actually, see http://bugzilla.gnome.org/show_bug.cgi?id=69872 */ + + +Direct C structure access for objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Having GObjects also have fields can be difficult to bind. Create accessor +functions. + +Example: + +.. code-block:: c + + struct _SoupMessage { + GObject parent; + + /*< public >*/ + const char *method; + + guint status_code; + ... + } + + const char * soup_message_get_method (SoupMessage *message); /* Or use a GObject property */ + + +va_list +~~~~~~~ + +Using varargs can be convenient for C, but they are difficult to bind. +Solution: Keep the C function for the convenience of C programmers, but add an +another function which takes an array (either zero terminated or with a length +parameter). + +**Good** example: + +.. code-block:: c + + GtkListStore *gtk_list_store_new (gint n_columns, + ...); + GtkListStore *gtk_list_store_newv (gint n_columns, + GType *types); + +You can also expose the array variant under the name of the varargs variant +using the ``rename-to`` annotation: +``gtk_list_store_newv: (rename-to gtk_list_store_new)`` + + +Multiple out parameters +~~~~~~~~~~~~~~~~~~~~~~~ + +Multiple out parameters are supported by introspection, but not all languages +have an obvious mapping for multiple out values. A boxed structure could serve +as an alternative. + +Example to think about (here, there could be a boxed ``struct GtkCoordinate { +gint x; gint y; }`` structure). + +.. code-block:: c + + void gtk_widget_get_pointer (GtkWidget *widget, + gint *x, + gint *y); + + +Arrays +~~~~~~ + +For reference types, zero-terminated arrays are the easiest to work with. +Arrays of primitive type such as "int" will require length metadata. + + +Callbacks +~~~~~~~~~ + +Callbacks are hard to support for introspection bindings because of their +complex life-cycle. Try to avoid having more than one callback in the same +function, and consider using GClosure when you need more. + + +Using a different name for error domain quarks from the enum name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Error domain quarks should always be named in the form +__error_quark() for an error enum called +Error. Example to avoid: + +.. code-block:: c + + typedef enum FooBarError { + FOO_BAR_ERROR_MOO, + FOO_BAR_ERROR_BLEAT + }; + + GQuark foo_bar_errors_quark(); + + +Custom code in constructors +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creating an object via ``foo_bar_new()`` shouldn't execute any code +differently than creating the same object via ``g_object_new()``, since many +bindings (and also GtkBuilder/Glade) create objects using ``g_object_new()``. +That is, don't do this: + +.. code-block:: c + + FooBar * + foo_bar_new (void) + { + FooBar *retval = FOO_BAR (g_object_new (FOO_TYPE_BAR, NULL)); + retval->priv->some_variable = 5; /* Don't do this! */ + return retval; + } + +Instead, put initialization code in the ``foo_bar_init()`` function or the +``foo_bar_constructed()`` virtual function. diff --git a/docs/website/writingbindings/guidelines.rst b/docs/website/writingbindings/guidelines.rst new file mode 100644 index 00000000..69f1aa78 --- /dev/null +++ b/docs/website/writingbindings/guidelines.rst @@ -0,0 +1,45 @@ +========== +Guidelines +========== + +This page is intended as a guide describing the process of writing a language +binding for the GObject Introspection framework. + +* Decide if you want to make a language binding which is implementation + agnostic or implementation specific. Some languages such as Python have + libraries which are available across implementations. The Python module + ``ctypes`` is a binding for the libffi language binding, which is + implemented in a couple of different Python implementations. It's usually + easier to target a specific interpreter or compiler implementation so if you + unsure, write a specific one. + +* For interpreted language implementations, construct the language binding on + top of the :doc:`libgirepository` library instead of writing a code generator. + It'll make it easier for developers to use your language binding as they + will be able to read the typelibs in runtime without having an extra + intermediate step to generate the language specific metadata. The + libgirepository library can also be used for bindings based upon code + generators as an optimization, its a lot faster to read metadata from the + typelib than it is to extract the metadata from the GIR XML files. + +* Use the Everything library in your unittests, aim at testing all functions + there. Do testing as early as possible in the development of the binding, as + the code is likely to be more complex than you anticipate. + +* Use the same coding style as your language. If libraries for your language + normally uses underscores do that as well. For instance, Java bindings + should have a method on it's GtkButton wrapper called ``setLabel`` and not + ``set_label``. + +* If there are existing GObject bindings, reuse them for improved + compatibility. It's a nice feature being able to use static bindings and + introspected bindings together. The Perl & Python bindings does that. + +* Try to stay close to the C language semantics, for instance + GObject should be mapped to a class and gtk_button_set_label to a method of + that class: + + * java: ``button.setLabel("foo")`` + * javascript/python/vala: ``button.set_label("foo")`` + * perl: ``$button->set_label("foo")`` + * scheme: ``(send button (set-label "foo"))`` diff --git a/docs/website/writingbindings/index.rst b/docs/website/writingbindings/index.rst new file mode 100644 index 00000000..f1f42a59 --- /dev/null +++ b/docs/website/writingbindings/index.rst @@ -0,0 +1,10 @@ +================ +Writing Bindings +================ + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + guidelines + libgirepository diff --git a/docs/website/writingbindings/libgirepository.rst b/docs/website/writingbindings/libgirepository.rst new file mode 100644 index 00000000..9c00e61c --- /dev/null +++ b/docs/website/writingbindings/libgirepository.rst @@ -0,0 +1,15 @@ +=============== +libgirepository +=============== + +libgirepository is a C library which provides a C API for accessing the +typelib data and for interacting with the corresponding GObject based +libraries. + +For more information about libgirepository see the `API documentation +`__. + +The following example shows how to call the ``g_assertion_message()`` function +from libglib-2.0: + +.. literalinclude:: ../../../examples/glib-print.c -- cgit v1.2.1