From 652879ef39b5a94fba50f8c78524e71e040e8b5b Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Wed, 25 Sep 2013 12:28:21 -0400 Subject: update client docs This are the most important pages in the bitmask documentation. I have converted .rst files using pandoc, since the .rst does not seem to be supported like the README says. I have added @nav_title and @title headers. --- docs/client/dev-environment.md | 144 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/client/dev-environment.md (limited to 'docs/client/dev-environment.md') diff --git a/docs/client/dev-environment.md b/docs/client/dev-environment.md new file mode 100644 index 0000000..c788251 --- /dev/null +++ b/docs/client/dev-environment.md @@ -0,0 +1,144 @@ +@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 git://leap.se/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 \ 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 + $ source /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 & -- cgit v1.2.3