7ef8245cc3d7423dd4063cfc74e7113984825ece
[leap_doc.git] / docs / client / dev-environment.md
1 @nav_title = 'Hacking'
2 @title = 'Setting up a development environment'
3
4 Setting up a development environment
5 ====================================
6
7 This document covers how to get an environment ready to contribute code
8 to Bitmask.
9
10 Cloning the repo
11 ----------------
12
13 > **note**
14 >
15 > Stable releases are in *master* branch. Development code lives in
16 > *develop* branch.
17
18     git clone https://leap.se/git/bitmask_client
19     git checkout develop
20
21 Dependencies
22 ------------
23
24 Bitmask depends on these libraries:
25
26 - python 2.6 or 2.7
27 - qt4 libraries
28 - openssl
29 - [openvpn](http://openvpn.net/index.php/open-source/345-openvpn-project.html)
30
31 ### Install dependencies in a Debian based distro
32
33 In debian-based systems:
34
35     $ sudo apt-get install git python-dev python-setuptools python-virtualenv python-pip libssl-dev python-openssl libsqlite3-dev g++ openvpn pyside-tools python-pyside libffi-dev
36
37
38 Working with virtualenv
39 -----------------------
40
41 ### Intro
42
43 *Virtualenv* is the *Virtual Python Environment builder*.
44
45 It is a tool to create isolated Python environments.
46
47 > The basic problem being addressed is one of dependencies and versions,
48 and indirectly permissions. Imagine you have an application that needs
49 version 1 of LibFoo, but another application requires version 2. How can
50 you use both these applications? If you install everything into
51 `/usr/lib/python2.7/site-packages` (or whatever your platform's standard
52 location is), it's easy to end up in a situation where you
53 unintentionally upgrade an application that shouldn't be upgraded.
54
55 Read more about it in the [project documentation
56 page](http://www.virtualenv.org/en/latest/virtualenv.html).
57
58 ### Create and activate your dev environment
59
60 You first create a virtualenv in any directory that you like:
61
62     $ mkdir ~/Virtualenvs
63     $ virtualenv ~/Virtualenvs/bitmask
64     $ source ~/Virtualenvs/bitmask/bin/activate
65     (bitmask)$
66
67 Note the change in the prompt.
68
69 ### Avoid compiling PySide inside a virtualenv
70
71 If you attempt to install PySide inside a virtualenv as part of the rest
72 of the dependencies using pip, basically it will take ages to compile.
73
74 As a workaround, you can run the following script after creating your
75 virtualenv. It will symlink to your global PySide installation (*this is
76 the recommended way if you are running a debian-based system*):
77
78     $ pkg/postmkvenv.sh
79
80 A second option if that does not work for you would be to install PySide
81 globally and pass the `--system-site-packages` option when you are creating
82 your virtualenv:
83
84     $ apt-get install python-pyside
85     $ virtualenv --system-site-packages .
86
87 After that, you must export `LEAP_VENV_SKIP_PYSIDE` to skip the
88 installation:
89
90     $ export LEAP_VENV_SKIP_PYSIDE=1
91
92 And now you are ready to proceed with the next section.
93
94 ### Install python dependencies
95
96 You can install python dependencies with `pip`. If you do it inside your
97 working environment, they will be installed avoiding the need for
98 administrative permissions:
99
100     $ pip install -r pkg/requirements.pip
101
102 This step is not strictly needed, since the `setup.py develop` in the next
103 paragraph with also fetch the needed dependencies. But you need to know abou it:
104 when you or any person in the development team will be adding a new dependency,
105 you will have to repeat this command so that the new dependencies are installed
106 inside your virtualenv.
107
108 Install Bitmask
109 ---------------
110
111 Normally we would install the `leap.bitmask` package as any other package
112 inside the virtualenv.
113 But, instead, we will be using setuptools **development mode**. The difference
114 is that, instead of installing the package in a permanent location in your
115 regular installed packages path, it will create a link from the local
116 site-packages to your working directory. In this way, your changes will always
117 be in the installation path without need to install the package you are working
118 on.::
119
120     (bitmask)$ python2 setup.py develop
121
122 After this step, your Bitmask launcher will be located at
123 `~/Virtualenvs/bitmask/bin/bitmask`, and it will be in the path as long as you
124 have sourced your virtualenv.
125
126 Compile Qt resources
127 --------------------
128
129 We also need to compile the resource files:
130
131     (bitmask)$ make
132
133 Note: you need to repeat this step each time you change a `.ui` file.
134
135 Running openvpn without root privileges
136 ---------------------------------------
137
138 In linux, we are using `policykit` to be able to run openvpn without root
139 privileges, and a policy file is needed to be installed for that to be
140 possible.
141 The setup script tries to install the policy file when installing bitmask
142 system-wide, so if you have installed bitmask in your global site-packages at
143 least once it should have copied this file for you.
144
145 If you *only* are running bitmask from inside a virtualenv, you will need to
146 copy this file by hand:
147
148     $ sudo cp pkg/linux/polkit/se.leap.bitmask.policy /usr/share/polkit-1/actions/
149
150
151 Running!
152 --------
153
154 If everything went well, you should be able to run your client by invoking
155 `bitmask`. If it does not get launched, or you just want to see more verbose
156 output, try the debug mode:
157
158    (bitmask)$ bitmask --debug
159
160
161 Using automagic helper script
162 -----------------------------
163
164 You can use a helper script that will get you started with bitmask and all the related repos.
165
166 1. install system dependencies
167 2. download automagic script
168 3. run it :)
169
170 Commands so you can copy/paste:
171
172     $ mkdir bitmask && cd bitmask
173     $ wget https://raw.githubusercontent.com/leapcode/bitmask_client/develop/pkg/scripts/bootstrap_develop.sh
174     $ chmod +x bootstrap_develop.sh
175     $ ./bootstrap_develop.sh init  # use help parameter for more information
176
177 This script allows you to get started, update and run the bitmask app with all its repositories.
178
179 Note: you need to copy the polkit file manually.