summaryrefslogtreecommitdiff
path: root/README.rst
diff options
context:
space:
mode:
Diffstat (limited to 'README.rst')
-rw-r--r--README.rst172
1 files changed, 63 insertions, 109 deletions
diff --git a/README.rst b/README.rst
index cc30c544..d8e055da 100644
--- a/README.rst
+++ b/README.rst
@@ -4,168 +4,122 @@ The LEAP Encryption Access Project Client
*your internet encryption toolkit*
-Installation
+Read the docs!
+==============
+
+You can read the documentation online at `http://leap-client.readthedocs.org <http://http://leap-client.readthedocs.org/en/latest/>`_. If you prefer to build it locally, run::
+
+ $ cd docs
+ $ make html
+
+Quick Start
=============
-Base Dependencies
+Dependencies
------------------
+
Leap client depends on these libraries:
-* python 2.6 or 2.7
-* qt4 libraries (see installing Qt section below)
-* libgnutls
-* openvpn
+* ``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
+Debian
+^^^^^^
Under a debian-based system, you can run::
- # apt-get install openvpn python-qt4 python-crypto
+ $ apt-get install openvpn python-qt4 python-crypto python-requests python-gnutls
-For testing:
+For *testing*::
- python-nose python-mock python-coverage
+ $ apt-get install python-nose python-mock python-coverage
-For _building_ the package you will need to install also::
+For *building* the package you will need to install also::
- pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
+ $ apt-get install pyqt4-dev-tools libgnutls-dev python-setuptools python-all-dev
-Install python dependencies with pip
--------------------------------------
-# XXX TODO: move to developers doc.
+pip
+^^^
-Use pip (preferrable inside a virtualenv) to install the required python packages::
+Use pip to install the required python packages::
- # apt-get install python-pip python-dev libgnutls-dev
- % pip install -r pkg/requirements.pip
+ $ apt-get install python-pip python-dev libgnutls-dev
+ $ pip install -r pkg/requirements.pip
-Install leap-client
--------------------
+Installing
+-----------
After getting the source and installing all the dependencies, proceed to install ``leap-client`` package:
-# run this if you have installed previous versions before::
-
- python setup.py clean
+.. note::
+ if you have installed previous versions before::
+ python setup.py clean
And finally, build and install leap-client::
- python setup.py install # as root if installing globally.
+ python setup.py install
-Running the App
------------------
+Running
+-------
-After a successful installation, there should be a launcher called leap-client somewhere in your path::
+After a successful installation, there should be a launcher called ``leap-client`` somewhere in your path::
% leap-client
-In order to run the client in debug mode::
-
- % leap-client --debug --logfile /tmp/leap.log
-
-To see all the available command line options::
-
- % leap-client --help
+Hacking
+=======
-Development
-==============
-
-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.
-
-As a workaround, you can:
-
- * 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::
-
- python configure.py
- make && make install
+.. note::
+ link to Hackers Guide in documentation.
+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::
-Install testing dependencies
-----------------------------
+ $ virtualenv . # ensure your .gitignore knows about it
+ $ 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 also install all of them 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:: docs/user/intro/gpl.*
- % 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