source: trunk/third/eel/README @ 17274

This file briefly describes Eel, the Eazel Extensions Library.  It
also contains build instructions as well as other information that
might be useful for folks trying to either use Eel or hack on it.

====================
0: Table of contents
====================

0: Table of contents
1: Hacking
2: Introduction
3: Distribution-specific notes
4: Compiling
5: FreeType issues

==========
1: Hacking
==========

If you would like to hack on Eel, or have patches, please send
them to the Nautilus mailing list:

<nautilus-list@lists.eazel.com>

We use the Nautilus mailing list because the code in Eel was 
originally part of Nautilus.  If there is enough interest in
discussing Eel on this list, we will create a new mailing list
as soon as the traffic warrants it.

===============
2: Introduction
===============

The Eazel Extensions Library is a collection of widgets and extensions
to many modules of the GNOME platform.  These widgets and extensions 
were developed by hackers working on Nautilus.   For the duration of
the Nautilus 1.0 development cycle, the code was internal to Nautilus
and its components.

In order to make these useful extensions usable to other projects, we
have decided to put then in their own library.  It is possible that 
we will move even more extensions/widgets from Nautilus to Eel.

If you wish to use Eel for a project, have patches, suggestions and/or
you wish to discuss whether some of the extensions belong in the
library they extend, please send mail to the mailing list in section 1.

==============================
3: Distribution-specific notes
==============================

The following describes the libraries that Eel hackers use for
development and what we have tested with. At the moment, we make no
guarantees one way or another about whether Eel will work with
other versions.

You will also need the library package that is associated with each
development package, these versions are for Red Hat 6.2 and Debian
"potato":

library         Red Hat                     Debian                          approx. version
--------------  ------------------------    ------------------------------  ------------------
audiofile       audiofile-devel-0.1.9-3     libaudiofile-dev (0.1.9-0.1)    0.1.9
esound          esound-0.2.20               ?                               0.2
libc            glibc-devel-2.1.3-15        libc6-dev (2.1.3-10)            2.1.3
libc++          egcs-c++-1.1.2-30           libstdc++2.10-dev (2.95.2-12)   2.9.0, 2.10
libjpeg         libjpeg-devel-6b-10         libjpeg62-dev (6b-1.2)          6b 1.0-1.2
libpng          libpng-devel-1.0.5-3        libpng2-dev (1.0.5-1)           1.0.5
libtiff         libtiff-devel-3.5.4-5       libtiff3g-dev (3.5.4-5)         3.5.4
libungif        libungif-devel-4.1.0-4      libungif3g-dev (3.0-3)          3.0 or 4.1.0
Xlib            XFree86-devel-3.3.6-20      xlib6g-dev (3.3.6-7)            3.3.6
zlib            zlib-devel-1.1.3-6          zlib1g-dev (1.1.3-5)            1.1.3
freetype2       freetype2-devel-1.0beta8    ?                               1.0beta8

Other modules for Red Hat users:

        - For most modules, the versions in Red Hat 6.1 or 6.2 will do (listed above).

        - FreeType packages are available here:

        http://developer.eazel.com/eazel-hacking/updates/redhat62/freetype2/freetype-2.0.1-4.i386.rpm
        http://developer.eazel.com/eazel-hacking/updates/redhat62/freetype2/freetype-devel-2.0.1-4.i386.rpm

Replace "redhat62" with "redhat70" if you are using RedHat Linux 7.0.

Other modules for Debian users: using potato, or possibly woody:

        - None are known at this time

=====================
4: Compiling from cvs
=====================

NOTE: Instructions on compiling from tarballs should be extracted from
the copy of Eel inside the tarball, not here in CVS.

Compiling from cvs a lot of work, and some packages may not compile at
any given moment when you check them out.

First, make sure you have installed the packages detailed below. If
you are running GNOME from binaries (Helix Code or your native
distribution binaries), please make sure you have installed the
corresponding development packages. (i.e.: the *-devel packages which
provide the necessary C header files.

Then, make sure you have no old version of the packages eel
depends on on your system. You can check the version of the relevant
packages by trying to execute "package-config --version" (ie:
gnome-config --version will report gnome-libs version, gconf-config
--version will report gconf's version).

The following lists the packages and the versions that are required.

    module             branch             configure options
    ------             ------             -----------------
    glib:              glib-1-2
    gtk+:              gtk-1-2
    gnome-xml:         LIB_XML_1_BRANCH
    gnome-libs:        gnome-libs-1-0     --enable-prefer-db1
    xml-i18n-tools:    xml-i18n-tools-stable-1-x
    gdk-pixbuf:        HEAD               --enable-canvas-pixbuf
    gnome-vfs:         HEAD
    librsvg:           HEAD

One difference between tarball and cvs compilation is that when you
get stuff from cvs, you don't get a configure script. This script has
to be generated.  This script is usually generated with the help of
another script available from cvs named "autogen.sh". For those
interested, "autogen.sh" will run in turn aclocal, automake, autoconf
and configure. You thus need versions of the GNU tools for the
following packages:

        package         version       command
        -------         -------       -------
        automake        1.4           automake --version
        autoconf        2.13          autoconf --version

Earlier versions might work but no one has tested them.

You will need to create the ${prefix}/share/aclocal directory
before compiling any package and setup the following environment
variable:

        export ACLOCAL_FLAGS="$ACLOCAL_FLAGS -I ${prefix}/share/aclocal"

We assume you want to install these packages in another prefix than
/usr since you want to keep a working system. For the following, we
assume you are installing in /usr/local. ie: ${prefix}=/usr/local

Redefine your PATH environment variable:
        export PATH=$PATH:${prefix}/bin

Redefine your LD_LIBRARY_PATH environment variable:

        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${prefix}/lib

Redefine your GNOME_PATH environment variable:

        export GNOME_PATH=$GNOME_PATH:${prefix}

In the order defined above and with the specific options detailed
above for each package, you should run the autogen scripts:

        ./autogen.sh --prefix=${prefix} <special-options>

Then:

        make

Then get root and:

        make install.

==================
5: FreeType issues
==================

Eel includes support for rendering anti aliased text (smooth
mode).  For smooth mode to work, Eel needs to detect and use
FreeType2 in your system.

To learn more about FreeType2, please see:

        http://freetype.sourceforge.net/

If you are using a RedHat 6.x or greater system, then you can easily
add FreeType2 support by installing the rpms found here:

        http://developer.eazel.com/eazel-hacking/updates/redhat62/freetype2

Replace "redhat62" with "redhat70" if you are using RedHat Linux 7.0.

Originally, the Freetype 2 rpm that we used for Eel/Nautilus was called "freetype2".
Now that RedHat 7.1 is is coming around, they have included freetype 2 in their 
distribution.  They called the rpm "freetype-2" (Freetype Version 2).  Their 
freetype-2 rpm contains both Freetype version 1 and Freetype version 2.  In
order to avoid naming conflicts, we have renamed our freetype2 rpm to freetype-2.
This will cause problems for people upgrading from our old rpms to our new ones.
To remove the old rpms,

1) su
   <password>
2) rpm -e --nodeps freetype2 freetype2-devel
3) Install the new Freetype-2 rpms: rpm -Uvh freetype*2.0.1*.rpm