Merge remote-tracking branch 'kali/feature/quickstart-and-deps' into develop

1 files changed, 78 insertions, 22 deletions

diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst
index e942b1cb..0f6366ef 100644
--- a/docs/dev/environment.rst
+++ b/docs/dev/environment.rst
@@ -3,7 +3,11 @@
 Setting up a development environment
 ====================================
 
-This document covers how to get an enviroment ready to contribute code to Bitmask.
+This document covers how to get an enviroment ready to contribute code to
+Bitmask, with some explanations of what are we doing in each step along the way.
+For just the meat, check the :ref:`quickstart <quickstart>` section. If you only
+want to do a a quick fetch of the latest code for casual testing, you can use
+the :ref:`bootstrap script <fetchinglatest>` instead.
 
 Cloning the repo
 ----------------
@@ -13,14 +17,15 @@ Cloning the repo
 
 ::
 
-    git clone git://leap.se/bitmask_client
+    git clone https://leap.se/git/?p=bitmask_client.git bitmask
+    cd bitmask
     git checkout develop
 
 .. XXX change this when repo changes.
 
 Base Dependencies
 ------------------
-Bitmask depends on these libraries:
+Bitmask depends on these base libraries:
 
 * `python 2.6 or 2.7`
 * `qt4` libraries (see also :ref:`Troubleshooting PySide install <pysidevirtualenv>` about how to install inside your virtualenv)
@@ -29,13 +34,11 @@ Bitmask depends on these libraries:
 
 Debian
 ^^^^^^
-In debian-based systems::
+In debian-based systems, you can get everything you need:
 
-  $ apt-get install openvpn python-pyside python-openssl
-
-To install the software from sources::
-
-  $ apt-get install python-pip python-dev
+.. include:: quickstart.rst
+   :start-after: begin-debian-deps
+   :end-before: end-debian-deps
 
 .. _virtualenv:
 
@@ -60,10 +63,17 @@ Read more about it in the `project documentation page <http://pypi.python.org/py
 
 Create and activate your dev environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-::
 
-    $ virtualenv </path/to/new/environment>
-    $ source </path/to/new/environment>/bin/activate
+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.
+
+.. TODO use virtualenvwrapper + isis non-sudo recipe here 
 
 .. _pysidevirtualenv:
 
@@ -74,16 +84,12 @@ If you attempt to install PySide inside a virtualenv as part of the rest of the
 
 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
+    (bitmask)$ 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::
+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 --site-packages .
-
-After that, you must export ``LEAP_VENV_SKIP_PYSIDE`` to skip the isntallation::
-
-    $ export LEAP_VENV_SKIP_PYSIDE=1
+    $ sudo apt-get install python-pyside
+    $ virtualenv --system-site-packages .
 
 And now you are ready to proceed with the next section.
 
@@ -92,10 +98,50 @@ 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::
+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::
+
+    (bitmask)$ 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.
+
+.. _installbitmaskdevelop:
 
-    $ pip install -r pkg/requirements.pip
+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
+
+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.
+
+.. _makeresources:
+
+Make resources
+--------------
+
+We also need to compile the resource files::
+
+    (bitmask)$ make resources
+
+You need to repeat this step each time you change a ``.ui`` file.
+
+.. TODO need to make translations too?
 
 .. _copyscriptfiles:
 
@@ -122,6 +168,7 @@ If you *only* are running bitmask from inside a virtualenv, you will need to cop
 
 Missing Authentication agent
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. TODO I think we could be safely removing this section by now.
 
 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::
 
@@ -130,3 +177,12 @@ If you are using linux and running a desktop other than unity or gnome, you migh
 or if you are a kde user::
 
    /usr/lib/kde4/libexec/polkit-kde-authentication-agent-1 &
+
+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