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