Thirdparty widgets and Guile

[Marius Vollmer <mvo zagadka ping de>]

Hi,

what do you think about this?

Wrapping 3rd party widgets
--------------------------

When writing new widgets for Gtk you should provide a stylized
description of them, just like the core Gtk package provides
"gtk.defs"

Write your own defs file and install it along with the new widgets.
If your widget (or the package of all widgets that you want to treat
as one unit) is called "foo", call the defs file "foo.defs" and
install it as <prefix>/share/gtk/foo.defs

The format of the defs file is not yet documented, but will be some
day.


When writing in a high-level language that needs a particular set of
wrapped widgets, you are responsible for making sure that bindings for
these widgets are available.  The exact way of doing this depends on
the particular language you are using.  Here is how it works with
Guile.

The basic command is

    build-guile-gtk [OPTIONS] COMMAND [CMD-OPTIONS] ARGS...

The various available COMMANDs are:

- list-defs

  Lists all installed definition files.  You can grep the output to
  check whether a specific widget is there at all.

- gen-funcs.c DEFS
- gen-types.c DEFS
- gen-types.h DEFS

  Generate glue code for the definitions in DEFS.  The code is written
  to stdout.  These commands are mainly intended for low-level things.

- link

  Output to stdout all necessary link options to include all installed
  Gtk bindings into a program.

- build-bindings DEFS...

  Generate and compile all necessary glue code for the DEFS files, and
  arrange things so that Guile programs can find them in the module

    (toolkits foo)

  when DEFS is "foo.defs".
  
  When bindings already exist for one of the DEFS and when they are
  up-to-date, nothing is done for this particular defs file.

  This might involve fairly massive actions, like linking a new
  guile-gtk executable on platforms where dynamic linking is not
  available. All actions happen in a new directory "foo-bindings".

  The new bindings are not installed, use the next command for that.

- install-bindings [--remove] DEFS...

  Install newly created bindings from their directories.  These
  directories have typically been filled with `build-bindings'.

  When a directory for one of the DEFS files does not exist, it is
  silently ignored.

  When the `--remove' options is specified the directories are removed
  after installing.

- clean-bindings DEFS...

  Remove the build directories for the DEFS files, like
  install-bindings with the `--remove' option does.

When one of the DEFS names contains a slash, it is used as is for the
filename, when it does not contain a slash, "<prefix>/share/gtk/" is
prepended.

The "<prefix>" used is the prefix specified while configuring the
guile-gtk package.  [You should not depend on this.  Maybe handling of
multiple prefixes will be added.]

Say, your program needs the `gtkhtml' widget.  That widget is supposed
to have installed a file called "gtkhtml.defs" and you can have the
following commands in your Makefile:

    all:
	build-guile-gtk build-bindings gtkhtml

    install:
	build-guile-gtk install-bindings gtkhtml

    clean:
	build-guile-gtk clean-bindings gtkhtml

If you have just installed a new Gtk widget and want to generate the
bindings beforehand, you can issue

    % build-guile-gtk build-bindings DEFS...
    become root, or whatever is appropriate for installation
    % build-guile-gtk install-bindings DEFS...