kupfer is a simple, flexible, launcher for Gnome
++++++++++++++++++++++++++++++++++++++++++++++++

:Homepage:  http://kaizer.se/wiki/kupfer/
:Credits:   Copyright 2007--2009 Ulrik Sverdrup <ulrik.sverdrup@gmail.com>
:Licence:   GNU General Public License v3 (or any later version)

Installing
==========

This project is configured for waf; waf is shipped in the distributable
tarball but not in the repository.  If you need to get waf, run::

    wget -O waf http://waf.googlecode.com/files/waf-1.5.8
    chmod +x waf

Installation follows the steps::

    ./waf configure
    ./waf

then::

    ./waf install

or ::

    sudo ./waf install

You can use ``--prefix=$PREFIX`` when configuring to assign an
installation spot. By default, Kupfer is installed for all users.
Installing only for your user, the prefix ``~/.local`` is often used;
you just have to check that: ``~/.local/bin`` is in your ``$PATH``.

Requirements
------------

Kupfer requires Python 2.6 or later, and the following important libraries:

* gtk python bindings, GTK+ version 2.16
* glib python bindings (pygobject) 2.18
* dbus python bindings

Optional, but very recommended dependencies:

* python-keybinder (see below)
* wnck python bindings
* gvfs
* xdg-terminal (to find which terminal application you use, if it's not
  Gnome Terminal)
* rst2man / python docutils  to build manpages
* xml2po / gnome docutils  to install mallard help pages
* `keyring` python module, and optionally its extensions
  python-keyring-gnome or python-keyring-kwallet

Opportunistic dependencies

* The deprecated 'gnome' module is used for session connection as
  fallback
* If available, 'setproctitle' is used to set the process name


Some plugins might require additional python modules!

Spawning
========

Kupfer is installed as ``kupfer`` into ``$PREFIX/bin``.

Keybinder Module
----------------

Kupfer uses tomboy's keybinder code, just like many other applications
do for global keybindings.  I had to break out the python wrapping of
the code into a standalone python module `keybinder`_ that you need to
install first.

.. _`keybinder`: http://kaizer.se/wiki/python-keybinder

Now you can set kupfer's keybinding by editing kupfer's config.  See
``kupfer --help`` for how to do that.

You can use kupfer without the keybinder module, for example by
assigning a global keybinding to the ``kupfer`` binary, but it not the
recommended way.

.. vim: ft=rst tw=72