
=================
Packaging Plugins
=================

Philosophy
==========

Elisa plugin framework relies on Setuptools_ which provides
interesting features like:

- eased packaging using Python Eggs
- dependency management
- release versions control
- easy package resources access
- and much more...

This document details step by step how to develop an Elisa plugin.

.. _Setuptools: http://peak.telecommunity.com/DevCenter/setuptools

Discovery
=========

Elisa exports a set of entry points where additional components can
plug into. Thus, Elisa is able to dynamically detect plugins, wherever
they are installed by easy_install.

Packaging
=========

So, once the plugin is developed, it's time to package, either for
test purpose or for deployment. To make our plugin usable in Elisa,
the developer has to:

1. package the plugin using a setup.py
2. reference his plugin class in one of Elisa's entry points groups.
3. build an Egg file using bdist_egg setup.py command

Here is an example of a setup.py:

.. code-block:: python

  from setuptools import setup, find_packages

  setup(name="elisa-lirc",
        version="0.1",
        description="""LIRC plugin""",
        author="The Elisa Team",
        author_email="foo@bar.com",
        packages=find_packages(),
        entry_points="""
        [elisa.plugins.misc]
        lirc = mylircplugin.package.lirc:LIRCPlugin
        """)

In above example, the lirc plugin is registered in elisa.plugins.misc
group. In development process context, it's overkill to rebuild
the Egg at each iteration; the developer would use the "develop"
command:

::

  $ python setup.py develop

In deployment context, the developer would package the plugin with:

::

  $ python setup.py bdist_egg

And an .egg file would appear in a dist/ directory from where the
setup.py was called.

The end-user can then either install the egg using easy_install or put
the .egg file in $HOME/.elisa/plugins/ directory. Finally it's just a
matter of adding plugin's name to elisa configuration file to tell
Elisa to load and use the new plugin.
