= How to contribute =

== Downloading the latest code ==

The code is maintained in a {{{darcs}}} repository. You can fetch it with the following command :

{{{
darcs get --partial http://mroy31.dyndns.org/~roy/repository/deejayd
}}}

== Sending in your changes ==

[http://wiki.darcs.net/DarcsWiki/GettingStartedUsing darcs is easy] and makes it easy both to integrate your patches and to give you credit for what you have contributed.

Patches by email will of course also be more than welcome.

== The code ==

=== Main source ===

==== Overview ====

All of Deejayd's source code is located in the [source:/ root directory]. You'll find in there :
  * packaging for some distributions
  * translations
  * {{{distutils}}} script.
  * the {{{deejayd}}} python module
  * the test suite and its launcher.
  * some documentation, especially the protocol documentation.
  * the launcher scripts

The [source:prepare.sh prepare script] changes some permitions and sets up some symlinks because {{{darcs}}} cannot hold this information. You should run it first, especially if you want to work on {{{djmote}}}.

==== The {{{deejayd}}} module ====

This module holds all of {{{deejayd}}}'s fonctionnality.

First, there is an [source:deejayd/interfaces.py interface] which aims at being shared among the client library and the core facade used in the server.

The mediadb and the database work together to populate some relationnal database tables according to you media files.

The player, either using the Gstreamer or the Xine backend gives us media playback. This playback capabilities gets used by the various available ''sources'' (such as playlist, webradio, dvd, etc).

Then there are the Twisted factories for both the net protocol and the web interface.

Those two manipulate [source:deejayd/core.py the core facade] which is a frontend to all those components.

==== The {{{pytyxi}}} module ====

Those are the Python {{{ctypes}}} bindings to {{{xine-lib}}}. To module holds {{{ctypes}}} declarations of the used C functions ({{{pytyxi/_*.py}}} modules) and object-oriented interfaces to {{{xine-lib}}}. See the bottom of [source:pytyxi/xine.py the xine bindings] for example usage and [source:deejayd/player/xine.py the stuff that glues this to deejayd] for an advanced usage.

==== The test suite ====

The full test suite may be launched using this simple line :

{{{
./tests.py
}}}

It accepts some options to narrow down which tests it is to run. Those options are documented in the [source:tests.py test suite launcher source].

Each test module is a python file named {{{test_*.py}}} which sits in the [source:testdeejayd testdeejayd directory]. There are a few helpers for building tests, such as launching a test server or building dummy media files to test the library on real data.

There is a special [source:testdeejayd/coreinterface.py test module which ensures that the deejayd core and the client library share the same interface (API)]. This way, if you for for instance a python GTK client to deejayd, it can become a full blown media player by only changing one line of code.

==== The net protocol documentation ====

The Deejayd net protocol documentation is generated from the [source:deejayd/net/commandsXML.py commands source] using a simple [source:docs.py documentation generation script].

=== Maemo source ===

The [source:maemosrc/ maemosrc directory] holds {{{djmote}}} which is a Deejayd client for the maemo platform. It also holds its packaging and symlinks to the client library.

This was splitted from the rest of the source because the way we package things, the debian directory cannot be shared between the maemo platform and the other full blown distributions. This is mainly due to the lack of {{{python-central}}} on the maemo platform.