============================================================
  Canola Tarball - Info, Installation and Use instructions
============================================================

 === Abstract ===

As Canola2's architecture supports the seamlessly execution of 3rd-party plugins 
and themes, we wanted to provide you, Canola2 user, the ability to code and
publish your own creations in a fast and easy way.

This tarball provides an easy way for users running Linux to have Canola2
installed on their machines in just a couple of minutes so that all plugin and 
themes development can be done in a friendly environment.


 === The tarball ===

This self-contained package contains all Canola2 binaries as well as its closest
dependencies. It's meant to be extracted in a user accessible folder like /tmp,
$HOME or in a system-wide one like /opt.

Canola2, as it was compiled, tries to use the libraries we provide whenever it's
possible in order to reduce the chance of misbehaviour due to the use of wrong
libraries.


 === System Requirements ===

Before proceeding to the the installation steps, make sure your system meets all
the requirements.

Currently Canola2 runs on Linux only, for other systems refer to the workaround
at the end of this page.

While Canola2 tarball should work on several Linux distributions, most of its
tests were conducted on x86 systems running Gentoo (~x86) or Ubuntu GutsyGibbon
LiveCD. If you have trouble installing on other systems please let us know so
we can have that fixed for the next release.


 --> What we provide

As of Canola2 Beta6 we provide the following requirements so you don't have to
worry about them:

* Canola2 code base
* Canola2 Python libraries 
* Python feedparser
* Python setuptools
* Enlightenment Foundation Libraries (eet, evas, ecore, embryo, edje, etk, e_dbus
                                      imlib2, epeg, epsilon)
* EFL Python bindings (evas, ecore, edje, e_dbus, epsilon)
* Enlightenment utilities (edje_cc, edje_viewer)


 --> What we do NOT provide

You probably have these installed in your system, if for any reason you don't,
please install them before running Canola2:

* Python 2.5
* mplayer (Canola uses mplayer to actually play the media content)


 === Download and Installation ===

Enough talking, have Canola2 running 3 steps.

1) Get Canola2 tarball (use current filename)
 
 $ wget http://openbossa.indt.org.br/canola/source_files/canola2-<version>.tar.bz2 -P /tmp

2) Unpack it to your $HOME folder, /opt or any one you wish so.

 $ cd <dest-dir>
 $ tar xf /tmp/canola2-<version>.tar.bz2

3) Start Canola2 in windowed mode

 $ ./run-canola -n

Alternatively you can omit the '-n' switch to try Canola2 in full-screen mode.
The interface still have some glitches in this mode though.


 === Running edje_cc and other applications ===

This script sets several environments variables to enable the use of its local
libraries. If you want to use any of the enclosed applications like 'edje_cc' or
the 'cnl-rescan-collection', which are used in the creation and installation of
plugins and themes, you must make sure these variables are set.

Canola2 Tarball provides an easy way to access a shell with all these variables
set, just run:

 $ ./run-canola --shell  (or -s)


 === Making your media available to Canola2 ===

When running on Linux, Canola2 watches for media at the following directories:

 * Music: $HOME/Music
 * Pictures: $HOME/Pictures
 * Videos: $HOME/Videos

If you'd like to change these folders you must use the cnl-set-prefs application
this way:

1) Set environment variables

 $ ./run-canola --shell

2) Check current settings

 $ bin/cnl-get-prefs settings

3) Modify the desired key ('audio', 'photo' or 'video')

 $ bin/cnl-set-prefs settings audio "['/dir1', '/dir2', '/dir3']"

4) Check new settings

 $ bin/cnl-get-prefs settings

5) Exit the spawned shell

 $ exit


 === Troubleshooting ===

If you have trouble running Canola2 please run it in verbose mode saving its
output:

 $ ./run-canola -n -vv > /tmp/Canola.output 2>&1

Then contact our team at #canola on freenode.net IRC servers.


 === Info for Mac or Windows users ===

As previously said, the only OS currently supported by Canola2 is Linux, however
you can run it in other operating systems using an Ubuntu LiveCD from within
a virtualization application like qemu, vmware or Parallels.

Just boot the Ubuntu LiveCD, install 'mplayer' and then follow the instructions
above to have Canola2 running.