== Building and Installing the Ubuntu Unity Recoll Lens

Important preliminary notes:

- This only makes sense for Ubuntu versions using the Unity environment:
  Natty (11.04), Oneiric (11.10), Precise (12.04), and later. 
- _Remember that you still need to use the recoll GUI (or the recollindex
  //command) to get the indexing going !_
- The Lens is artificially limited to showing at most 20 results. Use the
  recoll GUI for more complete capabilities (or edit rclsearch.py, change
  the "if actual_results >= 20:" line). 


=== The Lens with Recoll 1.17 and later

If you are willing to install or upgrade to Recoll version 1.17, all
necessary packages are on the Recoll PPA, you just need to add the
repository to your system sources and add or upgrade the packages: *_/This
is the recommended approach!_*

----
sudo add-apt-repository ppa:recoll-backports/recoll-1.15-on
sudo apt-get update
sudo apt-get install recoll-lens recoll
----

This document may still be useful if you want to modify the lens source
code.

=== The Lens with older Recoll versions

If, for some reason, you wish to test the Lens with an older Recoll
version, read the following. 

Please not that such an installation is somewhat crippled: you will not be
able to display results for embedded documents (emails inside an mbox,
attachments etc.). This requires a recoll command line option which is only
available in 1.17 

The Lens is based on the Recoll Python module which is not built by default
for versions prior to 1.17, so so you will first need to pull the Recoll
source code (for you version), then untar and proceed with the
configure/build instructions below. 

The following uses --prefix=/usr. I have no real reason to believe 
that this would not work with /usr/local (lenses are also searched there by
default). If you confirm that things work with another prefix, please drop
me a line.

When doing this over a previous Recoll compilation, run a "make clean" to
get rid of the non-PIC objects. 

Note that the following instructions change nothing to your existing Recoll
installation, they only install the Python module and the Unity Lens,
recoll, recollindex etc. are unaffected. 

'/TOP/OF/RECOLL/SRC' designates the top of the recoll source tree.

=== Configure and build the recoll library and python module, install the module

The following needs the development packages for Xapian, Python and zlib.

----
cd /TOP/OF/RECOLL/SRC 
# May fail if no previous build was performed
make clean

# the gui/x11 disabling is just here to avoid having to install the
# development libraries for Qt.
configure --prefix=/usr --enable-pic --without-x --disable-qtgui
make

cd python/recoll
python setup.py build
sudo python setup.py install
----

=== Build and install the Unity Lens

----
cd /TOP/OF/RECOLL/SRC
cd desktop/unity-lens-recoll
configure --prefix=/usr --sysconfdir=/etc 
sudo make install

----

Voilà, it should work...

Try to start the Dash, you should see the Recoll checkerboard (or
whatever...) in the Lens list. 

The Recoll Lens expects a Recoll query language string, so you can use
field searches, directory, size, and date filtering (see the
link:https://www.recoll.org/usermanual/rcl.search.lang.html[Recoll
manual] for a description of the query language).  

If you want to disable the Lens, I think that you just have to delete
'/usr/share/unity/lenses/recoll'

Other installed files:

----
/usr/libexec/unity-recoll-daemon
/usr/share/dbus-1/services/unity-lens-recoll.service
/usr/share/doc/unity-lens-recoll
/usr/share/unity-lens-recoll
----