README: Document how to use nix-shell for development

[coffee/main.git] / README.md

diff --git a/README.md b/README.md
index e682efa6686614f0248ed9691d69fc2cd3334770..d12ed97c4c74bb1b4f960a00a0fe2db0ee33c83a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -5,12 +5,17 @@ terminal. Fetch it with:
 
        git submodule update --init
 
-The `coffee-flask`  directory contains the server application, which
-runs on [rtime](https://rtime.felk.cvut.cz/coffee) server.
+The [`coffee-flask`](coffee-flask.git) directory contains the server
+application, which runs on [rtime](https://rtime.felk.cvut.cz/coffee)
+server.
 
-`terminal` directory is the code running on the terminal. It is a
-standard buildroot distribution. The most importat piece of code here
-is the `mtaio` application from `terminal/src/mt-apps`.
+`terminal` directory contains the code running on the terminal. It is
+based on a standard [buildroot](https://buildroot.org/) distribution.
+The most important piece of code here is the `mtaio` application from
+[`terminal/src/mt-apps`](./mt-apps.git), which contains the web server
+powering the GUI of the terminal – a web browser. Among other things,
+it informs the browser about physical events captured by the terminal
+from the card reader and coffee machine buttons.
 
 A more detailed documentation is available in [Jiří Matěják's Master
 thesis](https://dspace.cvut.cz/handle/10467/76276).
@@ -29,17 +34,38 @@ with this command:
 To improve the terminal, you can run all the relevant code on your
 Linux computer.
 
-First install all prerequisities:
+First install all prerequisites:
 
     apt install python3-flask libev-dev cmake
        pip3 install flask_cors
 
+Alternatively, you can install [Nix package manager][] and run
+`nix-shell` in the `main` directory. This ensures that correct version
+of all needed dependencies are available in the shell (until you
+exit).
+
 Then compile and run all the software components:
 
 1. Compile _mtaio_ simulator: `make -C terminal/src/mt-apps SIM=1`
 2. Run mtaio: `cd terminal/src/mt-apps && ./build/mtaio`
-3. Run the server application: `cd coffee-flask && FLASK_APP=app.py flask run`
+3. Run the server application: `cd coffee-flask && FLASK_APP=app.py FLASK_DEBUG=1 flask run`
 4. Point your web browser to http://localhost:8080/
 5. Pressing keys in _mtaio_ window simulates various activities.
    Numbers are cards of different users, letters A through F are
    different coffee machine buttons.
+
+The size of the terminal window is 960×560 px.
+
+### Submitting patches
+
+Send patches by email (preferably with [git send-email][]) to
+`coffee@rtime.felk.cvut.cz` [mailing list][]. You can subscribe the
+[mailing list][] to discuss the patches sent by others.
+
+It is recommended to run the [`setup_git`][sg] script in your local
+repository to configure git optimally for patch submission.
+
+[git send-email]: https://rtime.felk.cvut.cz/wiki/index.php/Configuring_git_send-email
+[mailing list]: https://rtime.felk.cvut.cz/mailman/listinfo/coffee
+[sg]: main.git/blob/HEAD:/setup_git
+[Nix package manager]: (https://nixos.org/guides/install-nix.html)