summaryrefslogtreecommitdiff
path: root/README.rst
blob: 6f2f98d66ec0809bb565b8a22425908b812ca537 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
Bitmask
=======================================

*Your internet encryption toolkit*

.. image:: https://badge.fury.io/py/leap.bitmask.svg
    :target: http://badge.fury.io/py/leap.bitmask
.. image:: https://img.shields.io/badge/IRC-leap-blue.svg
   :target: http://webchat.freenode.net/?channels=%23leap&uio=d4
   :alt: IRC
.. image:: https://img.shields.io/badge/IRC-bitmask_(es)-blue.svg
   :target: http://webchat.freenode.net/?channels=%23bitmask-es&uio=d4
   :alt: IRC-es


**Bitmask** is the client for the services offered by `the LEAP Platform`_. It
contains a command-line interface and a multiplatform desktop client. It can be
also used as a set of libraries to communicate with the different services from
third party applications.

It is written in python using `Twisted`_  and licensed under the `GPL3`_. The
Graphical User Interface is written in html+js and uses `PyQt5`_ for serving the
application.

.. _`the LEAP Platform`: https://github.com/leapcode/leap_platform
.. _`Twisted`: https://twistedmatrix.com
.. _`PyQt5`: https://pypi.python.org/pypi/PyQt5
.. _`GPL3`: http://www.gnu.org/licenses/gpl.txt

Package under development!
---------------------------------------

This is a unified repo that has merged the following packages, previously isolated, under the leap namespace:

bonafide, mail, keymanager, bitmask.

The previous Qt client has been deprecated (bitmask version 0.8.2, still
available at the http://github.com/leapcode/bitmask_client repo).

Note that this repo still doesn't have support for VPN: its porting will
follow soon.

Read the Docs!
---------------------------------------

The latest documentation about Bitmask is available at `LEAP`_.

.. _`LEAP`: https://leap.se/en/docs/client

Bugs
=======================================

Please report any bugs `in our bug tracker`_.

.. _`in our bug tracker`: https://leap.se/code/projects/report-issues


Development
=======================================

Running Tests
---------------------------------------

You need tox to run the tests. If you don't have it in your system yet::

  pip install tox

And then run all the tests::

  tox


Hacking
----------------------------------

In order to run bitmask in a development environment, you must activate a
virtualenv and install the various packages using 'pip install -e'. This
installs python packages as links to the source code, so that your code
changes are immediately reflected in the packages installed in the virtualenv.

All this is done for you with the Makefile. For example, if you want to
develop for the encrypted mail service::

  virtualenv venv
  source venv/bin/activate
  make dev-mail

If you want to develop for the gui client too, you have to have
installed the python2 bindings for Qt5 in your system (in debian: ``apt
install python-pyqt5  python-pyqt5.qtwebkit``). After ensuring this, you can
do::

  make dev-all

Note: even though the UI is in javascript. Qt is used to create a webview
window.

hacking on the javascript UI
+++++++++++++++++++++++++++++++++++++++

The above instructions will install a python package that contains a pre-
bundled version of the javascript UI.

If you want to hack on the javascript UI, then it needs to be able to update the
javascript bundle whenever a javascript or CSS source file changes.

First, install the javascript prerequisites:

  sudo apt install nodejs npm nodejs-legacy

Next, run ``dev-install``:

  source venv/bin/activate    # if not already activated
  cd www
  make dev-install            # install JS user interface as a python package in "develop" mode.
  node run watch              # continually rebuild javascript bundle when source files change.

For more information, see ``www/README.md``.

cross-testing
+++++++++++++++++++++++++++++++++++++++

If you are developing against a non-published branch of ``leap.common`` or
``leap.soledad``, run instead::

  tox -e py27-dev

This expects ``leap_common`` and ``soledad`` repos to be checked out in the
parent folder.


License
=======================================

.. image:: https://raw.github.com/leapcode/bitmask_client/develop/docs/user/gpl.png

Bitmask is released under the terms of the `GNU GPL version 3`_ or later.

.. _`GNU GPL version 3`: http://www.gnu.org/licenses/gpl.txt