From ed2e14dd6ced4f64b6ac707c5998b38a78e6d7ad Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Mon, 17 Oct 2022 14:49:21 +0200 Subject: [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. --- README.md | 159 ++++++++++++++------------------------------------------------ 1 file changed, 36 insertions(+), 123 deletions(-) (limited to 'README.md') 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--.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 -- cgit v1.2.3