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

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


Summary
=======

This is the Linux port of Miro.

Instructions and build requirements are documented at
https://develop.participatoryculture.org/index.php/LinuxBuildDocs

There are also helper build scripts located in ``tv/linux/helperscripts/``
which will install dependencies for some systems.  Note that these scripts
may be out of date and that you must run them with administrative priveliges.

RUN THEM AT YOUR OWN RISK!  

Please send in patches to the scripts if you encounter issues.

Please send in scripts for systems we don't have scripts for.

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/LinuxBuildDocs
for more information on building and executing the Linux 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 configuration preferences in gconf.

To see gconf preferences, do::

   gconftool-2 -R /apps/miro

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 Linux
platform.  Do the following::

   ./run.sh --unittest


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


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

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