From bf8c6b19b05e73a6e59b8884e1d26a730df6188b Mon Sep 17 00:00:00 2001 From: kali Date: Mon, 8 Oct 2012 08:33:06 +0900 Subject: another pass towards a clearer README --- README.rst | 154 ++++++++++++++++++++++++++------------------------- pkg/requirements.pip | 3 + 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 -- cgit v1.2.3