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

Quick start
===========

This document will guide you to get an environment ready to contribute code to
Bitmask.

Using an automagic script
=========================

You can use a helper script that will get you started with bitmask and all the
related repos.

1. download automagic script
2. run it :)

Commands so you can copy/paste:

    $ mkdir bitmask && cd bitmask
    $ wget https://raw.githubusercontent.com/leapcode/bitmask_client/develop/pkg/scripts/bootstrap_develop.sh
    $ chmod +x bootstrap_develop.sh
    $ ./bootstrap_develop.sh help    # check out the options :)
    $ ./bootstrap_develop.sh deps    # requires sudo
    $ ./bootstrap_develop.sh init ro
    $ ./bootstrap_develop.sh helpers # requires sudo
    $ ./bootstrap_develop.sh run

This script allows you to get started, update and run the bitmask app with all
its repositories.

Note: the `deps` option is meant to be used in a Debian based Linux distro.


Doing the work manually
=======================

Clone 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

Install Dependencies
--------------------

Bitmask depends on these libraries:

- python 2.6 or 2.7
- qt4 libraries
- openssl
- [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html)

### Install dependencies in a Debian based distro

In debian-based systems:

    $ sudo apt-get install git make python-dev python-setuptools python-virtualenv python-pip libssl-dev python-openssl libsqlite3-dev g++ openvpn pyside-tools python-pyside libffi-dev libzmq-dev protobuf-compiler


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://www.virtualenv.org/en/latest/virtualenv.html).

### Create and activate your dev environment

You first create a virtualenv in any directory that you like:

    $ mkdir ~/Virtualenvs
    $ virtualenv ~/Virtualenvs/bitmask
    $ source ~/Virtualenvs/bitmask/bin/activate
    (bitmask)$

Note the change in the prompt.

### 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 `--system-site-packages` option when you are creating
your virtualenv:

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

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

    $ 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

This step is not strictly needed, since the `setup.py develop` in the next
paragraph with also fetch the needed dependencies. But you need to know abou it:
when you or any person in the development team will be adding a new dependency,
you will have to repeat this command so that the new dependencies are installed
inside your virtualenv.

Install Bitmask
---------------

Normally we would install the `leap.bitmask` package as any other package
inside the virtualenv.
But, instead, we will be using setuptools **development mode**. The difference
is that, instead of installing the package in a permanent location in your
regular installed packages path, it will create a link from the local
site-packages to your working directory. In this way, your changes will always
be in the installation path without need to install the package you are working
on.::

    (bitmask)$ python2 setup.py develop --always-unzip

After this step, your Bitmask launcher will be located at
`~/Virtualenvs/bitmask/bin/bitmask`, and it will be in the path as long as you
have sourced your virtualenv.

Note: the `--always-unzip` option prevents some dependencies to be installed in
a zip/egg, which causes some issues with libraries like 'scrypt' that needs to
access to the files directly from the filesystem.

Compile Qt resources
--------------------

We also need to compile the resource files:

    (bitmask)$ make

Note: you need to repeat this step each time you change a `.ui` file.

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/se.leap.bitmask.policy /usr/share/polkit-1/actions/

Installing the bitmask EIP helper
---------------------------------

In linux, we have a `openvpn` and `firewall` helper that is needed to run EIP.
You need to manually copy it from `bitmask_client/pkg/linux/bitmask-root`.
Use the following command to do so:

    $ sudo cp bitmask_client/pkg/linux/bitmask-root /usr/sbin/


Running!
--------

If everything went well, you should be able to run your client by invoking
`bitmask`. If it does not get launched, or you just want to see more verbose
output, try the debug mode:

   (bitmask)$ bitmask --debug