summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.rst154
-rw-r--r--pkg/requirements.pip3
2 files changed, 83 insertions, 74 deletions
diff --git a/README.rst b/README.rst
index 183229fe..dd8ee425 100644
--- a/README.rst
+++ b/README.rst
@@ -1,88 +1,105 @@
-LEAP
-The LEAP Encryption Access Project
-your internet encryption toolkit
+=========================================
+The LEAP Encryption Access Project Client
+=========================================
+
+*your internet encryption toolkit*
Installation
=============
-Dependencies
---------------
-Listed in pkg/requirements.pip and pkg/test-requirements.pip
+Base Dependencies
+------------------
+Leap client depends on these libraries:
* python 2.6 or 2.7
-* python setuptools
-* qt4 libraries
+* qt4 libraries (see installing Qt section below)
+* libgnutls
+
+Python packages are listed in ``pkg/requirements.pip`` and ``pkg/test-requirements.pip``
+
+Debian systems
+--------------
+
* python-qt4
* python-gnutls == 1.1.9
* python-keyring
+* python-crypto
+* python setuptools
* python-nose, python-mock, python-coverage (if you want to run tests)
-If you are on a debian-based system, you can run:
+Under a debian-based system, you can run::
- apt-get install python-qt4 python-qt4-doc pyqt4-dev-tools python-gnutls libgnutls-dev python-setuptools python-nose
+ apt-get install python-qt4 python-gnutls python-keyring python-crypto
+
+For testing:
-# **note**: I think setuptools is needed for build process only.
-# we should separate what's needed as a lib dependency, and what's a dependency that has been debianized but
-# still can be retrieved using pip.
+ python-nose python-mock
-If you are installing in a virtualenv:
+For building the package you will need also::
- pip install -r pkg/requirements.pip
+ pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
-# **note**: I _think_ setuptools is needed for build process only.
-# we should separate what's needed as a global lib dependency, and what's a dependency that
-# still can be retrieved using pip.
-
-If you are installing in a virtualenv:
+# **note**: Some libs like setuptools are needed as build-deps only.
+# TODO we probably should separate what's needed as a global lib dependency, and what's a dependency that still can be retrieved using pip.
+
+Install python dependencies with pip
+-------------------------------------
+Use pip (preferrable inside a virtualenv) to install all the required python packages::
+
+ apt-get install python-pip
pip install -r pkg/requirements.pip
Install PyQt
------------
-pip install PyQt will fail because PyQt4 does not use the standard setup.py mechanism.
-Instead, they use configure.py which generates a Makefile.
+If you are using pip as your python packaging tool, pip install PyQt will fail because PyQt4 does not use the standard setup.py mechanism.
+
+Instead, they use configure.py which generates a Makefile::
-python configure.py
-make && make install
+ python configure.py
+ make && make install
You can:
-* (recommended) run pkg/postmkvenv.sh after creating your virtualenv. It will symlink to your global PyQt installation.
+* recommended run pkg/postmkvenv.sh after creating your virtualenv. It will symlink to your global PyQt installation.
* install PyQt globally and make a virtualenv with --site-packages
* run pkg/install_pyqt.sh inside your virtualenv (with --no-site-packages)
-Install
----------------
+Install leap-client
+-------------------
+
+After getting the sources and installing all the dependencies, proceed to install leap-client package:
# need to run this if you are installing from the git source tree
-# not needed if installing from a tarball.
+# not needed if installing from a tarball::
-python setup.py branding
+ python setup.py branding
-# run this if you have installed previous versions before
+# run this if you have installed previous versions before::
-python setup.py clean
+ python setup.py clean
-python setup.py install # as root if installing globally.
+And finally, build and install leap-client::
+ python setup.py install # as root if installing globally.
Running the App
-----------------
If you're running a branded build, the script name will have a infix that
-depends on your build flavor. Look for it in /usr/local/bin
+depends on your build flavor. Look for it in ``/usr/local/bin``::
-% leap-springbok-client
+ % leap-springbok-client
-In order to run in debub mode:
+In order to run the client in debug mode::
-% leap-springbok-client --debug --logfile /tmp/leap.log
+ % leap-springbok-client --debug --logfile /tmp/leap.log
-To see all options:
+To see all the available command line options::
-% leap-springbok-client --help
+ % leap-springbok-client --help
Development
@@ -93,60 +110,52 @@ Hack
Some steps to be run when setting a development environment for the first time.
-# recommended: enable a virtualenv to isolate your libraries.
-
-% virtualenv . # ensure your .gitignore knows about it
-% source bin/activate
+# recommended: enable a **virtualenv** to isolate your libraries::
-# make sure you're in the development branch
+ % virtualenv . # ensure your .gitignore knows about it
+ % source bin/activate
-(leap_client)% git checkout develop
+# make sure you are in the development branch::
-(leap_client)% pkg/postmkvenv.sh
-
-(leap_client)% python setup.py branding
-(leap_client)% python setup.py develop
+ (leap_client)% git checkout develop
+ (leap_client)% pkg/postmkvenv.sh
+ (leap_client)% python setup.py branding
+ (leap_client)% python setup.py develop
to avoid messing with the entry point and global versions installed,
-it's recommended to run the app like this during development cycle:
+it's recommended to run the app like this during development cycle::
-(leap_client)% cd src/leap
-(leap_client)% python app.py --debug
+ (leap_client)% cd src/leap
+ (leap_client)% python app.py --debug
Install testing dependencies
----------------------------
-have a look at setup/test-requires
+have a look at ``setup/test-requires``
The ./run_tests.sh command should install all of them in your virtualenv for you.
Running tests
-------------
-./run_tests.sh
-
-force no virtualenv and create coverage reports:
-./run_tests.sh -N -c
-
-if you want to run specific tests, pass the (sub)module to nose:
-
-nosetests leap.util
+There is a convenience script at ``./run_tests.sh``
-or
+If you want to run specific tests, pass the (sub)module to nose::
+ nosetests leap.util
-nosetests leap.util.test_leap_argparse
+or::
+ nosetests leap.util.test_leap_argparse
-Colorized output
-----------------
-Install rednose locally and activate it.
+Hint: colorized output
+----------------------
+Install ``rednose`` locally and activate it, and give your eyes a rest :)::
(leap_client)% pip install rednose
(leap_client)% export NOSE_REDNOSE=1
-enjoy :)
Tox
---
-For running testsuite against all the supported python versions (currently 2.6 and 2.7), run:
+For running testsuite against all the supported python versions (currently 2.6 and 2.7), run::
tox -v
@@ -154,12 +163,9 @@ For running testsuite against all the supported python versions (currently 2.6 a
Compiling resource/ui files
-----------------------------
-You should refresh resource/ui files every time you
-change an image or a resource/ui (.ui / .qc). From
-the root folder:
+You should refresh resource/ui files every time you change an image or a resource/ui (.ui / .qc). From the root folder::
-make ui
-make resources
+ make ui
+ make resources
-As there are some tests to guard against unwanted resource updates,
-you will have to update the resource hash in those failing tests.
+As there are some tests to guard against unwanted resource updates, you will have to update the resource hash in those failing tests.
diff --git a/pkg/requirements.pip b/pkg/requirements.pip
index 2406884d..e5338744 100644
--- a/pkg/requirements.pip
+++ b/pkg/requirements.pip
@@ -1,3 +1,6 @@
+# in order of addition to the project.
+# do not change it, we will freeze the requirements before tagging a release.
+
argparse # only for python 2.6
requests
ping