Glib
====

This module provides perl access to Glib and GLib's GObject libraries.
GLib is a portability and utility library; GObject provides a generic
type system with inheritance and a powerful signal system.  Together
these libraries are used as the foundation for many of the libraries
that make up the Gnome environment, and are used in many unrelated
projects.

This wrapper attempts to provide a perlish interface while remaining
as true as possible to the underlying C API, so that any reference
materials you can find on using GLib may still apply to using the
libraries from perl.  Where GLib's functionality overlaps perl's,
perl's is favored; for example, you will find perl lists and arrays in
place of GSList or GList objects.  Some concepts have been eliminated;
you need never worry about reference-counting on GObjects or GBoxed
structures.  Other concepts have been converted to a perlish analogy;
the GType id will never be seen in perl, as the package name serves
that purpose.  See the main Glib manpage for more information.

This module also provides facilities for creating wrappers for other
GObject-based libraries.  The documentation page of the gtk2-perl
project's website has information about this stuff; see
http://gtk2-perl.sourceforge.net/

INSTALLATION
------------

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install


To avoid installing to a system directory, since this is a beta release,
you can change the installation prefix at Makefile.PL time with

   perl Makefile.PL PREFIX=/some/other/place

This will install the module to the subdirectory lib/perl5 under the given
prefix.  If this is not already in perl's include path, you'll need to tell
perl how to get to this library directory so you can use it; there are three
ways:

  in your environment (the easiest):
    # assuming a bourne-style shell
    PERL5LIB=/some/other/place/lib/perl5/site_perl
    export PERL5LIB

  on the perl command line:
    perl -I /some/other/place/lib/perl5/site_perl yourscript

  in the code of your perl script:
    use lib '/some/other/place/lib/perl5/site_perl';


DEPENDENCIES
------------

In order to use perl bindings for glib, you must have glib 2.x and its
prerequisites (pkg-config and a decent standard c library) installed.
glib-2.x is available from http://www.gtk.org, http://www.gnome.org,
etc.

Glib uses unicode internally; therefore this module requires perl 5.8.0
or newer.

You'll also need the following modules in order to build the Glib module
from source:

  ExtUtils::Depends >= 0.300
  ExtUtils::PkgConfig >= 1.00


HOW TO CONTACT US
-----------------
Homepage:               http://gtk2-perl.sourceforge.net/
Mailing list:           gtk-perl-list [at] gnome.org
Mailing list archives:  https://mail.gnome.org/archives/gtk-perl-list/
IRC:                    irc://irc.gnome.org/#gtk-perl
E-mail bug submission via CPAN's RT:
                bug-Glib [at] rt.cpan.org
Web bug submission via gnome.org's bugzilla:
                http://bugzilla.gnome.org/enter_bug.cgi?product=gnome-perl

Please do not contact any of the maintainers directly unless they ask you to.
The first point of contact for questions/problems/issues should always be the
mailing list.


BUG REPORTS
-----------
For help with problems, please contact the mailing list (above).  If you
already know you have a bug, please file it with one of the bug trackers
below.  With any problems and/or bug reports, it's always helpful for the
developers to have the following information:

- A small script that demonstrates the problem; this is not required, however,
  it will get your issue looked at much faster than a description of the
  problem alone.
- Version of Perl (perl -v)
- Versions of Gtk2-Perl modules (Glib/Gtk2/Pango/Cairo)
- Optional, but nice to have: versions of GTK+ libraries on your system
  (libglib, libgtk+, libpango, libcairo, etc.)

There are multiple project bug trackers, please choose the one you are most
comfortable with using and/or already have an account for.

Request Tracker:
- submitting bugs via the Web (requires a PAUSE account/Bitcard):
  https://rt.cpan.org/Public/Bug/Report.html?Queue=Glib
- submitting bugs via e-mail (open to anyone with e-mail):
  bug-Glib [at] rt.cpan.org

Gnome's bugtracker:
- report bugs to the 'gnome-perl' product (requires login)
  http://bugzilla.gnome.org/enter_bug.cgi?product=gnome-perl


PATCH SUBMISSION GUIDELINES
---------------------------
You can send us patches by...
- E-mailing it to the mailing list (above); please use a pastebin service of
  some kind for longer patchfiles (over say 20k in size).
- Those with gnome.org Git ID's can push trivial patches to git directly; if
  you're not sure what a trivial patch is, please ask first on the mailing
  list prior to pushing your commit.

OBTAINING SOURCE FROM THE GNOME.ORG GIT REPO
--------------------------------------------
Assuming you already have the 'git' command installed on your system, you can
use the 'git://' protocol:

git clone git://git.gnome.org/perl-Glib

Or, read-only access via HTTP:

git clone http://git.gnome.org/browse/perl-Glib

To update an existing clone of the source:

git pull

Most Linux distros package the 'git' command in a package called 'git-core'.


COPYRIGHT AND LICENSE
---------------------

Copyright (C) 2003-2012 by the gtk2-perl team (see the file AUTHORS for the
full list)

See the LICENSE file in the top-level directory of this distribution for the
full license terms.
