From 60fe12414a8c1f137d2750a384e853f6882aa2d4 Mon Sep 17 00:00:00 2001 From: Kali Kaneko Date: Mon, 2 Oct 2017 23:41:01 +0200 Subject: [docs] move js docs to its own section --- docs/hacking/uidev.rst | 106 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-) (limited to 'docs/hacking') diff --git a/docs/hacking/uidev.rst b/docs/hacking/uidev.rst index 4ada825e..968fa010 100644 --- a/docs/hacking/uidev.rst +++ b/docs/hacking/uidev.rst @@ -3,4 +3,108 @@ Bitmask's Javascript User Interface ==================================== -(stuff goes here). +Some notes specific to development of the javascript ui interface. For more detail, see ``ui/README.md``. + +Run headless backend in development mode +---------------------------------------- + +Prerequisites:: + +.. note: move this snippet to a common include! + + sudo apt install build-essential python-dev python-virtualenv \ + libsqlcipher-dev libssl-dev libffi-dev + +Install and activate a virtualenv:: + + cd bitmask-dev + virtualenv venv + source venv/bin/activate + +(Refer to the `virtualenv documentation` if you're not using bash/zsh/dash). + +All the subsequent commands assume that you have activated the virtualenv. + +Install all the python dependencies:: + + make dev-backend + +Run application:: + + bitmaskd + +.. _`virtualenv documentation`: https://virtualenv.pypa.io/en/stable/userguide/#activate-script + +Run user interface frontend +--------------------------- + +If you want to run the Bitmask user interface, you additionally need the +following: + +Prerequisites:: + + sudo apt install python-pyqt5 python-pyqt5.qtwebkit + +Install python dependencies:: + + make dev-all + +Note: even though the UI is in javascript, Qt is used to create a webview +window. + +Run user interface:: + + bitmask + +The command `bitmask` should be in your path if you have activated the virtual +environment. + +Install Bitmask user interface in development mode +-------------------------------------------------- + +The above instructions will install a python package that contains a pre- +bundled version of the javascript UI. + +If you want to modify the javascript UI, then you need to be able to update the +javascript bundle whenever a javascript or CSS source file changes. To support +this, we build a python package of the javascript UI and install it in +"development mode" so that changes to the contents of the package are reflected +in bitmaskd immediately. + +Prerequisites:: + + sudo apt install nodejs npm nodejs-legacy + +Next, run ``dev-install``:: + + cd ui + make dev-install + +Now you should be able to run the user interface with debugging tools:: + + bitmaskd + cd ui + npm run ui + +This command is the same as running:: + + chromium-browser "http://localhost:7070/#$(cat ~/.config/leap/authtoken)" + +Firefox does not work as well, because the UI is only tested with webkit-based +browsers. + +Chromium is not the most ideal, however, because it uses a newer webkit than is +available in Qt. Instead, try qupzilla:: + + sudo apt install qupzilla + bitmaskd + qupzilla -ow "http://localhost:7070/#$(cat ~/.config/leap/authtoken)" + +If you make a change to any of the CSS or JS source files, you need to rebuild +the javascript bundle. You can do this continually as files change like so:: + + cd ui + node run watch + +The new javascript bundle will be used when you refresh the page so long as +``make dev-install`` was previously run. -- cgit v1.2.3