Gtk2Hs: A binding of Gtk+ Version 2.x for the programming language Haskell

http://www.haskell.org/gtk2hs

The library currently wraps most functions for GUI programming from
the gtk 2.6 libraries. Furthermore there is support for the Pixbuf
functions, the libglade UI loader, the SourceView widget, the GConf
configuration system, and the Mozilla rendering engine, embedded in a widget.

The GHC Haskell compiler, version 5.04 or greater, is required.
Gtk2hs is known to compile on FreeBSD, Linux, Solaris, OS X and
Windows (MinGW).

You are reading these instructions because you want to build Gtk2Hs from
source. If you would rather install a binary (pre-compiled) package,
please check the Gtk2Hs web site.

Building
--------

This section assumes that you are building a source distribution (.tar.gz).
If you are building on Windows, read "Building on Windows" first. If you
are interested in using ghci on Solaris, read "ghci on Solaris". If you
are using the CVS repository, please read "Building from the CVS HEAD".

The following assumes that the sources are in ~/gtk2hs.

1. Run the configure script.

The configure script has several useful options, particularly:

--with-hc=<path to your ghc>
  Uses the specified GHC for compilation and for installation of the package.

--with-hcflags=<path to your ghc>
  If you find that you need to pass any special flags to the Haskell compiler
  then use this option to specify them. This overrides the default flags which
  is just "-O" to compile using optimisations.

--with-c2hs=no
  Uses the c2hs binding tool that comes with gtk2hs. This special version
  translates the header files only once, thereby accelerating generating
  Haskell files from .chs sources. This setting is the default.

--with-c2hs=yes
  Search for a c2hs installation in the current PATH.

NOTE: using an external version of c2hs is not currently working!

--with-c2hs=<path to your c2hs-config>
  Use this specific installation of c2hs. Make sure you specify the c2hs-config
  program, not c2hs itself.

--enable-packager-mode
  Enables --without-pkgreg and does not build any optional packages unless
  these are specified with --enable-PACKAGE. On Windows it also does some
  other stuff that helps with building an installer.

--without-pkgreg
  This option disables registering the packages with GHC. This
  is useful to people building on one machine but wanting to install on
  another, e.g. people packaging Gtk2Hs for use with a package management
  system.

--with-pkgconf=<path to a local .conf file>
  Instead of registering Gtk2Hs with GHC's global package file, use the given
  file. If this file doesn't exit, it is created. Useful for people who do
  not have sufficient priviliges to install into the global GHC package file.

--enable-PACKAGE      {- substitute package name for PACKAGE -}
--disable-PACKAGE
  Gtk2Hs contains bindings to some libraries that are not part of Gtk+ but
  closely related. This option forces a particular package to be built or
  not built. The default is to autodetect if a given package is installed
  (except in --packager-mode where the default is --disable-PACKAGE for all
  packages). At the time of writing the possible values for PACKAGE are:

  libglade : A library to load XML user interface descriptions that were
 	generated by the Glade user interface builder.

  gconf : A library to store configuration data in a Gnome-compatible way.

  sourceview : An enhancement of the TextView-widget of Gtk+. It adds features
	useful for editing source code, e.g. syntax highlighting.

  firefox / seamonkey / xulrunner / mozilla : A widget that renders HTML.

  cairo : A library for rendering vector graphics.

  svg-cairo : SVG file rendering for cairo.

  opengl : Bindings for the Gtk OpenGL extension

--disable-deprecated
  There are many Gtk+ APIs that have been deprecated as new versions of Gtk+
  have come out. This option makes sure that no deprecated APIs are used. You
  might want to use this option to make sure that you are not using deprecated
  APIs in your new programs.

--enable-docs
  This builds reference documentation in html format. These are also available
  from the website but you may prefer to keep a local copy. You will need
  haddock version 0.6 or later to build the documentation.

With --help you can ask ./configure what options it supports.

Add any of these options to the following command:

~/gtk2hs:$ ./configure

2. Building the sources.

In the following "make" stands for GNU make. If your system has a program
called "gmake" then "make" is probably not GNU make. In this case use "gmake".

To build the sources you issue:

~/gtk2hs:$ make

3. Install the libraries.

Become root and say:

~/gtk2hs:# make install

With the --prefix= and --pkg-conf= options, it is possible to compile and
install Gtk2Hs without root privileges.

4. Compiling a program.

To get started, you can compile and run one of the programs that reside in
the demo/ directory in the gtk2hs source directory. For example:

~/gtk2hs/demo/hello:$ make

which has the same effect as typing

~/gtk2hs/demo/hello:$ ghc --make World.hs -o helloworld

(If you are using ghc 6.0 or earlier you also need to use -package gtk)

The program should pop up a dialog box when you say

~/gtk2hs/demo/hello:$ ./helloworld

5. Documentation

The documentation is avaliable on the website. You can also build the
documentation locally. You say

~/gtk2hs:$ ./configure --enable-docs

6. Deinstallation

So long as you do not delete the source tree you can easily uninstall
everything that gtk2hs installed by saying

~/gtk2hs:$ make uninstall

in the root of the source tree. This will properly remove the package from
GHC and remove any installed file.

Alteratively, if you do not keep the source tree around then you can
uninstall by unregistering the packages with ghc-pkg and deleting all the
installed files. Assuming that you installed in the default location
(ie did not specify --prefix= during ./configure) then that would mean
doing the following:

# for pkg in glib gtk mogul glade gconf sourceview mozembed; \
> do ghc-pkg -r $pkg; done
# rm -rf /usr/local/lib/gtk2hs/
# rm -rf /usr/local/share/doc/gtk2hs/  #if you installed the docs

Building on Windows
--------------------

Install MSYS and MinGW.  Download the the binary installer for
Gtk and Glade. Make sure that GHC and all Gtk libraries are on your
path. The configure script should complain if this is not the case.


ghci on Solaris
---------------

The ghc-pkg program tends to pick up the Solaris linker which does not
understand the GNU ld option --whole-archive which is necessary to
build a package that can be used with ghci. You can build the object
files for interactive use manually by following the instructions that
come with GHC.


Building from CVS HEAD
----------------------

Building the latest sources from the CVS repository is normally straight
forward. In fact, since Gtk2Hs is only a wrapper around Gtk+, the CVS
HEAD is usually not as "unstable" as it is for most software projects.

Building the CVS HEAD proceeds as normal building, except that you need to
run "autoreconf" with sufficiently new versions of the automake/autoconf
toolsuite installed. (automake 1.8.x, autoconf 2.59)

Note that dependencies are generated only in a clean tree. Hence, if the
import structure of files change, the build might fail due to missing
dependencies. The easy way out is "make clean; make", the faster way is
to delete the lib*.deps files in each subdirectory.



Please report problems to the Gtk2hs mailing list
<gtk2hs-users@lists.sourceforge.net>.

The Gtk2Hs team.

