diff options
28 files changed, 2965 insertions, 151 deletions
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 <fdbe3cc3>` + :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 <cf7621f3>` + :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 <d15f8cde>` + :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 <bc88ef7b>` + :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 <dc651812>` + :bzbug:`557405` + * - ``(in-out)`` + - Replaced by ``(inout)`` + - :commit:`1.39.0 <a2b22ce7>` + :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 ``<xi:include href="xml/annotation-glossary.xml"><xi:fallback/></xi:include>`` + to your master GTK-Doc document; e.g. see the end of `tester-docs.xml + <https://gitlab.gnome.org/GNOME/gtk-doc/blob/master/tests/gobject/docs/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 | + | | | + | | <GI-name>.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 +<https://mesonbuild.com/Gnome-module.html#gnomegenerate_gir>`__ 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 <your favorite runtime> +------------------------------------------------------ + +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 <https://wiki.gnome.org/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 + <https://developer.gnome.org/gobject/stable/pt02.html>`__ + +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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" width="1052.3622" height="744.09448" id="svg2" version="1.1" inkscape:version="0.48.2 r9819" sodipodi:docname="architecture.svg" inkscape:export-filename="/home/antono/Documents/Slides/lvee-winter-2012/architecture.png" inkscape:export-xdpi="303.60001" inkscape:export-ydpi="303.60001"> + <title id="title3277">GObject Introspection Architecture</title> + <defs id="defs4"> + <marker inkscape:stockid="DotM" orient="auto" refY="0" refX="0" id="DotM" style="overflow:visible"> + <path id="path3833" d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none;marker-end:none" transform="matrix(0.4,0,0,0.4,2.96,0.4)" inkscape:connector-curvature="0"/> + </marker> + <marker inkscape:stockid="Arrow2Mend" orient="auto" refY="0" refX="0" id="Arrow2Mend" style="overflow:visible"> + <path id="path3795" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" transform="scale(-0.6,-0.6)" inkscape:connector-curvature="0"/> + </marker> + <marker inkscape:stockid="Arrow2Lend" orient="auto" refY="0" refX="0" id="Arrow2Lend" style="overflow:visible"> + <path id="path3789" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" transform="matrix(-1.1,0,0,-1.1,-1.1,0)" inkscape:connector-curvature="0"/> + </marker> + <marker inkscape:stockid="Arrow1Lend" orient="auto" refY="0" refX="0" id="Arrow1Lend" style="overflow:visible"> + <path id="path3771" d="M 0,0 5,-5 -12.5,0 5,5 0,0 z" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none" transform="matrix(-0.8,0,0,-0.8,-10,0)" inkscape:connector-curvature="0"/> + </marker> + <marker inkscape:stockid="DotM" orient="auto" refY="0" refX="0" id="DotM-3" style="overflow:visible"> + <path id="path3833-1" d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none;marker-end:none" transform="matrix(0.4,0,0,0.4,2.96,0.4)" inkscape:connector-curvature="0"/> + </marker> + <marker inkscape:stockid="Arrow2Lend" orient="auto" refY="0" refX="0" id="Arrow2Lend-8" style="overflow:visible"> + <path id="path3789-9" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" transform="matrix(-1.1,0,0,-1.1,-1.1,0)" inkscape:connector-curvature="0"/> + </marker> + <marker inkscape:stockid="DotM" orient="auto" refY="0" refX="0" id="DotM-2" style="overflow:visible"> + <path id="path3833-5" d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" style="fill-rule:evenodd;stroke:#000000;stroke-width:1pt;marker-start:none;marker-end:none" transform="matrix(0.4,0,0,0.4,2.96,0.4)" inkscape:connector-curvature="0"/> + </marker> + <marker inkscape:stockid="Arrow2Lend" orient="auto" refY="0" refX="0" id="Arrow2Lend-4" style="overflow:visible"> + <path id="path3789-0" style="font-size:12px;fill-rule:evenodd;stroke-width:0.625;stroke-linejoin:round" d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z" transform="matrix(-1.1,0,0,-1.1,-1.1,0)" inkscape:connector-curvature="0"/> + </marker> + </defs> + <sodipodi:namedview id="base" pagecolor="#ffffff" bordercolor="#666666" borderopacity="1.0" inkscape:pageopacity="0.0" inkscape:pageshadow="2" inkscape:zoom="0.70710678" inkscape:cx="493.13397" inkscape:cy="410.25035" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="false" showguides="false" inkscape:guide-bbox="true" inkscape:window-width="1214" inkscape:window-height="776" inkscape:window-x="66" inkscape:window-y="24" inkscape:window-maximized="1" showborder="true"> + <sodipodi:guide orientation="0,1" position="535.38085,998.03071" id="guide5157"/> + <sodipodi:guide orientation="1,0" position="62.629458,834.386" id="guide5159"/> + <sodipodi:guide orientation="1,0" position="692.96465,713.1677" id="guide5161"/> + <sodipodi:guide orientation="0,1" position="391.93919,785.89868" id="guide5163"/> + <sodipodi:guide orientation="1,0" position="359.61431,833.37585" id="guide5165"/> + <sodipodi:guide orientation="1,0" position="394.96965,744.48243" id="guide5167"/> + <sodipodi:guide orientation="0,1" position="471.74124,874.7921" id="guide5171"/> + <sodipodi:guide orientation="0,1" position="394.96965,684.28572" id="guide5173"/> + <sodipodi:guide orientation="0,1" position="333.35034,582.85802" id="guide5179"/> + <sodipodi:guide orientation="0,1" position="239.40615,807.11188" id="guide5195"/> + <sodipodi:guide orientation="0,1" position="260,444.28571" id="guide5203"/> + <sodipodi:guide orientation="0,1" position="274.28571,492.85714" id="guide5207"/> + <sodipodi:guide orientation="0,1" position="312.85714,390" id="guide5231"/> + <sodipodi:guide orientation="0,1" position="248.57143,251.42857" id="guide5256"/> + <sodipodi:guide orientation="1,0" position="201.02036,807.11188" id="guide5277"/> + <sodipodi:guide orientation="1,0" position="535.38085,902.06622" id="guide5279"/> + <sodipodi:guide orientation="1,0" position="840,492.85714" id="guide5322"/> + <sodipodi:guide orientation="0,1" position="1111.4286,647.14286" id="guide5324"/> + </sodipodi:namedview> + <metadata id="metadata7"> + <rdf:RDF> + <cc:Work rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type rdf:resource="http://purl.org/dc/dcmitype/StillImage"/> + <dc:title>GObject Introspection Architecture</dc:title> + <dc:date>2012-02-13</dc:date> + <dc:creator> + <cc:Agent> + <dc:title>Antono Vasiljev</dc:title> + </cc:Agent> + </dc:creator> + <dc:rights> + <cc:Agent> + <dc:title>http://creativecommons.org/licenses/by-sa/3.0/</dc:title> + </cc:Agent> + </dc:rights> + <dc:language>English</dc:language> + <dc:subject> + <rdf:Bag> + <rdf:li>GObject</rdf:li> + <rdf:li>GLib</rdf:li> + <rdf:li>GTK</rdf:li> + <rdf:li>Bindings</rdf:li> + </rdf:Bag> + </dc:subject> + <dc:publisher> + <cc:Agent> + <dc:title>http://antono.info/</dc:title> + </cc:Agent> + </dc:publisher> + </cc:Work> + </rdf:RDF> + </metadata> + <g inkscape:label="Tavolo 1" inkscape:groupmode="layer" id="layer1" transform="translate(0,-308.2677)"> + <rect style="fill:#ffffff;fill-opacity:1;stroke:none" id="rect3211" width="1052" height="743" x="1.4142075" y="308.36215" rx="0.89988375" ry="1.2800797"/> + <rect style="opacity:0.60852715;fill:#16aa41;fill-opacity:1;stroke:none" id="rect5275" width="254.98872" height="84.836205" x="176.48564" y="840.18842" rx="2.6552014" ry="2.6552014"/> + <rect ry="2.6552014" rx="2.6552014" y="744.00201" x="176.07715" height="56.580166" width="120.5053" id="rect5268" style="opacity:0.60852715;fill:#16aa41;fill-opacity:1;stroke:none"/> + <rect style="opacity:0.60852715;fill:#16aa41;fill-opacity:1;stroke:none" id="rect5233" width="120.5053" height="56.580166" x="310.8797" y="744.00201" rx="2.6552014" ry="2.6552014"/> + <rect ry="0.51764756" rx="0.36266771" y="666.01282" x="176.48563" height="56.580166" width="120.09681" id="rect5149" style="opacity:0.60852715;fill:#8a3673;fill-opacity:1;stroke:none"/> + <rect style="opacity:0.60852715;fill:#606060;fill-opacity:1;stroke:none" id="rect2985" width="225.99976" height="60.405384" x="176.48564" y="498.12244" rx="0.68247288" ry="0.55264413"/> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="270.94678" y="531.75018" id="text3759" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan3761" x="270.94678" y="531.75018">foo.c</tspan></text> + <path style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)" d="m 232.44911,547.95853 0,130.51524" id="path3763" inkscape:connector-curvature="0" sodipodi:nodetypes="cc"/> + <text sodipodi:linespacing="125%" id="text5151" y="702.40796" x="200.86145" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan y="702.40796" x="200.86145" id="tspan5153" sodipodi:role="line">libfoo.so</tspan></text> + <rect style="opacity:0.60852715;fill:#606060;fill-opacity:1;stroke:none" id="rect5155" width="120.5053" height="56.580166" x="310.87967" y="583.90582" rx="0.36390126" ry="0.51764756"/> + <path inkscape:connector-curvature="0" id="path5169" d="m 367.66014,547.95853 0,53.10402" style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="343.13705" y="624.99677" id="text5175" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan5177" x="343.13705" y="624.99677">Foo.gir</tspan></text> + <rect ry="0.51764756" rx="0.36390126" y="666.01282" x="310.87967" height="56.580166" width="120.5053" id="rect5181" style="opacity:0.60852715;fill:#8a3673;fill-opacity:1;stroke:none"/> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="263.1763" y="575.32751" id="text5187" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan5189" x="263.1763" y="575.32751">g-ir-scanner</tspan></text> + <text sodipodi:linespacing="125%" id="text5191" y="575.32751" x="196.09328" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan y="575.32751" x="196.09328" id="tspan5193" sodipodi:role="line">gcc</tspan></text> + <path style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)" d="m 367.86439,635.58016 0,37.37708" id="path5197" inkscape:connector-curvature="0" sodipodi:nodetypes="cc"/> + <text sodipodi:linespacing="125%" id="text5199" y="655.83643" x="256.62698" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan y="655.83643" x="256.62698" id="tspan5201" sodipodi:role="line">g-ir-compiler</tspan></text> + <text sodipodi:linespacing="125%" id="text5209" y="702.40796" x="327.53925" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan y="702.40796" x="327.53925" id="tspan5211" sodipodi:role="line">Foo.typelib</tspan></text> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="297.02197" y="896.43829" id="text5215" sodipodi:linespacing="125%"><tspan sodipodi:role="line" x="297.02197" y="896.43829" id="tspan5219" style="font-size:40px;text-align:center;text-anchor:middle">bindings</tspan></text> + <text sodipodi:linespacing="125%" id="text5242" y="777.79724" x="319.70181" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan style="font-size:11.32283497px" y="777.79724" x="319.70181" id="tspan5244" sodipodi:role="line">libgirrepository.so</tspan></text> + <path style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)" d="m 367.66014,753.2557 0,-37.37707" id="path5260" inkscape:connector-curvature="0" sodipodi:nodetypes="cc"/> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="201.32657" y="779.81921" id="text5262" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan5264" x="201.32657" y="779.81921" style="font-size:19.41057587px">libffi.so</tspan></text> + <path sodipodi:nodetypes="cc" inkscape:connector-curvature="0" id="path5266" d="m 233.0969,749.47378 -0.64779,-30.70879" style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/> + <path sodipodi:nodetypes="cc" inkscape:connector-curvature="0" id="path5281" d="m 367.66014,847.01924 0,-55.35074" style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/> + <path style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)" d="m 232.44911,845.8143 0,-55.35074" id="path5283" inkscape:connector-curvature="0" sodipodi:nodetypes="cc"/> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="490.84418" y="722.04968" id="text5308" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan5310" x="490.84418" y="722.04968" style="font-size:58.23171997px;font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;fill:#8a3673;fill-opacity:1;font-family:Ubuntu;-inkscape-font-specification:Ubuntu Medium">Deployment</tspan></text> + <text sodipodi:linespacing="125%" id="text5318" y="853.72321" x="490.84418" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan style="font-size:58.23171997px;font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;fill:#16aa41;fill-opacity:1;font-family:Ubuntu;-inkscape-font-specification:Ubuntu Medium" y="853.72321" x="490.84418" id="tspan5320" sodipodi:role="line">Consumption</tspan></text> + <text sodipodi:linespacing="125%" id="text5326" y="601.31128" x="490.84418" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#606060;fill-opacity:1;stroke:none;font-family:Sans" xml:space="preserve"><tspan style="font-size:58.23171997px;font-style:normal;font-variant:normal;font-weight:500;font-stretch:normal;fill:#606060;fill-opacity:1;font-family:Ubuntu;-inkscape-font-specification:Ubuntu Medium" y="601.31128" x="490.84418" id="tspan5328" sodipodi:role="line">Development</tspan></text> + <rect style="opacity:0.60852715;fill:#606060;fill-opacity:1;stroke:none" id="rect2985-6" width="254.89937" height="60.405384" x="178.17885" y="404.4209" rx="0.76974374" ry="0.55264413"/> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="280.45071" y="438.04865" id="text3759-4" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan3761-3" x="280.45071" y="438.04865">foo.vala</tspan></text> + <path inkscape:connector-curvature="0" id="path5169-3" d="m 369.35335,454.25697 0,53.10403" style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/> + <text xml:space="preserve" style="font-size:16.17547798px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" x="373.75293" y="486.75397" id="text5187-3" sodipodi:linespacing="125%"><tspan sodipodi:role="line" id="tspan5189-8" x="373.75293" y="486.75397">valac</tspan></text> + <path inkscape:connector-curvature="0" id="path5169-3-5" d="m 419.70848,452.574 0,148.40335" style="fill:none;stroke:#000000;stroke-width:1.21316099;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#DotM);marker-end:url(#Arrow2Lend)"/> + </g> +</svg>
\ 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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="678.53101" + height="468.55246" + id="svg2" + sodipodi:version="0.32" + inkscape:version="0.92.3 (2405546, 2018-03-11)" + sodipodi:docname="overview.svg" + inkscape:output_extension="org.inkscape.output.svg.inkscape" + version="1.1"> + <defs + id="defs4"> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + gridtolerance="10000" + guidetolerance="10" + objecttolerance="10" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.70000001" + inkscape:cx="219.00285" + inkscape:cy="259.78855" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="840" + inkscape:window-height="431" + inkscape:window-x="535" + inkscape:window-y="227" + fit-margin-top="10" + fit-margin-left="10" + fit-margin-right="10" + fit-margin-bottom="10" + inkscape:window-maximized="0" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(-32.877341,-31.452583)"> + <path + style="fill:none;fill-rule:evenodd;stroke:#303030;stroke-width:1.02008247;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:4.08032983, 1.02008246;stroke-dashoffset:0;stroke-opacity:0.77586209" + d="M 42.877341,295.93361 H 701.40837" + id="path3171" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <rect + style="fill:#749fcd;fill-opacity:1;stroke:#000000;stroke-width:1.06179869;stroke-opacity:0.62780265" + id="rect3185" + width="186.36678" + height="33.509632" + x="67.173752" + y="224.53593" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + ry="16.754816" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="76.428574" + y="245.93361" + id="text3187" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3189" + x="76.428574" + y="245.93361" + style="font-size:16px;line-height:1.25">Introspected GType's</tspan></text> + <g + id="g3325" + transform="translate(-66.428571,30.714286)" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <rect + y="102.00188" + x="170.53255" + height="33.577782" + width="109.29207" + id="rect3221" + style="fill:#739ecd;fill-opacity:1;stroke:#000000;stroke-width:0.99400002;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:0.62780265" + ry="16.071428" + rx="16.071428" /> + <text + id="text3223" + y="124.61499" + x="185.23328" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve"><tspan + y="124.61499" + x="185.23328" + id="tspan3225" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">Sources .c</tspan></text> + </g> + <g + id="g3320" + transform="translate(-66.428571,30.714286)" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <rect + y="145.21617" + x="170.71114" + height="33.577782" + width="109.29207" + id="rect3183" + style="fill:#749fcd;fill-opacity:1;stroke:#000000;stroke-width:0.99365026;stroke-opacity:0.62780265" + ry="16.788891" /> + <text + id="text3227" + y="167.96991" + x="181.77515" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve"><tspan + y="167.96991" + x="181.77515" + id="tspan3229" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">Headers .h</tspan></text> + </g> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.6243791px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 214.0979,149.31722 74.66135,42.51851" + id="path3231" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.48916915px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 254.74458,239.76045 34.08226,-46.93939" + id="path3235" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <rect + style="fill:#8bc254;fill-opacity:1;stroke:#000000;stroke-width:1.30141628;stroke-opacity:1" + id="rect3247" + width="208.27" + height="135.41287" + x="289.4364" + y="133.9415" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + ry="18.571428" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="295.99329" + y="156.75784" + id="text3249" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + x="295.99329" + y="156.75784" + id="tspan3469" + style="font-size:16px;line-height:1.25">GIR - XML format with</tspan><tspan + sodipodi:role="line" + x="295.99329" + y="176.75784" + id="tspan3495" + style="font-size:16px;line-height:1.25">introspectable metadata</tspan><tspan + sodipodi:role="line" + x="295.99329" + y="196.75784" + id="tspan3471" + style="font-size:16px;line-height:1.25">a language binding need</tspan><tspan + sodipodi:role="line" + x="295.99329" + y="216.75784" + id="tspan3491" + style="font-size:16px;line-height:1.25">function,class,enum,</tspan><tspan + sodipodi:role="line" + x="295.99329" + y="236.75784" + id="tspan3515" + style="font-size:16px;line-height:1.25">docstrings, struct fields</tspan><tspan + sodipodi:role="line" + x="295.99329" + y="256.75784" + id="tspan2561" + style="font-size:16px;line-height:1.25">etc</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="227.14287" + y="107.36218" + id="text3253" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3255" + x="227.14287" + y="107.36218" + style="font-size:16px;line-height:1.25">g-ir-scanner(1)</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="541.42859" + y="107.36218" + id="text3257" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3259" + x="541.42859" + y="107.36218" + style="font-size:16px;line-height:1.25">g-ir-compiler(1)</tspan></text> + <path + style="fill:none;fill-opacity:0.35426007;fill-rule:evenodd;stroke:#000000;stroke-width:1.28129315;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:3.84387917, 3.84387917;stroke-dashoffset:0;stroke-opacity:0.48878922" + d="M 513.92858,92.402021 V 282.32233" + id="path3265" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 212.85714,193.79075 h 75" + id="path3279" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.68055099px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 499.4176,193.07647 h 34.73622" + id="path3281" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <g + id="g3473" + transform="translate(24.285714,13.571429)" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <rect + y="130.21986" + x="510.00055" + height="105.71322" + width="157.85606" + id="rect3277" + style="fill:#d0c77b;fill-opacity:1;stroke:#000000;stroke-width:1.00107861;stroke-opacity:1" + ry="15.714286" /> + <text + id="text3283" + y="153.20482" + x="526.4989" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve"><tspan + y="153.20482" + x="526.4989" + id="tspan3285" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">Typelib - binary</tspan><tspan + id="tspan3457" + y="173.20482" + x="526.4989" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">format for fast</tspan><tspan + id="tspan3459" + y="193.20482" + x="526.4989" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">disk-access and</tspan><tspan + id="tspan3461" + y="213.20482" + x="526.4989" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">low memory</tspan></text> + </g> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="44.285713" + y="56.647896" + id="text3297" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3299" + x="44.285713" + y="56.647896" + style="font-weight:bold;font-size:20px;line-height:1.25;-inkscape-font-specification:'Bitstream Vera Sans Bold'">Build time</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="48.293804" + y="329.10397" + id="text3301" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + x="48.293804" + y="329.10397" + style="font-weight:bold;font-size:20px;line-height:1.25;-inkscape-font-specification:'Bitstream Vera Sans Bold'" + id="tspan3305">Runtime</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="244.28571" + y="118.79075" + id="text3312"><tspan + sodipodi:role="line" + id="tspan3314" + x="244.28571" + y="118.79075" + style="font-size:16px;line-height:1.25"> </tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="244.28571" + y="118.79075" + id="text3316"><tspan + sodipodi:role="line" + id="tspan3318" + x="244.28571" + y="118.79075" + style="font-size:16px;line-height:1.25"> </tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="67.14286" + y="350.21933" + id="text3342" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3344" + x="67.14286" + y="350.21933" + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12px;line-height:1.25;font-family:'Bitstream Vera Serif';-inkscape-font-specification:'Bitstream Vera Serif Italic'">How a language binding uses introspection</tspan></text> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';-inkscape-font-specification:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="66.887283" + y="79.159195" + id="text3346" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3348" + x="66.887283" + y="79.159195" + style="font-style:italic;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:12px;line-height:1.25;font-family:'Bitstream Vera Serif';-inkscape-font-specification:'Bitstream Vera Serif Italic'">How a library enables introspection</tspan></text> + <rect + style="fill:#d0c77b;fill-opacity:1;stroke:#000000;stroke-width:1.0904454;stroke-opacity:1" + id="rect3359" + width="191.33812" + height="103.481" + x="80.402374" + y="385.97882" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + ry="20" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="109.08316" + y="422.13339" + id="text3361" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3363" + x="109.08316" + y="422.13339" + style="font-size:16px;line-height:1.25">Typelib - mmap()</tspan><tspan + sodipodi:role="line" + x="109.08316" + y="442.13339" + id="tspan3395" + style="font-size:16px;line-height:1.25">shared between</tspan><tspan + sodipodi:role="line" + x="109.08316" + y="462.13339" + id="tspan3397" + style="font-size:16px;line-height:1.25">processes</tspan></text> + <g + id="g3413" + transform="translate(-30.714286,3.5714286)" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <rect + y="388.51193" + x="366.86404" + height="43.41486" + width="148.41486" + id="rect3376" + style="fill:#cca66e;fill-opacity:1;stroke:#000000;stroke-width:0.44228357;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922" + ry="21.70743" /> + <text + id="text3380" + y="414.63342" + x="383.2746" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve"><tspan + y="414.63342" + x="383.2746" + id="tspan3382" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">libgirepository</tspan></text> + </g> + <g + id="g3418" + transform="translate(-30,3.5714286)" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"> + <rect + y="445.21933" + x="367.14288" + height="37.142857" + width="147.85715" + id="rect3384" + style="fill:#cca66e;fill-opacity:1;stroke:#000000;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922" + ry="18.571428" /> + <text + id="text3386" + y="469.75562" + x="423.70425" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + xml:space="preserve"><tspan + y="469.75562" + x="423.70425" + id="tspan3388" + sodipodi:role="line" + style="font-size:16px;line-height:1.25">libffi</tspan></text> + </g> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.82769597px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 272.05671,437.35287 63.02944,-25.07684" + id="path3399" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.83396173px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 271.62195,443.79905 64.88964,25.78901" + id="path3401" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <rect + style="opacity:0.98000004;fill:#749fcd;fill-opacity:1;stroke:#000000;stroke-width:0.88915378;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:0.48878922" + id="rect3403" + width="152.96799" + height="41.539417" + x="529.23022" + y="418.02109" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + ry="20.769709" /> + <text + xml:space="preserve" + style="font-style:normal;font-weight:normal;line-height:0%;font-family:'Bitstream Vera Sans';fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + x="537.24548" + y="443.20486" + id="text3405" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90"><tspan + sodipodi:role="line" + id="tspan3407" + x="537.24548" + y="443.20486" + style="font-size:16px;line-height:1.25">dlopen:ed library</tspan></text> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.21470141px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="m 484.39306,412.46952 44.78531,25.4996" + id="path3409" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + <path + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.19193971px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 485.09597,466.55192 529.18975,440.3153" + id="path3411" + inkscape:export-filename="/home/jdahlin/dev/gnome/gobject-introspection/docs/reference/images/overview.png" + inkscape:export-xdpi="90" + inkscape:export-ydpi="90" + inkscape:connector-curvature="0" /> + </g> +</svg> 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 <https://gitlab.gnome.org/GNOME/gobject-introspection/>`__. + + +Reporting bugs +-------------- + +For a list of existing bugs and feature requests, see the `issues page +<https://gitlab.gnome.org/GNOME/gobject-introspection/issues>`__. You can also +`open an issue +<https://gitlab.gnome.org/GNOME/gobject-introspection/issues/new>`__. + + +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 <https://wiki.gnome.org/Projects/Vala>`__ - Compiler for the GObject type system (compile time) +* `Genie <https://wiki.gnome.org/Projects/Genie>`__ - Genie Language (compile time) +* `PyGObject <https://wiki.gnome.org/Projects/PyGObject>`__ - Python bindings (runtime) +* `pygir-ctypes <http://code.google.com/p/pygir-ctypes/>`__ - Pure Python GObject Introspection Repository (GIR) wrapper using ctypes (runtime) +* `pgi <http://github.com/lazka/pgi>`__ - Pure Python GObject Introspection Bindings (runtime) +* `GTK2-Perl/Introspection <https://wiki.gnome.org/GTK2-Perl/Introspection>`__ - Perl bindings (runtime) +* `JGIR <https://wiki.gnome.org/Projects/JGIR>`__ - Java/JVM bindings (compile time, using typelib) +* `GJS <https://wiki.gnome.org/Projects/Gjs>`__ - Javascript (spidermonkey) bindings (runtime) +* `Seed <https://wiki.gnome.org/Projects/Seed>`__ - Javascript (JSCore, WebKit JS engine) bindings (runtime) +* `sbank <http://live.gnome.org/sbank>`__ - Scheme binding for gobject-introspection (runtime) +* `GObjectIntrospection/GObjectConsume <https://wiki.gnome.org/Projects/GObjectIntrospection/GObjectConsume>`__ - Qt bindings (compile time) +* `GirFFI <http://wiki.github.com/mvz/ruby-gir-ffi>`__ - Ruby bindings (runtime) +* `lgob <http://oproj.tuxfamily.org/wiki/doku.php?id=lgob>`__ - Lua bindings (compile time?) +* `guile-gir <http://gitorious.org/guile-gir>`__ - Guile bindings (runtime) +* `factor-gir <http://github.com/ex-rzr/factor-gir>`__ - Factor bindings (runtime) +* `lgi <http://www.github.com/pavouk/lgi>`__ - Lua bindings (runtime) +* `GObject for PHP <https://github.com/megous/gobject-for-php>`__ +* `cl-gir <http://bazaar.launchpad.net/~scymtym/+junk/cl-gir/files>`__ GIR for Common Lisp (work in progress) +* `GNU Smalltalk <http://www.gitorious.org/gst-gobject-introspection>`__ - A branch of GNU Smalltalk which adds GObject Introspection bindings. +* `node-gir <https://github.com/creationix/node-gir>`__ - Node.js bindings to the girepository +* `go-gir-generator <https://github.com/linuxdeepin/go-gir-generator>`__ - Go bindings (compile time) (Forked from `gogobject <https://github.com/nsf/gogobject/>`__ which is unmaintained) +* `haskell-gi <http://www.haskell.org/haskellwiki/GObjectIntrospection>`__ - 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 <https://github.com/andy128k/cl-gobject-introspection>`__ - A bridge between Common Lisp and GObject. +* `ocaml-gir <http://git.ocamlcore.org/cgi-bin/gitweb.cgi?p=ocaml-gir/ocaml-gir.git>`__ - An automatic binding generator for gtk-related libraries +* `gir2pascal <http://wiki.freepascal.org/gir2pascal>`__ - gir2pascal is a program to convert gir files into into pascal files +* `PLGI <https://github.com/keriharris/plgi>`__ - Prolog bindings (runtime) +* `hbgi <https://github.com/tuffnatty/hbgi>`__ - Harbour bindings for GObject Introspection (runtime) + +Projects using GObject Introspection +------------------------------------ + + * `Folks <http://telepathy.freedesktop.org/wiki/Folks>`__ - the Gnome contact aggregator + * `GnomeShell <https://wiki.gnome.org/Projects/GnomeShell>`__ - prototyping the future gnome shell + * `Midgard2 <http://www.midgard2.org/>`__ - language bindings to the Midgard content repository + * `libpeas <http://git.gnome.org/browse/libpeas/tree/>`__ - library providing a generic plugin framework + * `telepathy-glib <http://telepathy.freedesktop.org/wiki/Telepathy%20GLib>`__ - GLib bindings for Telepathy + * `gir2xmi <https://github.com/jralls/gir2xmi>`__ - UML model generator for GObject-Introspection Gir files. + * `playerctl <https://github.com/acrisci/playerctl>`__ - a library and cli for controlling media players that implement the MPRIS DBus interface + * `i3ipc-glib <https://github.com/acrisci/i3ipc-glib>`__ - a library for extensions to the i3 window manager + +Projects that could use GObject-Introspection +--------------------------------------------- + + * `Mono GAPI <http://www.mono-project.com/GAPI>`__ could replace its gapi2-parser by using GOject-Introspection. + * `gtkmm <http://www.gtkmm.org/>`__ could use GObject-Introspection in its `gmmproc <http://www.gtkmm.org/docs/gtkmm-2.4/docs/tutorial/html/chapter-wrapping-c-libraries.html>`__ 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 +<https://developer.gnome.org/gobject/unstable/gobject-Boxed-Types.html>`__. +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 +<https://developer.gnome.org/gobject/unstable/gobject-The-Base-Object-Type.html>`__ +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 +<namespace>_<module>_error_quark() for an error enum called +<Namespace><Module>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 +<https://developer.gnome.org/gi/stable>`__. + +The following example shows how to call the ``g_assertion_message()`` function +from libglib-2.0: + +.. literalinclude:: ../../../examples/glib-print.c |
