diff options
Diffstat (limited to 'docs/website/writingbindings')
-rw-r--r-- | docs/website/writingbindings/guidelines.rst | 45 | ||||
-rw-r--r-- | docs/website/writingbindings/index.rst | 10 | ||||
-rw-r--r-- | docs/website/writingbindings/libgirepository.rst | 15 |
3 files changed, 70 insertions, 0 deletions
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 |