= GirFFI

by Matijs van Zuijlen

http://www.github.com/mvz/ruby-gir-ffi

{<img src="https://secure.travis-ci.org/mvz/ruby-gir-ffi.png" />}[http://travis-ci.org/mvz/ruby-gir-ffi]

== Description

Ruby bindings for GNOME using the GObject Introspection Repository.

== Features/Notes

* Create bindings to any GObject-based library.
* Supports both Gtk+ 2 and Gtk+ 3.
* Bindings generated at runtime.
* Provides overridden bindings for selected methods.
* Require 'ffi-gtk2' or 'ffi-gtk3' to load overrides for Gtk2 or Gtk3.

== Install

* sudo gem install gir_ffi

== Synopsis

Basic usage:

  require 'gir_ffi'

  GirFFI.setup :TheNamespace

  TheNamespace.some_function

  obj = TheNamespace::SomeClass.new
  obj.some_method with, some, args

Gtk2:

  require 'ffi-gtk2'
  Gtk.init
  win = Gtk::Window.new :toplevel
  win.show
  GObject.signal_connect(win, "destroy") { Gtk.main_quit }
  Gtk.main

Gtk3:

  require 'ffi-gtk3'
  Gtk.init
  win = Gtk::Window.new :toplevel
  win.show
  GObject.signal_connect(win, "destroy") { Gtk.main_quit }
  Gtk.main

See the `examples/` directory for more, well, examples.

== Requirements

* Ruby-FFI of course
* gobject-introspection installed with some introspection data
* The `rr` and `minitest` gems for testing

Depending on the GIR data, GirFFI needs the actual libraries to be
available under the name ending in plain `.so`. If GirFFI complains that it
cannot find the library, try installing development packages for those
libraries.

On Debian and Ubuntu, the following set of packages should be enough to get
`rake test` working: `libgirepository1.0-dev` (at least version 0.10),
`gir1.2-gtk-2.0` and `libgtk2.0-dev`.

== Hacking and contributing

If you want to help out, have a look at TODO.rdoc, and the output of `rake
notes`. Feel free to file bugs or send pull requests.

If you want to send pull requests or patches, please:

* Make sure `rake test` runs without reporting any failures. If your code
  breaks existing stuff, it won't get merged in.
* Add tests for your feature. Otherwise, I can't see if it works or if I
  break it later.
* Make sure latest master merges cleanly with your branch. Things might
  have moved around since you forked.
* Try not to include changes that are irrelevant to your feature in the
  same commit.

== License

Copyright (c) 2009--2012 Matijs van Zuijlen

GirFFI is free software, distributed under the terms of the GNU Lesser
General Public License, version 2.1 or later. See the file COPYING.LIB for
more information.