======
README
======

:Author: Will Kahn-Greene <will.guaraldi at pculture dot org>
:Date: January 14, 2010


Summary
=======

This is the GTK/X11 port of Miro.

Instructions and build requirements are documented at
https://develop.participatoryculture.org/trac/democracy/wiki/GTKX11BuildDocs

If you have problems, visit us on ``#miro-hackers`` on
``irc.freenode.net``.


Build and run
=============

To compile and run Miro in the current directory, do::

   ./run.sh

If you have the required dependencies it should build Miro and run it.

See https://develop.participatoryculture.org/projects/dtv/wiki/GTKX11BuildDocs
for more information on building and executing the GTK-X11 platform code.
The information at this URL is considered the authoritative source.

To run Miro in "debug mode" (i.e. in gdb)::

   ./run.sh --debug

Obviously, this requires gdb.

For more command-line options including how to set preferences on the command 
and what preferences are available, do::

   ./run.sh --help

Set the ``HOME`` environment variable to switch where Miro saves database
and other files::

   mkdir /tmp/foo
   HOME=/tmp/foo ./run.sh

.. Note:: Setting ``HOME`` doesn't work in KDE--it causes other problems.


Preferences
===========

Miro stores preferences in gconf.  To wipe out all preferences, do::

   gconftool-2 --recursive-unset /apps/miro

To backup your preferences, do::

   gconftool-2 --dump /apps/miro > /tmp/foobar


Unittest instructions
=====================

Once you get ``./run.sh`` working, you can run the unittests on GTK-X11 
platform.  Do the following::

   ./run.sh --unittest


This will go through all the unittests on the GTK-X11 platform and spit out 
any errors to stdout and stderr.


Problems with xulrunner
=======================

If you're having problems with compiling and running Miro with xulrunner
on your system, then it's likely that the code in ``setup.py`` that guesses
values for xulrunner paths and libraries isn't guessing correctly on your
system.

If this is the case, try setting the properties located at the top of the
``setup.py`` file.

Note that if you have xulrunner 1.8 and 1.9 installed on your system, you
must use the same xulrunner that the gtkmozembed Python module is compiled
against.  If you don't, when you go to run Miro, you'll get Symbol Undefined
type errors.


Problems with gstreamer
=======================

Make sure you have gstreamer plugins installed.  That solves most
problems.
