Getting started with nammu for developers

Requirements and installation

nammu is written mainly in Jython, an implementation of Python that runs on Java.

Currently, nammu requires

• Python 2.7
• Java Development Kit 8
• Jython 2.7.0
• a few Python packages listed in the requirements.txt file

Check if you can install Java DK 8 with your system's package manager, otherwise it can be downloaded here: https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html.

Also for Jython check if you can install version 2.7.0 with your system's package manager, otherwise you can download it from here: https://www.jython.org/downloads.html. Note: nammu is tested only with Jython 2.7.0, if your package manager provides Jython 2.7.1 (especially on some GNU/Linux distributions), be aware that this will likely not work.

Python 2.7 is probably already installed in your system, but make sure it's the case. We'll describe in the next section how to install the Python packages used by nammu.

Setting up the development environment

We recommend using Python's virtual environments for development. One possibility is to use virtualenv. After having installed it, add the following lines to your shell's init script (e.g., .bashrc for the Bash):

export JYTHONPATH="/path/to/nammu/resources/lib:$JYTHONPATH"
export WORKON_HOME=~/.virtualenvs
source /usr/bin/virtualenvwrapper.sh

The environment variable WORKON_HOME should point to a directory of your choice where the environments will be saved to (note that you have to create it). The last line loads some shell functions to conveniently work with virtual environments. Double check the path to the virtualenvwrapper.sh is correct.

Open a new shell or source your shell's init script to make sure the settings above take effect. You can now create a virtual environment with the command

$ mkvirtualenv -p jython --no-pip --system-site-packages nammu

The -p option is to select jython as the Python interpreter. The last argument, nammu in this example, is the name of the virtual environment. New versions of pip, a Python package manager, won't work with Jython 2.7.0, thus with the option --no-pip we tell virtualenv to not use system's default pip. Then, create a symbolic link of Jython's pip into the bin directory of our virtual environment: identify where system jython executable is installed (e.g., /opt/jython2.7.0/bin/jython), in the same directory there should be the pip executable (e.g., /opt/jython2.7.0/bin/pip), and you can create the link with the command

$ ln -s /opt/jython2.7.0/bin/pip "WORKON_HOME/nammu/bin/."

where nammu is the name of the environment you created before. The option --system-site-packages is needed because pip will install packages into the global Jython installation, this option makes packages installed system-wide will be available inside the environment.

Activate the environment, if it wasn't activated automatically, with the command

$ workon nammu

and install the required Python packages with

$ pip install -r requirements.txt

Note: pip will install packages into the system-wide Jython installation, depending on where this is, you might need super-user rights to install packages there.

The last step is to compile the Java classes: create the directory where they will be installed into (it's the same directory that you added to the JYTHONPATH environment variable)

$ mkdir /path/to/nammu/resources/lib

and compile the classes with

$ javac -d /path/to/nammu/resources/lib /path/to/nammu/src/main/java/uk/ac/ucl/rc/development/oracc/ext/*.java

If everything went well, you should be able to run Nammu from a console.

Testing Nammu

Nammu uses pytests to make sure that it's behaving as expected. To run the test locally issue the command from the top-directory of this repository:

$ pytest python/nammu/test

Nammu is also connected to Travis CI which automatically runs the tests for every commit pushed to the remote repository and every pull request opened.

After you make a change to Nammu code (new feature, bug fix, etc...) be sure to add new tests, or update the existing ones if necessary, as appropriate.