[builder][server][proxy] orchestrate Guix-powered development with a Makefile

* We're no longer treating builds from git and builds from release tarball differently. We now generate a source tarball under `./dist/` in both cases.
* We're now using `guix time-machine` to ensure we're always running a Guix revision that works.

1 files changed, 36 insertions, 123 deletions

diff --git a/README.md b/README.md
index fc1bda1..ae46b6a 100644
--- a/README.md
+++ b/README.md
@@ -7,143 +7,56 @@ Haketilo started as a browser extension (a WebExtension) with a dedicated user
 scripts repository server, Hydrilla. It has since been rewritten as an HTTP
 proxy. This repository contains the Python code of Hydrilla and Haketilo.
 
-## Getting started
+## Installation and running
 
-At the moment the recommended method of using Haketilo and Hydrilla is through
-the [GNU Guix](https://guix.gnu.org/) package manager. Installation from Python
-wheel is also possible but not described here.
+Head on to the relevant [wiki
+article](https://hydrillabugs.koszko.org/projects/haketilo/wiki/User_manual) for
+usage instructions for casual users.
 
-Build instructions have been most recently tested with Guix version
-1.3.0-26.fd00ac7.
+## Hacking
 
-### Building locally (from release tarball)
+At the moment the recommended method of hacking Haketilo and Hydrilla's codebase
+is through the [GNU Guix](https://guix.gnu.org/) package manager.
 
-Assuming GNU Guix is already installed and working, we can execute the following
-command in the project root to spawn a shell with Hydrilla & Haketilo available
-inside.
+A Guix version of at least 1.1.0 is expected. Most development tasks have been
+automated through Makefile. Rules use the `guix time-machine` command under the
+hood to pull and run a fixed Guix version that is known to work with the
+code. The most important make rules are described below.
 
-```
-guix environment -L . --ad-hoc -e '(@ (hydrilla) hydrilla)'
-```
+### `make wheel`
+Builds the project and put a source tarbal and a Python wheel under `dist/`.
 
-We can then make a test by running one of the programs, e.g.
-```
-haketilo --version
-```
+### `make dist`
+Generates a source tarbal under `dist/`.
 
-To instead install Haketilo & Hydrilla into the current Guix profile, treat your
-terminal with the following incantation
+### `make release`
+Produces a standalone, relocatable, binary release tarball that should work on
+most GNU/Linux systems. The tarball is written as
+`./haketilo-and-hydrilla-bin-<VERSION>-<ARCHITECTURE>.tar.gz`.
 
-```
-guix package -L . -e '(@ (hydrilla) hydrilla)'
-```
+### `make shell`
+Spawns a development shell with project's all dependencies and dev dependencies
+available.
 
-### Building locally (from git checkout)
+### `make shell-with-haketilo`
+Spawns a shell with Haketilo and Hydrilla built and available by means of a Guix
+profile.
 
-Due to some nuances of the setuptools-scm tool we're using, it is necessary to
-generate a project source tarball under `dist/` before building the Guix
-package.
+### `make catalogs`
+Rebuilds GNU gettext message catalogs used for localization.
 
-```
-guix environment -L . -e '(@ (hydrilla) hydrilla)' -- python3 -m build -s
-```
+### `make refresh-catalogs`
+Extracts messages form source files, refreshes the GNU gettext message catalog
+source files and rebuilds the catalogs.
 
-After that, we can start a shell with Hydrilla & Haketilo installed
+### `make test`
+Runs the automated test suite.
 
-```
-guix environment -L . --ad-hoc -e '(@ (hydrilla) hydrilla-dist-tarball)'
-```
+### `make run-haketilo`
+Runs `haketilo` program from sources.
 
-or just install to Guix profile
-
-```
-guix package -L . -e '(@ (hydrilla) hydrilla-dist-tarball)'
-```
-
-or build a binary package suitable for distribution to other GNU/Linux users
-
-```
-guix pack -L . -RR \
-    -S /hydrilla=bin/hydrilla \
-    -S /hydrilla-builder=bin/hydrilla-builder \
-    -S /hydrilla-server=bin/hydrilla-server \
-    -S /haketilo=bin/haketilo \
-    -e '(@ (hydrilla) hydrilla-dist-tarball)'
-```
-
-### Running from source
-
-During development, it is convenient to run the tools being worked on without
-putting them in a package. To spawn a shell with all development dependencies
-installed, run
-
-```
-guix environment -L . -e '(@ (hydrilla) hydrilla)'
-```
-
-For software to run, we first need to compile message catalogs and make sure the
-relevant metadata has been extracted from git by setuptools-scm. Inside the
-shell we just spawned, we run
-
-```
-# The following command, besides building a source tarball, generates the
-# src/hydrilla/_version.py file we need.
-python3 -m build -s
-# Generate .mo file(s) for gettext.
-./setup.py compile_catalog
-```
-
-Tools can be manually tested by telling Python interpreter tu execute the
-relevant module, e.g
-
-```
-PYTHONPATH=./src/ python3 -m hydrilla.mitmproxy_launcher --version
-```
-
-#### Running tests
-
-Hydrilla uses pytest. Tests can be run with
-
-```
-pytest
-```
-
-Please refer to the
-[pytest documentation](https://docs.pytest.org/en/stable/how-to/usage.html) for
-more details.
-
-#### Working on message catalogs
-
-There are 3 commands we'll want to use.
-
-```
-# Generate a message catalog template (src/hydrilla/locales/messages.pot)
-./setup.py extract_messages
-# Merge the generated template into existing .po catalog file(s)
-./setup.py update_catalog
-# Generate .mo file(s) that will be loaded by gettext
-./setup.py compile_catalog
-```
-
-Please refer to the
-[Babel documentation](https://babel.pocoo.org/en/latest/messages.html#message-extraction)
-for more details.
-
-#### Exiting Guix environment
-
-Once we're done hacking on the project, we can type
-
-```
-exit
-```
-
-in the shell... or just hit `Ctrl+d`.
-
-### User documentation
-
-Please look at
-[our wiki](https://hydrillabugs.koszko.org/projects/haketilo/wiki) for
-instructions on how to operate Haketilo and Hydrilla.
+### `make clean`
+Removes generated files.
 
 ## Contributing, asking for help, giving feedback, reporting bugs