diff --git a/INSTALL b/INSTALL index c80dbe90282b76465aca4a383793b281db8aa432..82c00d554bf7fca9bf90c98de3cd8d803a8ba38d 100644 --- a/INSTALL +++ b/INSTALL @@ -1,79 +1,82 @@ -Installation instructions. +Mutalyzer installation instructions. -1) Install dependencies. - If you are on Debian or Ubuntu, you can use the following command to - install all dependencies: +Get Mutalyzer +============= - $ sudo bash extras/pre-install-debian.sh +Since you are reading this, you can probably skip this step. Otherwise, get +your hands on a tarball and: - Otherwise, install them manually (perhaps have a look in the above script - for a useful dependency list). Also, step 3 below might assume some - locations that are not standard for your distribution (so keep an eye on - that). + $ tar -zxvf mutalyzer-XXX.tar.gz + $ cd mutalyzer-XXX -2) Install Mutalyzer. +Or get the source from SVN directly: - Mutalyzer can be installed using Python setuptools. For a production - environment: + $ svn https://www.mutalyzer.nl/svn/mutalyzer2/trunk mutalyzer + $ cd mutalyzer - $ sudo python setup.py install - Alternatively, if you want to have a development environment, use: +Install Dependencies +==================== - $ sudo python setup.py develop +If you are on Debian or Ubuntu, you can use the following command to install +all dependencies: - The development environment uses symlinks to this source directory, so - you can develop from here. + $ sudo bash extras/pre-install-debian.sh -3) Create configuration files, setup database. +Otherwise, install them manually (perhaps have a look in the above script for +a useful dependency list). Also, further steps might assume some non-standard +locations for your distribution (so keep an eye on that). - Just run: - $ sudo bash extras/post-install.sh +Install Mutalyzer +================= -4) Test the installation. +Mutalyzer can be installed using Python setuptools. For a production +environment: - Note: This step is broken at the moment. Some tests write to the cache - for which we have no rights. This should be fixed to have a temporary - cache for the tests I guess. + $ sudo python setup.py install - You should always test the installation. The tests (for now at least) - need the batch daemon and the webserver (the SOAP part) running: +Alternatively, if you want to have a development environment, use: - $ sudo /etc/init.d/mutalyzer-batchd start - $ sudo /etc/init.d/apache2 restart + $ sudo python setup.py develop - Now run the tests: +The development environment uses symlinks to this source directory, so you can +develop directly from here. - $ MUTALYZER_ENV=test nosetests +Setup Mutalyzer +=============== -This program depends on the following packages: -- mysql-server >= 5.0.0 -- python >= 2.5.2 -- python-mysqldb >= 1.2.2 -- python-biopython >= 1.54 -- python-pyparsing >= 1.5.0 -- python-configobj >= 4.4.0 -- python-simpletal >= 4.1-6 -- python-soappy >= 0.12.0-2 -- python-magic >= 5.04-2 -- python-psutil >= 0.1.3-1 -- python-xlrd >= 0.6.1-2 -- python-daemon >= 1.5.5 -- python-webpy >= 0.33 -- python-webtest >= 1.2.3 -- python-suds >= 0.3.9-1 -- python-nose >= 0.11 +This step creates configuration files and populates the database: -The web and SOAP interfaces depend on the following packages: -- apache2 >= 2.2.11 -- libapache2-mod-wsgi >= 2.8 -- python-soaplib >= 2.0.0-alpha1 + $ sudo bash extras/post-install.sh -Below is the old install.sh script, but it is a bit outdated: +Test the Installation +===================== + +Note: This step is broken at the moment. Some tests write to the cache for + which we have no rights. This should be fixed to have a temporary cache + for the tests I guess. + +You should always test the installation. The tests (for now at least) need +the batch daemon and the webserver (the SOAP part) running: + + $ sudo /etc/init.d/mutalyzer-batchd start + $ sudo /etc/init.d/apache2 restart + +Now run the tests: + + $ MUTALYZER_ENV=test nosetests + + +Additional Notes +================ + +Included below for future reference is the old install.sh script. It is a bit +outdated. + #!/bin/sh diff --git a/README b/README index 1fb30b61aad8867fddc01546a83abcb5812f5758..c5e03f7bb1f3f77a4b322f41681e155454edebd8 100644 --- a/README +++ b/README @@ -1,90 +1,114 @@ -Coding style guide: +Mutalyzer, a HGVS variant nomenclature checker. + + +Documentation +============= + +See the doc/ directory for (possibly outdated) developer documentation and +presentation slides related to Mutalyzer. See http://www.mutalyzer.nl for +user documentation. + + +Installation +============ + +See the INSTALL file for installation instructions. -* Follow PEP 8 (code) and PEP 257 (docstrings). - http://www.python.org/dev/peps/pep-0008/ - http://www.python.org/dev/peps/pep-0257/ -* Use Epydoc style documentation in docstrings. -* Use __all__ definitions in modules. -* Executables are in the bin/ directory, e.g. like this: - #!/usr/bin/env python - from mutalyzer import batch_runner - batch_runner.run() -* For examples, check established Python projects: - http://code.djangoproject.com/browser/django/trunk - http://twistedmatrix.com/trac/browser/trunk - https://github.com/webpy/webpy - https://github.com/mitsuhiko/jinja2 - https://bitbucket.org/mramm/tg-21/src - http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/files - https://github.com/ask/celery +Unit Tests +========== -Run the test with (from the package root, or the /tests directory): - MUTALYZER_ENV=test nosetests +The unit tests depend on a running batch daemon and SOAP webservice: + $ sudo /etc/init.d/mutalyzer-batchd start + $ sudo /etc/init.d/apache2 start -Todo: +Now run the tests with: -* Tests fail in clean installation, because name checker tests make the + $ MUTALYZER_ENV=test nosetests + + +Development Notes +================= + +Todo list: +- Tests fail in clean installation, because name checker tests make the Retriever want to write to the cache and we don't run the tests as the user that owns the cache. How to fix this? -* Fix mutalyzer/UCSC_update.py. -* Test all uses of mkstemp(). -* https://www.mutalyzer.nl/projects/mutalyzer2/changeset?old_path=%2Ftrunk&old=228&new_path=%2Fbranches%2Fexon-deletions-branch&new=228#file5 -* Accept a --config command line argument for a configuration file location. -* Document integration, deployment, release management, etc. -* Use standard logging module, with rotating functionality. Race conditions +- Fix mutalyzer/UCSC_update.py. +- Test all uses of mkstemp(). +- Integrate fuzzy offsets from this branch: + https://www.mutalyzer.nl/projects/mutalyzer2/changeset?old_path=%2Ftrunk&old=228&new_path=%2Fbranches%2Fexon-deletions-branch&new=228#file5 +- Use standard logging module, with rotating functionality. Race conditions on the log file are probably a problem in the current setup. Instead of that rotating, we could also use logrotate: http://serverfault.com/questions/55610/logrotate-and-open-files -* Use environment variable for testing situation. Something like: - http://webpy.org/cookbook/testing_with_paste_and_nose - For example, we probably want to disable logging during the test run. -* Setup continuous integration. Currently, I'm most impressed with Hudson. +- Setup continuous integration. Currently, I'm most impressed with Hudson. http://hudson-ci.org/ http://www.rhonabwy.com/wp/2009/11/04/setting-up-a-python-ci-server-with-hudson/ -* Create an installation script, and from that preferably a Debian package. - Non-trivial thing here would be the requirement of database contents. - http://www.siafoo.net/article/77 - http://ghantoos.org/2008/10/19/creating-a-deb-package-from-a-python-setuppy/ - http://packages.python.org/distribute/setuptools.html#developer-s-guide - https://wiki.ubuntu.com/PackagingGuide/Python#The debhelper way - http://stackoverflow.com/questions/4981174/migrating-to-pipvirtualenv-from-setuptools - http://peak.telecommunity.com/DevCenter/setuptools -* Make the batch checker a real system service, using /var/run and a Upstart - init script. - http://wiki.debian.org/LSBInitScripts - http://celeryproject.org/docs/cookbook/daemonizing.html - http://www.debian-administration.org/articles/28 -* Migrate Javascript to JQuery. -* I think in the long run, the Output object is not really the way to go. It +- Migrate Javascript to JQuery. +- I think in the long run, the Output object is not really the way to go. It obscures the control flow. The logging part should use the standard logging module. The data gathering by the Output object is probably better handled by explicitely returning data objects from functions. -* Migrate from TAL to a more mondern and maintained Python template library. -* Develop a large test suite. -* Create a web interface url to watch the progress of a batch job. -* Use virtualenv? -* Perhaps the WSGI file should be somewhere else and be called mutalyzer.wsgi? -* Password for MySQL user. - +- Migrate from TAL to a more mondern and maintained Python template library. +- Develop a large test suite. +- Create a web interface url to watch the progress of a batch job. +- Use virtualenv? +- Perhaps the WSGI interface should be somewhere else and be called + mutalyzer.wsgi? +- Password for MySQL user. -Notes for server setup (Europium VM copy): +Code style guide: +- Follow PEP 8 (code) and PEP 257 (docstrings). + http://www.python.org/dev/peps/pep-0008/ + http://www.python.org/dev/peps/pep-0257/ +- Use Epydoc style documentation in docstrings. +- Executables are in the bin/ directory. +- For examples, check established Python projects: + http://code.djangoproject.com/browser/django/trunk + http://twistedmatrix.com/trac/browser/trunk + https://github.com/webpy/webpy + https://github.com/mitsuhiko/jinja2 + https://bitbucket.org/mramm/tg-21/src + http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev/files + https://github.com/ask/celery +- A lot of code does not yet adhere to these points, this is an ongoing + effort. -- Hostname aanpassen. -- Mailserver. -- Batch checker stoppen. +Obsoleted features: +- On eu.liacs.nl: + /etc/apache2/mods-enabled/rewrite.load contains a rewrite rule that converts + "Variant_info.php" to "Variant_info". + When all LOVD versions are above 2.0-23, this rule can be deleted and the + rewrite module can be disabled. +- In the Variant_info() function a substitution on error messages is + performed. + When all LOVD versions are above 2.0-23, this check can be deleted. -Obsoleted features: +Dependencies +============ - On eu.liacs.nl: /etc/apache2/mods-enabled/rewrite.load - - This file contains a rewrite rule that converts "Variant_info.php" to - "Variant_info". - - When all LOVD versions are above 2.0-23, this rule can be deleted and - the rewrite module can be disabled. +Mutalyzer depends on the following (Debian/Ubuntu) packages: +- mysql-server >= 5.0.0 +- python >= 2.5.2 +- python-mysqldb >= 1.2.2 +- python-biopython >= 1.54 +- python-pyparsing >= 1.5.0 +- python-configobj >= 4.4.0 +- python-simpletal >= 4.1-6 +- python-soappy >= 0.12.0-2 +- python-magic >= 5.04-2 +- python-psutil >= 0.1.3-1 +- python-xlrd >= 0.6.1-2 +- python-daemon >= 1.5.5 +- python-webpy >= 0.33 +- python-webtest >= 1.2.3 +- python-suds >= 0.3.9-1 +- python-nose >= 0.11 - index.py: - - In the Variant_info() function a substitution on error messages is - performed. - - When all LOVD versions are above 2.0-23, this check can be deleted. +The web and SOAP interfaces depend on the following packages: +- apache2 >= 2.2.11 +- libapache2-mod-wsgi >= 2.8 +- python-soaplib >= 2.0.0-alpha1