summaryrefslogtreecommitdiff
path: root/pages/docs/client/dev-environment.md
blob: d1bd7a3f2c92ea58ee37af6a5e728a4866042c84 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
@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