summaryrefslogtreecommitdiff
path: root/README.rst
diff options
context:
space:
mode:
authordrebs <drebs@leap.se>2012-12-24 10:14:58 -0200
committerdrebs <drebs@leap.se>2012-12-24 10:14:58 -0200
commit319e279b59ac080779d0a3375ae4d6582f5ee6a3 (patch)
tree118dd0f495c0d54f2b2c66ea235e4e4e6b8cefd5 /README.rst
parentca5fb41a55e1292005ed186baf3710831d9ad678 (diff)
parenta7b091a0553e6120f3e0eb6d4e73a89732c589b2 (diff)
Merge branch 'develop' of ssh://code.leap.se/leap_client into develop
Diffstat (limited to 'README.rst')
-rw-r--r--README.rst177
1 files changed, 63 insertions, 114 deletions
diff --git a/README.rst b/README.rst
index cc30c544..01e1c151 100644
--- a/README.rst
+++ b/README.rst
@@ -4,168 +4,117 @@ The LEAP Encryption Access Project Client
*your internet encryption toolkit*
-Installation
-=============
-
-Base Dependencies
-------------------
-Leap client depends on these libraries:
-
-* python 2.6 or 2.7
-* qt4 libraries (see installing Qt section below)
-* libgnutls
-* openvpn
-
-Python packages are listed in ``pkg/requirements.pip`` and ``pkg/test-requirements.pip``
-
-Debian systems
---------------
-# XXX TODO: move to packaging doc.
-
-* python-qt4
-* python-crypto
-* python setuptools
-* python-nose, python-mock, python-coverage (if you want to run tests)
-
-Note: these two need a version that is not found in the current debian stable or in ubuntu 12.04.
-
-* python-gnutls == 1.1.9
-* python-keyring
-
-Under a debian-based system, you can run::
-
- # apt-get install openvpn python-qt4 python-crypto
+Read the docs!
+==============
-For testing:
+You can read the documentation online at `http://leap-client.readthedocs.org <http://leap-client.readthedocs.org/en/latest/>`_. If you prefer to build it locally, run::
- python-nose python-mock python-coverage
+ $ cd docs
+ $ make html
-For _building_ the package you will need to install also::
+Quick Start
+==============
- pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
+At the current development stage we still do not have any versioned release. Instead, you might want to have a look at the `testers guide<http://leap-client.readthedocs.org/en/latest/testers/howto.html>`_ for a quick howto on fetching and testing latest development code.
+Dependencies
+------------------
-Install python dependencies with pip
--------------------------------------
-# XXX TODO: move to developers doc.
+Leap client depends on these libraries:
-Use pip (preferrable inside a virtualenv) to install the required python packages::
+* ``python 2.6`` or ``2.7``
+* ``qt4 libraries``
+* ``libgnutls``
+* ``openvpn``
- # apt-get install python-pip python-dev libgnutls-dev
- % pip install -r pkg/requirements.pip
+Python packages are listed in ``pkg/requirements.pip`` and ``pkg/test-requirements.pip``
+Debian
+^^^^^^
-Install leap-client
--------------------
+Under a debian-based system, you can run::
-After getting the source and installing all the dependencies, proceed to install ``leap-client`` package:
+ $ apt-get install openvpn python-qt4 python-crypto python-requests python-gnutls
-# run this if you have installed previous versions before::
+For *testing*::
- python setup.py clean
+ $ apt-get install python-nose python-mock python-coverage
-And finally, build and install leap-client::
+For *building* the package you will need to install also::
- python setup.py install # as root if installing globally.
+ $ apt-get install pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
-Running the App
------------------
+pip
+^^^
-After a successful installation, there should be a launcher called leap-client somewhere in your path::
+Use pip to install the required python packages::
- % leap-client
+ $ apt-get install python-pip python-dev libgnutls-dev
+ $ pip install -r pkg/requirements.pip
-In order to run the client in debug mode::
- % leap-client --debug --logfile /tmp/leap.log
+Installing
+-----------
-To see all the available command line options::
+After getting the source and installing all the dependencies, proceed to install ``leap-client`` package::
- % leap-client --help
+ $ python setup.py install
-Development
-==============
+Running
+-------
-Troubleshooting PyQt install inside a virtualenv
-------------------------------------------------
-If you attempt to install PyQt inside a virtualenv using pip, it will fail because PyQt4 does not use the standard setup.py mechanism.
+After a successful installation, there should be a launcher called ``leap-client`` somewhere in your path::
-As a workaround, you can:
+ $ leap-client
- * run pkg/postmkvenv.sh after creating your virtualenv. It will symlink to your global PyQt installation _(recommended)_.
- * install PyQt globally and make a virtualenv with --site-packages
-Or, if you prefer, you can download the official PyQt tarball and execute `configure.py` in the root folder of their distribution, which generates a Makefile::
+Hacking
+=======
- python configure.py
- make && make install
+See the `hackers guide<http://leap-client.readthedocs.org/en/latest/dev/environment.html>`_
+The LEAP client git repository is available at::
-Hack
---------------
-
-The LEAP client git repository is available at:
-git://leap.se/leap_client
+ git://leap.se/leap_client
Some steps need 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
-
-# make sure you are in the development branch::
-
- (leap_client)% git checkout develop
- (leap_client)% pkg/postmkvenv.sh
- (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::
-
- (leap_client)% cd src/leap
- (leap_client)% python app.py --debug
+Enable a **virtualenv** to isolate your libraries. (Current *.gitignore* knows about a virtualenv in the root tree. If you do not like that place, just change ``.`` for *<path.to.environment>*)::
-Install testing dependencies
-----------------------------
+ $ virtualenv .
+ $ source bin/activate
-have a look at ``pkg/test-requirements.pip``
-The ./run_tests.sh command should install all of them in your virtualenv for you.
+Make sure you are in the development branch::
-Running tests
--------------
+ (leap_client)$ git checkout develop
-There is a convenience script at ``./run_tests.sh``
+Symlink your global pyqt libraries::
-If you want to run specific tests, pass the (sub)module to nose::
- nosetests leap.util
+ (leap_client)$ pkg/postmkvenv.sh
-or::
- nosetests leap.util.tests.test_leap_argparse
+And make your working tree available to your pythonpath::
-Hint: colorized output
-----------------------
-Install ``rednose`` locally and activate it, and give your eyes a rest :)::
+ (leap_client)$ python setup.py develop
- (leap_client)% pip install rednose
- (leap_client)% export NOSE_REDNOSE=1
+Testing
+=======
-Tox
----
-For running testsuite against all the supported python versions (currently 2.6 and 2.7), run::
+Have a look at ``pkg/test-requirements.pip`` for the tests dependencies.
- % tox -v
+To run the test suite::
+ $ ./run_tests.sh
+
+which the first time should automagically install all the needed dependencies in your virtualenv for you.
-Compiling resource/ui files
------------------------------
+License
+=======
-You should refresh resource/ui files every time you change an image or a resource/ui (.ui / .qc). From the root folder::
+.. image:: https://raw.github.com/leapcode/leap_client/develop/docs/user/gpl.png
- % make ui
- % make resources
+The LEAP Client is released under the terms of the `GNU GPL version 3`_ or later.
-As there are some tests to guard against unwanted resource updates, you will have to update the resource hash in those failing tests.
+.. _`GNU GPL version 3`: http://www.gnu.org/licenses/gpl.txt