@nav_title = 'Hacking'
@title = 'Setting up a development environment'

Setting up a development environment
====================================

This document covers how to get an enviroment ready to contribute code
to Bitmask.

Cloning the repo
----------------

> **note**
>
> Stable releases are in *master* branch. Development code lives in
> *develop* branch.

    git clone https://leap.se/git/bitmask_client
    git checkout develop

Base Dependencies
-----------------

Bitmask depends on these libraries:

-   python 2.6 or 2.7
-   qt4 libraries (see also
    Troubleshooting PySide install \<pysidevirtualenv\> about how to
    install inside your virtualenv)
-   openssl
-   [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html)

### Debian

In debian-based systems:

    $ apt-get install openvpn python-pyside python-openssl

To install the software from sources:

    $ apt-get install python-pip python-dev

Working with virtualenv
-----------------------

### Intro

*Virtualenv* is the *Virtual Python Environment builder*.

It is a tool to create isolated Python environments.

The basic problem being addressed is one of dependencies and versions,
and indirectly permissions. Imagine you have an application that needs
version 1 of LibFoo, but another application requires version 2. How can
you use both these applications? If you install everything into
/usr/lib/python2.7/site-packages (or whatever your platform's standard
location is), it's easy to end up in a situation where you
unintentionally upgrade an application that shouldn't be upgraded.

Read more about it in the [project documentation
page](http://pypi.python.org/pypi/virtualenv/).

> **note**
>
> this section could be completed with useful options that can be passed
> to the virtualenv command (e.g., to make portable paths,
> site-packages, ...). We also should document how to use
> virtualenvwrapper.

### Create and activate your dev environment

    $ virtualenv </path/to/new/environment>
    $ source </path/to/new/environment>/bin/activate

### Avoid compiling PySide inside a virtualenv

If you attempt to install PySide inside a virtualenv as part of the rest
of the dependencies using pip, basically it will take ages to compile.

As a workaround, you can run the following script after creating your
virtualenv. It will symlink to your global PySide installation (*this is
the recommended way if you are running a debian-based system*):

    $ pkg/postmkvenv.sh

A second option if that does not work for you would be to install PySide
globally and pass the `--site-packages` option when you are creating
your virtualenv:

    $ apt-get install python-pyside
    $ virtualenv --site-packages .

After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the
isntallation:

    $ export LEAP_VENV_SKIP_PYSIDE=1

And now you are ready to proceed with the next section.

### Install python dependencies

You can install python dependencies with `pip`. If you do it inside your
working environment, they will be installed avoiding the need for
administrative permissions:

    $ pip install -r pkg/requirements.pip

Copy script files
-----------------

The openvpn invocation expects some files to be in place. If you have
not installed bitmask from a debian package, you must copy these files
manually by now:

    $ sudo mkdir -p /etc/leap
    $ sudo cp pkg/linux/resolv-update /etc/leap

Running openvpn without root privileges
---------------------------------------

In linux, we are using `policykit` to be able to run openvpn without
root privileges, and a policy file is needed to be installed for that to
be possible. The setup script tries to install the policy file when
installing bitmask system-wide, so if you have installed bitmask in your
global site-packages at least once it should have copied this file for
you.

If you *only* are running bitmask from inside a virtualenv, you will
need to copy this file by hand:

    $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/

### Missing Authentication agent

If you are using linux and running a desktop other than unity or gnome,
you might get an error saying that you are not running the
authentication agent. For systems with gnome libraries installed you can
launch it like this:

    /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 &

or if you are a kde user:

    /usr/lib/kde4/libexec/polkit-kde-authentication-agent-1 &