From 297694e06ffb1eb4b191cbc164bd1d7a8ba5f46b Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Wed, 16 Oct 2013 16:39:13 -0300 Subject: Update apt-get dependencies * Also, tweak different sections to be consistent with the new quickstart. * Squashed contributions by Jeremy (@bneg) * add note about authors.rst --- docs/dev/environment.rst | 15 +++++---- docs/dev/quickstart.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/dev/workflow.rst | 5 +++ docs/index.rst | 1 + docs/testers/howto.rst | 12 +++---- 5 files changed, 100 insertions(+), 14 deletions(-) create mode 100644 docs/dev/quickstart.rst (limited to 'docs') diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst index e942b1cb..8e6fd89d 100644 --- a/docs/dev/environment.rst +++ b/docs/dev/environment.rst @@ -13,14 +13,14 @@ Cloning the repo :: - git clone git://leap.se/bitmask_client + git clone https://leap.se/git/?p=bitmask_client.git 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 ` about how to install inside your virtualenv) @@ -29,13 +29,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: @@ -122,6 +120,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:: diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst new file mode 100644 index 00000000..8f0e90dd --- /dev/null +++ b/docs/dev/quickstart.rst @@ -0,0 +1,81 @@ +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) + + +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 + $ cd bitmask_client + $ git checkout develop + + +Create and activate the virtualenv, and symlink to your gloabal PySide install:: + + $ virtualenv . + $ source bin/activate + $ pkg/postmkvenv.sh + + +Python libraries +---------------- + +.. TODO Check! -- this step should not be needed. setup develop should do it for you. +Install python requirements:: + + $ pip install -r pkg/requirements.pip + +Install the bitmask package in development mode inside the virtualenv:: + + $ ./setup.py develop + +Compile the resource files:: + + $ make + +Copy necessary files into system folders, with root privileges:: + + $ sudo mkdir -p /etc/leap + $ sudo cp pkg/linux/resolv-update /etc/leap + $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ + + +Running +-------- + +Run ``bitmask_client`` in debug mode:: + + $ 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..24a90de5 100644 --- a/docs/testers/howto.rst +++ b/docs/testers/howto.rst @@ -108,13 +108,13 @@ 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 + sudo apt-get install openvpn git-core python-dev python-pyside python-setuptools \ + python-virtualenv python-all-dev python-pip python-dev python-openssl git \ + libgnutls-dev python-qt4 g++ libsqlite3-dev -.. TODO Should review these dependencies. I think python-sqlite is missing, we - have an issue for that^^ +.. TODO Should review these dependencies. .. TODO we really should keep the dependencies in a single file that we are able to include, to avoid phasing out. @@ -132,7 +132,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 -- cgit v1.2.3 From 96e2bcb0a103130b20026c2f943e16205867ec80 Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Wed, 16 Oct 2013 17:01:23 -0300 Subject: add include to testing howto too --- docs/testers/howto.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst index 24a90de5..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 development files and dependencies needed to compile:: +First, install all the development files and dependencies needed to compile: - sudo apt-get install openvpn git-core python-dev python-pyside python-setuptools \ - python-virtualenv python-all-dev python-pip python-dev python-openssl git \ - libgnutls-dev python-qt4 g++ libsqlite3-dev - -.. TODO Should review these dependencies. - -.. 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 -- cgit v1.2.3 From e1fee7f497c5b31e88600aa2d8702b9fef78951d Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Tue, 22 Oct 2013 10:49:40 -0200 Subject: Fixes to environment.rst. Closes: #4185 --- docs/dev/environment.rst | 57 ++++++++++++++++++++++++++++++++++++++---------- docs/dev/quickstart.rst | 6 +++-- 2 files changed, 49 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst index 8e6fd89d..596d833e 100644 --- a/docs/dev/environment.rst +++ b/docs/dev/environment.rst @@ -3,7 +3,7 @@ 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 ` `section`. Cloning the repo ---------------- @@ -58,10 +58,14 @@ Read more about it in the `project documentation page - $ source /bin/activate +You first create a virtualenv in any directory that you like:: + + $ mkdir ~/Virtualenvs + $ virtualenv ~/Virtualenvs/bitmask + $ source ~/Virtualenvs/bitmask/bin/activate + +.. TODO use virtualenvwrapper + isis non-sudo recipe here .. _pysidevirtualenv: @@ -74,14 +78,10 @@ As a workaround, you can run the following script after creating your virtualenv $ 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 . +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:: -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,8 +92,32 @@ 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 + $ (bitmask) pip install -r pkg/requirements.pip + +.. _makeresources: + +Install Bitmask +--------------- + +We will be using setuptools **development mode** inside the virtualenv. It will +creaate 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. + +Make resources +-------------- + +We also need to compile the resource files:: + + $ (bitmask) make resources + +.. TODO need to make translations too? .. _copyscriptfiles: @@ -129,3 +153,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 index 8f0e90dd..978dc9e5 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -1,3 +1,5 @@ +.. _quickstart: + Quickstart ========== @@ -56,11 +58,11 @@ Install python requirements:: Install the bitmask package in development mode inside the virtualenv:: - $ ./setup.py develop + $ python2 setup.py develop Compile the resource files:: - $ make + $ make resources Copy necessary files into system folders, with root privileges:: -- cgit v1.2.3 From 1e1e65134474d65c00a0b5ed89c70fe46c56a1e5 Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Tue, 22 Oct 2013 11:09:12 -0200 Subject: add prompt indication for the virtualenv --- docs/dev/environment.rst | 50 +++++++++++++++++++++++++++++++++++------------- docs/dev/quickstart.rst | 29 ++++++++++++++-------------- 2 files changed, 51 insertions(+), 28 deletions(-) (limited to 'docs') diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst index 596d833e..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, with some explanations of what are we doing in each step along the way. For just the meat, check the :ref:`quickstart ` `section`. +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 ` 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 ` instead. Cloning the repo ---------------- @@ -13,7 +17,8 @@ Cloning the repo :: - git clone https://leap.se/git/?p=bitmask_client.git + git clone https://leap.se/git/?p=bitmask_client.git bitmask + cd bitmask git checkout develop .. XXX change this when repo changes. @@ -64,6 +69,9 @@ 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 @@ -76,7 +84,7 @@ 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 ``--system-site-packages`` option when you are creating your virtualenv:: @@ -90,32 +98,48 @@ 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 + (bitmask)$ pip install -r pkg/requirements.pip -.. _makeresources: +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: Install Bitmask --------------- -We will be using setuptools **development mode** inside the virtualenv. It will -creaate 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.:: +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 + (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 + (bitmask)$ make resources + +You need to repeat this step each time you change a ``.ui`` file. .. TODO need to make translations too? @@ -161,4 +185,4 @@ 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 + (bitmask)$ bitmask --debug diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index 978dc9e5..8ef7dfb8 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -13,6 +13,9 @@ to build the latest development code for ``bitmask_client`` 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 `. + Prerequisites ------------- @@ -36,8 +39,8 @@ Prerequisites Clone the repo into your working directory, and checkout development branch:: - $ git clone https://github.com/leapcode/bitmask_client - $ cd bitmask_client + $ git clone https://github.com/leapcode/bitmask_client bitmask + $ cd bitmask $ git checkout develop @@ -45,30 +48,26 @@ Create and activate the virtualenv, and symlink to your gloabal PySide install:: $ virtualenv . $ source bin/activate - $ pkg/postmkvenv.sh + (bitmask)$ pkg/postmkvenv.sh Python libraries ---------------- -.. TODO Check! -- this step should not be needed. setup develop should do it for you. -Install python requirements:: - - $ pip install -r pkg/requirements.pip - -Install the bitmask package in development mode inside the virtualenv:: +Install the bitmask package in development mode inside the virtualenv. This will +also install the needed dependencies:: - $ python2 setup.py develop + (bitmask)$ python2 setup.py develop Compile the resource files:: - $ make resources + (bitmask)$ make resources Copy necessary files into system folders, with root privileges:: - $ sudo mkdir -p /etc/leap - $ sudo cp pkg/linux/resolv-update /etc/leap - $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ + (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 @@ -76,7 +75,7 @@ Running Run ``bitmask_client`` in debug mode:: - $ bitmask --debug + (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 -- cgit v1.2.3