[builder][server][proxy] replace guix.scm with a loadable scheme module; document Haketilo+Guix usage in the README

1 files changed, 133 insertions, 51 deletions

diff --git a/README.md b/README.md
index ad3434b..fc1bda1 100644
--- a/README.md
+++ b/README.md
@@ -3,74 +3,156 @@
 Haketilo is a tool to modify pages being opened in a web browser. It can block
 pages' scripts and optionally inject user-specified ones.
 
-Haketilo started as a browser extension (a WebExtension) with a dedicated
-user scripts repository server, Hydrilla. Haketilo is now being rewritten as an
-HTTP proxy. This repository contains combined sources of Hydrilla and Haketilo
-which are going to be distributed together.
+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.
 
-This source tree is a work in progress. The server part has simlar functionality
-as in earlier Hydrilla releases and should be mostly usable at this point. The
-proxy part is still being developed, but you can play with it nevertheless if
-you're brave 😉
+## Getting started
 
-You're going to need at least Python 3.7 plus the following Python libraries
-* mitmproxy 8 (sadly, not in Debian yet)
-* immutables (also not in Debian but if you are familiar with git-buildpackage,
-  you can utilize [my own packaging of it](https://git.koszko.org/immutables/))
-* flask
-* jsonschema (>= 3.0)
-* beautifulsoup4
-* html5lib
-* setuptools
-* setuptools_scm
-* wheel
-* babel (Python library)
-* build (a PEP517 package builder)
+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.
 
-This project also utilizes reuse, pytest and mypy but those are either
-development-only dependencies or just not required for the actual Haketilo
-proxy.
+Build instructions have been most recently tested with Guix version
+1.3.0-26.fd00ac7.
+
+### Building locally (from release tarball)
+
+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.
 
-Make sure to run
 ```
-./setup.py build
+guix environment -L . --ad-hoc -e '(@ (hydrilla) hydrilla)'
 ```
-before running anything. Otherwise, missing files can make things break.
 
-Create directory ~/.haketilo/store/temporary_malcontent/ and put there all the
-[built Haketilo packages](https://hydrillabugs.koszko.org/projects/hydrilla/wiki/Hydrilla_on-disk_data_format) that you'd like to use. You can use
-[hydrilla builder](https://hydrillabugs.koszko.org/projects/hydrilla/wiki/Releases)
-and the [repository of fixes for JS-encumbered websites](https://git.koszko.org/hydrilla-fixes-bundle/).
+We can then make a test by running one of the programs, e.g.
+```
+haketilo --version
+```
+
+To instead install Haketilo & Hydrilla into the current Guix profile, treat your
+terminal with the following incantation
 
-Now, run
 ```
-PYTHONPATH=./src/ python3 -m mitmproxy_launcher
+guix package -L . -e '(@ (hydrilla) hydrilla)'
 ```
 
-Next, open your browser, go to settings and import the certificate that got
-generated under ~/.haketilo/mitmproxy/mitmproxy-ca-cert.pem.
+### Building locally (from git checkout)
 
-Under (at least) Mozilla browsers, certificate pinning may cause mitmproxy's
-generated certificates to still be rejected. This generally happens on Google
-and Mozilla websites. To be able to access these through proxy, go to
-about:config and set the security.cert_pinning.enforcement_level preference to
-0.
+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.
 
-You can now browse to some site for which you configured a Haketilo user script
-to run. I usually visit https://opencores.org/projects for which the first
-Haketilo script was written...
+```
+guix environment -L . -e '(@ (hydrilla) hydrilla)' -- python3 -m build -s
+```
 
-There's some work to do before any of this will be usable to normal human
-beings. Help appreciated.
+After that, we can start a shell with Hydrilla & Haketilo installed
 
-## Copying
+```
+guix environment -L . --ad-hoc -e '(@ (hydrilla) hydrilla-dist-tarball)'
+```
 
-Hydrilla is Copyright (C) 2021-2022 Wojtek Kosior and contributors, entirely available under the GNU Affero General Public License version 3 or later. Some files might also give you broader permissions, see comments inside them.
+or just install to Guix profile
 
-*I, Wojtek Kosior, thereby promise not to sue for violation of this project's license. Although I request that you do not make use of this code in a proprietary program, I am not going to enforce this in court.*
+```
+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
 
-## Contributing
+```
+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.
 
-Please visit our Redmine instance at https://hydrillabugs.koszko.org.
+#### Exiting Guix environment
 
-You can also write an email to koszko@koszko.org.
+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.
+
+## Contributing, asking for help, giving feedback, reporting bugs
+
+Development occurs on
+[our issue tracker](https://hydrillabugs.koszko.org/projects/haketilo). You can
+also write directly to [Wojtek](mailto:koszko@koszko.org) if you prefer.
+
+## Copying
+
+Hydrilla is Copyright (C) 2021-2022 Wojtek Kosior and contributors, entirely available under the GNU Affero General Public License version 3 or later. Some files might also give you broader permissions, see comments inside them.
+
+*I, Wojtek Kosior, thereby promise not to sue for violation of this project's license. Although I request that you do not make use of this code in a proprietary program, I am not going to enforce this in court.*