README

======
README
======
:Author: Will Kahn-Greene <will.guaraldi at pculture dot org>
:Date: February 8th, 2011
Summary
=======
This is the Linux port of Miro. It uses GTK and other GNOME
technologies.
Instructions and build requirements are documented at
https://develop.participatoryculture.org/index.php/LinuxBuildDocs
Requirements
============
There are 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``.
Generally, the requirements are these:
Build requirements:
* git - http://git-scm.com/
* gcc, g++, standard c/c++ libraries - http://gcc.gnu.org/
* Python >= 2.6 - http://www.python.org/ (we don't support Python 3.0
or higher yet)
* Pyrex >= 0.9.6.4 or higher -
http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/
* PyGTK >= 2.0 - http://www.pygtk.org/
* pygobject >= 2.0 - http://ftp.gnome.org/pub/GNOME/sources/pygobject/
* libwebkit dev files - http://webkit.org/ (might work with lower
versions--untested)
* libsoup dev files - http://live.gnome.org/LibSoup
Runtime requirements:
* Python >= 2.6 - http://www.python.org/
(we don't support Python 3.0 or higher yet)
* dbus and python bindings 0.80.0 or higher -
http://www.freedesktop.org/wiki/Software/dbus
* PyGTK >= 2.0 - http://www.pygtk.org/
* pygobject >= 2.0 - http://ftp.gnome.org/pub/GNOME/sources/pygobject/
* pycairo - http://cairographics.org/pycairo/
* libwebkit >= 1.1.15 - http://webkit.org/
(might work with lower versions--untested)
* pywebkitgtk >= 1.1.5 - http://live.gnome.org/PyWebKitGtk
* libsoup - http://live.gnome.org/LibSoup
* gconf and python bindings
* gstreamer >= 0.10.22 - http://gstreamer.freedesktop.org/
(needs playbin2 with text-sink)
* gstreamer plugins-base and plugins-good
* gstreamer python bindings
* libtorrent-rasterbar 0.14 or higher except for 0.15.4 which has
known issues (bz:13549) -
http://www.rasterbar.com/products/libtorrent/
* libtorrent-rasterbar python bindings
* libcurl - http://curl.haxx.se/libcurl/
* libcurl python bindings - http://curl.haxx.se/libcurl/python/
* mutagen - http://pypi.python.org/pypi/mutagen/1.12
* libavahi-compat-libdnssd1
If you discover that there are other requirements, let us know!
Building and running
====================
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/index.php/LinuxBuildDocs
for more information on building and executing the Linux platform code.
The information at this URL is considered the authoritative source.
For more command-line options including how to set preferences on the command
and what preferences are available, do::
./run.sh --help
There are two ways to run Miro in a test sandbox.
1. Set the ``HOME`` environment variable to switch where Miro saves
database and other files::
mkdir /tmp/foo
HOME=/tmp/foo ./run.sh
This has the problem that it doesn't work if you're using KDE (it
causes problems) and it uses your "production" Miro configuration.
2. Run Miro using the ``--home`` and ``--gconf-name`` arguments::
mkdir /tmp/foo
run.sh --home=/tmp/foo --gconf-name=mirotest
This stores configuration in a different place and uses a different
home without affecting the process environment.
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.
You can run specific tests by providing the test name. For example::
./run.sh --unittest utiltest
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
Problems with gstreamer
=======================
Make sure you have gstreamer plugins installed. That solves most problems.
Consult your Linux distribution's documentation for details.
Problems with ffmpeg
====================
Miro uses ffmpeg for conversions. It's common for Linux distributions to
ship with ffmpeg versions that are missing libaac decoding. If you're
running into problems converting things, that's probably the cause. Consult
your Linux distribution's documentation for help.