= Installing Alexandria

Alexandria is written in Ruby with a GTK+2/GNOME user-interface. It
currently only runs on UNIX-style systems, such as GNU/Linux.

Alexandria is not an easy project to build from scratch. Apart from
Ruby and GNOME, it has a lot of dependencies; however, many of these
are now optional as detailed below. Once the dependencies have been
installed, building and installing Alexandria is relatively
straightforward.

[Also note that there are pre-built packages for some distros, such as
Fedora and Ubuntu.]

== Dependencies

The {Ruby-GNOME2}[http://ruby-gnome2.sourceforge.jp/] user-interface
involves a number of packages:

* <tt>ruby-gtk2</tt>
* <tt>ruby-gnome2</tt>
* <tt>ruby-libglade2</tt>
* <tt>ruby-gconf2</tt>
* <tt>ruby-pango</tt>

You should have GTK+ >= 2.8.0, and use Ruby-GNOME2 >= 0.16.0.

<tt>ruby-gettext</tt>[http://ponx.s5.xrea.com/hiki/ruby-gettext.html]
is required for the internationalisation of the user interface.
Requires version 1.7.0 or higher.

=== Hpricot

Alexandria uses +hpricot+[http://code.whytheluckystiff.net/hpricot] to
parse the HTML from web pages for providers such as DeaStore and
Siciliano. It is also used to parse the XML for the Amazon web
service. You can install the +hpricot+ package natively or as a
ruby gem.

== HTMLEntities

This is used by all website-based providers except MCU. 
 +htmlentities+[http://htmlentities.rubyforge.org/] is used to
provide more flexible HTML parsing.

== Build Dependencies

=== Ruby Dependencies

+rake+[http://rake.rubyforge.org] is required to build Alexandria from
the project +Rakefile+.

You also need +rubygems+[http://www.rubygems.org/] and
+rspec+[http://rspec.rubyforge.org/] to run the RSpec test suite.

=== Native Dependencies

The +gettext+[http://www.gnu.org/software/gettext] package is needed
to generate the binary +mo+ files used by <tt>ruby-gettext</tt> at
runtime. You also need the
+intltool+[http://www.freedesktop.org/wiki/Software/intltool] package
to merge translations into generated files (and to extract
translatable string from xml files during development).

Note that these files are pre-generated in tar.gz releases, so you'll
only need them if you're building from the SVN version, or want to
change the translations.

== Optional Dependencies

=== Ruby/ZOOM and Yaz

For Z39.50 support and and the <b>Library of Congress</b> and
<b>British Library</b> book providers you will need
<tt>ruby-zoom</tt>[http://ruby-zoom.rubyforge.org], which in turn
requires the non-Ruby package +yaz+[http://www.indexdata.dk/yaz].

Note that if you install the recent Ruby/ZOOM as the +zoom+ gem, you
will also need to install the +marc+ gem. (Older implementations of
ruby-zoom contained their own implementation of MARC.)

The Z39.50 Object-Orientation Model (ZOOM) is an international
standard for communication between computer systems, particularly
libraries and information-related systems.

=== image_size

You will need
<tt>image_size</tt>[http://rubyforge.org/projects/imagesize/] for
optimizing the cover images in exported libraries.

=== Revolution

If you want to auto-complete the names of people you loan books to
from your Evolution contacts database, you can install
+revolution+[ http://revolution.rubyforge.org/].

== Build and Install

To build Alexandria from a subversion checkout, go to the base project
directory (where the Rakefile and this INSTALL file are located) and
issue the command
    rake build
If you have downloaded a source package, this step will not usually be
necessary.

You must have root priveledges to install, so use +su+
    su -c 'rake install'
or +sudo+
    sudo rake install

Now you can check the version of the installed Alexandria
    alexandria --version

To launch Alexandria, simply use
    alexandria

If you wish to see more output on the console, you can use
    alexandria --debug

=== Staged installation for making packages

When building a binary package (such as a deb or rpm) you will want to
"install" Alexandria into a specified directory instead of the root
filesystem. You should specify this as the DESTDIR environment variable
and use the +install_package_staging+ task instead of +install+

    DESTDIR=debian/alexandria rake install_package_staging

If your distribution uses a specific directory to install Ruby
packages, you should also set the RUBYLIBDIR.

=== Installing in the home directory

If you want to install Alexandria in your home directory, you should
specify the PREFIX, SHARE and RUBYLIBDIR envrionment variables, and
use the +install_package+ task instead of +install+.

    PREFIX=$HOME SHARE=$HOME/.share RUBYLIBDIR=$HOME/.rubylib rake install_package

This will install the +alexandria+ program into +$HOME/bin+ (which you
should add to your +PATH+), and the ruby files to your
+$HOME/.rubylib+ which you should add to your +RUBYLIBDIR+ environment
variable.

=== Uninstalling

To uninstall, simply run

    sudo rake uninstall

(or +rake uninstall_package+ if you installed in your home directory).

If you specified any of the environment variables PREFIX, SHARE,
RUBYLIBDIR and DESTDIR during the installation, you should use the
same variables during uninstallation (or rake won't know where to look
for the files it has to remove).
