Skip to content

dev_guide.md

Latest commit

 

History

History
64 lines (45 loc) · 2.18 KB

dev_guide.md

File metadata and controls

64 lines (45 loc) · 2.18 KB
Raw

GtkAda development guide

This contains Ada bindings for Gtk, Gdk, Glib, Pango and Cairo.

Source organization

src/ # The main source directory
    generated/ # The generated bindings
    misc.c     # C code for miscellaneous functions and constants
docs/    # The user-facing documentation
gtkada_demo/ # A demo that can be used as an example for how to use GtkAda.
testsuite/ # The test suite for GtkAda

Ada packages are namespaced under Gtk, Gdk, Glib, Pango and Cairo corresponding to the underlying C libraries.

The mapping from C to Ada is mostly straightforward. For instance, gtk_window_present becomes Gtk.Window.Present.

Documentation

The GtkAda Reference manual (docs/gtkada_rm/) is generated by gnatdoc.

Working on bindings

The documentation for bindings is in contrib/documentation.md.

Never edit the files under src/generated/ by hand. They are generated. See contrib/documentation.md.

To write a custom widget in Ada by overriding the GtkWidget virtual methods (measure, size_allocate, realize, snapshot), use the Set_Default_*_Handler / Inherited_* family in Gtk.Widget. See the "Overriding GObject virtual methods" section of contrib/documentation.md and the worked example in gtkada_demo/create_custom_widget.adb.

Testing

To run the entire testsuite: python testsuite/testsuite.py. To run an individual test: python testsuite/testsuite.py <name of test>.

The testsuite is an Ada port of the C testsuite. The C testsuite is available in testsuite/c_tests/.

A minimal example test is available in testsuite/tests/main/.

GTK tests need an X display. On Linux the test driver wraps each test in xvfb-run -a, giving every (parallel) test its own private virtual display, so xvfb must be installed (e.g. the xorg-x11-server-Xvfb / xvfb package). If xvfb-run is not found, the driver logs a warning and falls back to the ambient DISPLAY.

Work checklist

Before submitting your work:

  • Add a demo for your changes in gtkada_demo/ if applicable.
  • Edit or port a test from C if applicable.
  • Update the user's guide in docs/gtkada_ug/ if needed.
  • Update dev_guide.md and contrib/documentation.md if needed.