INSTALL

# vi: set ts=2 fdm=marker:

"""
 *
 * Program       : SRMCollider
 * Author        : Hannes Roest <roest@imsb.biol.ethz.ch>
 * Date          : 05.02.2011 
 *
 *
 * Copyright (C) 2011 - 2012 Hannes Roest
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
 *
"""

=== Installation === 
{{{

==== Linux ====  
{{{

The SRMCollider is tested on an Ubuntu 10.04 system and all auxiliary programs
should be easily installable using the package manager apt-get. In principal, a
minimal installation should only require Python 2.4 or higher and a MySQL
server 5.1 or higher, as well Biopython.
Alternatively there also exists experimental support for SQLite.

These components can be installed on ubuntu using the command 

$ sudo apt-get install -y python mysql-server python-mysqldb python-biopython 

In order to compile the C++ extensions, the Boost.Python libraries are
necessary as well as the CGAL libraries. These can be installed on Ubuntu using
the command

$ sudo apt-get install -y python-dev libcgal-dev libboost-python-dev
$ sudo apt-get install libboost-filesystem-dev libboost-test-dev libboost-system-dev

In order to install the webserver, you would need to install
$ sudo apt-get install apache2 python-matplotlib

Then you can try to build the extensions and copy them 

$ python setup.py build
$ sudo python setup.py install

For local installs, you can just skip the install step and copy the built .so
files into the local directory:
$ cp build/lib.*/* .

After that, you should run the tests (see testing down below)

}}}

==== Windows ==== 
{{{

Installing the SRMCollider on Windows is is possible for experienced users only
since you need many additional software. Compiling the C++ extensions has not
yet been tested but the basic functionality should be accessible using the
Python-only version. To complete a successful install on Windows, you will have
to do the following:

Install Python 2.x (e.g. 2.7) from http://www.python.org/getit/
Install MySQL from http://dev.mysql.com/downloads/mysql/
Install MySQLdb from http://www.lfd.uci.edu/~gohlke/pythonlibs/ - search for
    MySQL-python-1.2.3.win32-py2.6.exe 

This should be sufficient for an minimal install on Windows. However it will
not enable you to compile the C++ extensions. There are several examples out
there on how to do it, e.g. http://docs.python.org/extending/windows.html but
be aware that the SRMCollider relies on the following libraries:

* Python headers
* Boost.Python
* CGAL

There some solutions that rely on MinGW or VC++, see here for example:
http://stackoverflow.com/questions/101061/building-python-c-extension-modules-for-windows
but you then still need to install the above libraries.

Furthermore, the SRMCollider requires either sqlite or a MySQL server which can
be installed locally or on a dedicated host. However for non-performance
critical applications, also a local MySQL server or a SQLite installation is
supported.  For the Python bindings to SQLite, pysqlite is used which may be
obtained here: https://code.google.com/p/pysqlite/. To install a MySQL server
on a windows machine, there are instructions available from the MySQL project
https://dev.mysql.com/doc/refman/5.1/en/windows-installation.html and SQLite
binaries are precompiled here https://www.sqlite.org/download.html.

}}}

==== Webserver ==== 
{{{

To install the SRMCollider as a webservice, you need a webserver that supports
execution of Python scripts. One option would be Apache. Apart from that you
need access to a MySQL database, as when you run it stand-alone. Note that it
is necessary to compile the C++ scripts in order to run the webservice! Thus
follow the instructions above to install the compiled c_getnonuis.so object.

The following apache config file can be copied to /etc/apache2/sites-available
and then a link from  /etc/apache2/sites-enabled has to be made to point to
that file:

<VirtualHost *:80>

    ServerName srmcollider.org
    ServerAlias www.srmcollider.org

    DocumentRoot /var/websites/srmcollider
    <Directory />
        Options FollowSymLinks
        AllowOverride None
    </Directory>

    ScriptAlias /srmcollider/ /var/webapps/srmcollider/web_scripts/
    <Directory "/var/webapps/srmcollider/web_scripts">
        AllowOverride None
        AddHandler cgi-script .py
        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch +IncludesNoExec
        Order allow,deny
        Allow from all
    </Directory>

    ErrorLog /var/log/apache2/srmcollider_error.log

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    CustomLog /var/log/apache2/srmcollider_access.log combined

</VirtualHost>


The following files from the folder "cgi-scripts" go the folder "/var/webapps/srmcollider/web_scripts/":
- about.html
- download.html
- sharedhtml.py
- srmcollider.py

The files from the folder "css" go the folder "/var/websites/srmcollider/stylesheets/"

You then have to edit /var/webapps/srmcollider/web_scripts/srmcollider.py and
set configuration options like relative file path and mysql config files, the
ssrcalc table (as a lookup if a user submits a peptide). Please look at
everything up to the tag 
" # No changes after here "
and edit everything above according to your setup.

Congratulations, after restarting apache the webserver should now be available
at yourdomain.org/srmcollider/srmcollider.py

==== Set up a webserver using the cgi-scripts ==== 

{{{
There are python cgi-scripts in the cgi-scripts folder. You can copy them into
your cgi-bin folder and add something like the following entry to your apache
VirtualHost entry:

    ScriptAlias /cgi-bin/ /var/www/cgi-bin/
    <Directory "/var/www/cgi-bin">
        AllowOverride None
        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
        Order allow,deny
        Allow from all
    </Directory>

Furthermore the code expects the stylesheets (which can be found in the css
directory) to be placed under the apache root in a folder called stylesheets,
e.g. /stylesheets/srmcollider.css -- in addition there is also a color
stylesheet, e.g. called brown.css which is also necessary.


}}}

}}}

=== Testing === 
{{{

The easiest way to test which functions are enabled and which ones are not is
by running the tests. Please use the -s option because it may give you valuable
information whether all the modules are correctly loaded and available.

To work with nosetests, you first need to install nosetests (e.g. on Ubuntu do
"sudo apt-get install python-nose").

In order to test sqlite, first an sqlite and mysql database needs to be created:

$ cd test
$ vi test_db.py # edit the file and change the mysql config
$ python sqltest_tables_setup.py mysql
$ python sqltest_tables_setup.py sqlite

Then you can run the tests

$ nosetests test --with-coverage -s

To run all nonslow tests (e.g. no database tests or complete functionality tests)
$ nosetests test -a '!slow' -s

To run all tests that do not require any cpp modules
$ nosetests test -a '!cpp' -s

To run all tests that do not require mysql 
$ nosetests test -a '!mysql' -s

To just test one function, one could do this
$ nosetests test/test_collider.py:Test_collider_function.test_getMinNeededTransitions_1

To test the real coverage

$ nosetests test --with-coverage --cover-package=DDB,Residues,SRM_parameters,collider,precursor,uis_functions 

To test the functionality of the C++ functions, you can run

$ cd cpp
$ cmake .
$ make && make test

 }}}

=== Distributing === 
{{{

$ python setup.py sdist --manifest-only
$ python setup.py sdist --formats=gztar,zip


 }}}