diff options
| -rw-r--r-- | README.rst | 22 | ||||
| -rw-r--r-- | docs/dev/environment.rst | 100 | ||||
| -rw-r--r-- | docs/dev/quickstart.rst | 82 | ||||
| -rw-r--r-- | docs/dev/workflow.rst | 5 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/testers/howto.rst | 15 |
6 files changed, 182 insertions, 43 deletions
@@ -41,15 +41,22 @@ Getting dependencies under debian With a Debian based system, to be able to run Bitmask you need to run the following command:: - $ sudo apt-get install openvpn python-pyside pyside-tools python-setuptools python-all-dev python-pip python-dev python-openssl + $ sudo apt-get install git python-dev python-setuptools + python-virtualenv python-pip python-openssl libsqlite3-dev g++ openvpn + pyside-tools python-pyside Installing ----------- -After getting the source and installing all the dependencies, proceed to install ``bitmask`` package:: +Quick install, from the cheese shop:: + + $ sudo pip install leap.bitmask + +If you prefer to install from sources:: + + $ make + $ sudo python2 setup.py install - $ make - $ sudo python2 setup.py install Running ------- @@ -102,13 +109,6 @@ Run Bitmask:: (bitmask)$ bitmask --debug - -If you are testing a new provider that doesn't have the proper certificates yet, you can use --danger flag, but **DO NOT use it on a regular basis**. - -**WARNING**: If you use the --danger flag you may be victim to a MITM_ attack without noticing. Use at your own risk. - -.. _MITM: http://en.wikipedia.org/wiki/Man-in-the-middle_attack - Testing ======= 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 diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst new file mode 100644 index 00000000..8ef7dfb8 --- /dev/null +++ b/docs/dev/quickstart.rst @@ -0,0 +1,82 @@ +.. _quickstart: + +Quickstart +========== + +**Assumptions:** These instructions were made on a clean Ubuntu 12.04.3 +system. + +**Goal:** With minimal effort or reading install the necessary packages +to build the latest development code for ``bitmask_client`` + +**Outcome:** At the end of these instructions, you should be able to run +the latest development branch for bitmask client, getting the GUI in debug +mode and connect to a LEAP provider (bitmask.net) + +If you want to know what each step is for, check +:ref:`this other section <environment>`. + + +Prerequisites +------------- + +.. begin-debian-deps +:: + + $ sudo apt-get install git python-dev python-setuptools + python-virtualenv python-pip python-openssl libsqlite3-dev g++ openvpn + pyside-tools python-pyside + +.. python-qt4 ??? (for translations) +.. TODO I'm pretty sure python-qt4 shoudln't be there... + Nor libsqlite-dev, that's a bug in python-sqlcipher/soledad. + + +.. XXX any change HERE ^^^^ should be reflected also in README.rst. + From any other place in the documentation, it should be just included. + +.. end-debian-deps + +Clone the repo into your working directory, and checkout development branch:: + + $ git clone https://github.com/leapcode/bitmask_client bitmask + $ cd bitmask + $ git checkout develop + + +Create and activate the virtualenv, and symlink to your gloabal PySide install:: + + $ virtualenv . + $ source bin/activate + (bitmask)$ pkg/postmkvenv.sh + + +Python libraries +---------------- + +Install the bitmask package in development mode inside the virtualenv. This will +also install the needed dependencies:: + + (bitmask)$ python2 setup.py develop + +Compile the resource files:: + + (bitmask)$ make resources + +Copy necessary files into system folders, with root privileges:: + + (bitmask)$ sudo mkdir -p /etc/leap + (bitmask)$ sudo cp pkg/linux/resolv-update /etc/leap + (bitmask)$ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ + + +Running +-------- + +Run ``bitmask_client`` in debug mode:: + + (bitmask)$ bitmask --debug + +You should see the ``bitmask_client`` window prompting to connect to an +existing node or add a new one. If not, something went wrong, maybe ask +on #leap-dev at irc.freenode.net diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst index abd228c1..f217df24 100644 --- a/docs/dev/workflow.rst +++ b/docs/dev/workflow.rst @@ -90,3 +90,8 @@ Other methods ------------- Feel free to use any other methods like format-patch and mail or whatever method you prefer, although we recommend you follow the same workflow as we do. + +Contributors +------------ + +Please, add yourself to ``dev/authors.rst`` if you contribute code to Bitmask. diff --git a/docs/index.rst b/docs/index.rst index d0b0ff22..f210be8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,6 +44,7 @@ If you want to contribute to the project, we wrote this for you. .. toctree:: :maxdepth: 1 + dev/quickstart dev/environment dev/tests dev/workflow diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index 1e276f7d..d9536632 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -108,16 +108,11 @@ compact way suitable (ahem) also for non developers. Install dependencies ^^^^^^^^^^^^^^^^^^^^ -First, install all the base dependencies plus git, virtualenv and development -files needed to compile several extensions:: +First, install all the development files and dependencies needed to compile: - apt-get install openvpn git-core python-dev python-pyside python-setuptools python-virtualenv - -.. TODO Should review these dependencies. I think python-sqlite is missing, we - have an issue for that^^ - -.. TODO we really should keep the dependencies in a single file that we are able to - include, to avoid phasing out. +.. include:: ../dev/quickstart.rst + :start-after: begin-debian-deps + :end-before: end-debian-deps Bootstrap script @@ -132,7 +127,7 @@ Download and source the following script in the parent folder where you want you .. code-block:: bash - cd /tmp + cd /tmp wget https://raw.github.com/leapcode/bitmask_client/develop/pkg/scripts/bitmask_bootstrap.sh source bitmask_bootstrap.sh |