[bug] missing bytes conversion
[bitmask-dev.git] / README.rst
1 Bitmask
2 ===========================================================
3
4 *Your internet encryption toolkit*
5
6 .. image:: https://badge.fury.io/py/leap.bitmask.svg
7     :target: http://badge.fury.io/py/leap.bitmask
8 .. image:: https://0xacab.org/leap/bitmask-dev/badges/master/build.svg
9     :target: https://0xacab.org/leap/bitmask-dev/pipelines
10 .. image:: https://readthedocs.org/projects/bitmask/badge/?version=latest
11    :target: http://bitmask.readthedocs.io/en/latest/?badge=latest
12    :alt: Documentation Status
13 .. image:: https://img.shields.io/badge/IRC-leap-blue.svg
14    :target: http://webchat.freenode.net/?channels=%23leap&uio=d4
15    :alt: IRC
16 .. image:: https://img.shields.io/badge/IRC-bitmask_(es)-blue.svg
17    :target: http://webchat.freenode.net/?channels=%23bitmask-es&uio=d4
18    :alt: IRC-es
19
20
21 **Bitmask** is the client for the services offered by `the LEAP Platform`_. It
22 contains a command-line interface and a multiplatform desktop client. It can be
23 also used as a set of libraries to communicate with the different services from
24 third party applications.
25
26 It is written in python using `Twisted`_  and licensed under the `GPL3`_. The
27 Graphical User Interface is written in html+js and uses `PyQt5`_ for serving
28 the application.
29
30 .. _`the LEAP Platform`: https://github.com/leapcode/leap_platform
31 .. _`Twisted`: https://twistedmatrix.com
32 .. _`PyQt5`: https://pypi.python.org/pypi/PyQt5
33 .. _`GPL3`: http://www.gnu.org/licenses/gpl.txt
34
35 Package under development!
36 -----------------------------------------------------------
37
38 The previous client using PySide has been deprecated (Bitmask version 0.9.2,
39 still available at the http://github.com/leapcode/bitmask_client repo).
40
41
42 Read the Docs!
43 -----------------------------------------------------------
44
45 There is documentation about Bitmask `for users`_ and `for developers`_. For
46 developers, be sure to read the sections on `hacking`_ and `contributing_`.
47 Testers should read the section on `testing and QA`_.
48
49 .. _`for users`: https://leap.se/en/docs/client
50 .. _`for developers`: https://bitmask.readthedocs.io
51 .. _`hacking`: https://bitmask.readthedocs.io/en/latest/hacking/index.html
52 .. _`contributing`: https://bitmask.readthedocs.io/en/latest/hacking/contributing.html#contributing
53 .. _`testing and QA`: https://bitmask.readthedocs.io/en/latest/testing/index.html
54
55 Bugs
56 ===========================================================
57
58 Please report any bugs `in our bug tracker`_.
59
60 .. _`in our bug tracker`: https://0xacab.org/leap/bitmask-dev/issues/
61
62 Logs
63 ----
64
65 If you want to watch the logs, from the command line::
66
67   bitmaskctl logs watch
68
69 The paste command can be handy to do bug reports (needs ``pastebinit`` installed
70 in the system)::
71
72   bitmaskctl logs send
73
74 but do not upload anything that you do not want to make public ;)
75
76
77 Development
78 ===========================================================
79
80 Running Tests
81 -----------------------------------------------------------
82
83 You need tox to run the tests. If you don't have it in your system yet::
84
85   pip install tox
86
87 And then run all the python tests::
88
89   tox
90
91 There are some minimal end-to-end tests::
92
93   make test_e2e
94
95 For testing the UI (aka ``bitmask-js``) you need to have ``mocha``
96 installed. You can run ui tests like this::
97
98   cd ui && make test
99
100 More info abou testing can be found in the ``docs/hacking/testing`` document.
101
102
103 Hacking
104 -----------------------------------------------------------
105
106 In order to run bitmask in a development environment, you must activate a 
107 `virtualenv`_ and install the various leap-related python packages using ``pip
108 install -e``. This installs them as links to the source code, so
109 that your code changes are immediately reflected in the packages imported from
110 within the virtualenv.
111
112 The various ``make dev-*`` commands will run the appropriate ``pip install``
113 commands for you.
114
115 If you want to setup your whole development environment in a single step, and
116 you are running a debian-based system, you can use::
117
118   make dev-bootstrap
119
120 That should install all the system dependencies, create a virtualenv for you,
121 and drop you in a shell inside that virtualenv. In the future, you can enter this
122 `virtualenv`_ again by using `pew`_::
123
124   pew workon bitmask
125
126 To upgrade regularly the python dependencies installed inside your virtualenv,
127 you can run::
128
129   make upgrade-all
130
131 inside your virtualenv, and it will install any new version of your
132 dependencies that is found in `pypi`_.
133
134 Check out the ``docs/hacking`` page for more extense instructions `to get
135 you started`_.
136
137 .. _`to get you started`: https://bitmask.readthedocs.io/en/latest/hacking/
138 .. _`pew`: https://pypi.python.org/pypi/pew
139 .. _`virtualenv`: https://pypi.python.org/pypi/virtualenv
140 .. _`pypi`: https://pypi.python.org
141
142
143 License
144 ===========================================================
145
146 .. image:: https://raw.github.com/leapcode/bitmask_client/develop/docs/user/gpl.png
147
148 Bitmask is released under the terms of the `GNU GPL version 3`_ or later.
149
150 .. _`GNU GPL version 3`: http://www.gnu.org/licenses/gpl.txt