diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 139 |
1 files changed, 52 insertions, 87 deletions
@@ -1,113 +1,78 @@ -# Hydrilla (Python implementation) +# Hydrilla&Haketilo -This is the repository of Python incarnation of [Hydrilla](https://hydrillabugs.koszko.org/projects/hydrilla/wiki), a repository software to serve [Haketilo](https://hydrillabugs.koszko.org/projects/haketilo/wiki) packages. +Haketilo is a tool to modify pages being opened in a web browser. It can block +pages' scripts and optionally inject user-specified ones. -The information below is meant to help hack on the codebase. If you're instead looking for some noob-friendly documentation, see the [user manual](https://hydrillabugs.koszko.org/projects/hydrilla/wiki/User_manual). +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. -## Dependencies +## Installation and running -### Runtime +Head on to the relevant [wiki +article](https://hydrillabugs.koszko.org/projects/haketilo/wiki/User_manual) for +usage instructions for casual users. -* Python3 (>= 3.7) -* [hydrilla.builder](https://git.koszko.org/hydrilla-builder/) -* flask -* click -* jsonschema (>= 3.0) +## Hacking -### Build +At the moment the recommended method of hacking Haketilo and Hydrilla's codebase +is through the [GNU Guix](https://guix.gnu.org/) package manager. -* setuptools -* wheel -* setuptools_scm -* babel +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. -### Test +### `make wheel` +Builds the project and put a source tarbal and a Python wheel under `dist/`. -* pytest -* reuse +### `make dist` +Generates a source tarbal under `dist/`. -## Building +### `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`. -We're using setuptools. You can build a wheel under `dist/` with -``` shell -python3 -m build -``` -Optionally, add a `--no-isolation` option to the second command to have it use system packages where possible instead of downloading all dependencies from PyPI. +### `make shell` +Spawns a development shell with project's all dependencies and dev dependencies +available. -The generated .whl file can then be used to install Hydrilla either globally or in the current Python virtualenv: -```shell -python3 -m pip install dist/put_the_name_of_generated_file_here.whl -``` +### `make shell-with-haketilo` +Spawns a shell with Haketilo and Hydrilla built and available by means of a Guix +profile. -### PyPI considerations +### `make catalogs` +Rebuilds GNU gettext message catalogs used for localization. -Commands like `python3 -m build` and `python3 -m pip` but also `virtualenv` will by default download the dependencies from PyPI repository[^pypi]. Although this is what many people want, it carries along a freedom issue. PyPI is not committed to only hosting libre software packages[^pypi_freeware] and, like any platform allowing upload of code by the public, has lower package standards than repositories of many operating system distributions. For this reason you are encouraged to use the dependencies as provided by your distribution. +### `make refresh-catalogs` +Extracts messages form source files, refreshes the GNU gettext message catalog +source files and rebuilds the catalogs. -To perform the build and installation without PyPI, first install all dependencies system-wide. For example, in Debian-based distributions (including Trisquel): -``` shell -sudo apt install python3-flask python3-flask python3-jsonschema \ - python3-setuptools python3-setuptools-scm python3-babel python3-wheel -``` +### `make test` +Runs the automated test suite. -Then, block programs you're about to spawn from accessing https://pypi.org. If running on a GNU/Linux system you can utilize Linux user namespaces: -``` shell -unshare -Urn -``` +### `make run-haketilo` +Runs `haketilo` program from sources. -The above will put you in a network-isolated shell. If you're using a virtualenv, activate it **after** the `unshare` command. +### `mypy-lint` +Runs mypy static type checker over source files of the project. -Now, in unpacked source directories of **both** `hydrilla-builder` and `hydrilla`, run the build and installation commands: -``` shell -python3 -m build --no-isolation -python3 -m pip install dist/hydrilla*.whl # or use the full file name -``` +### `mypy-lint-server`, `mypy-lint-builder`, `mypy-lint-haketilo` +Runs mypy static type checker over source files used in the relevant part of the +project. -[^pypi]: [https://pypi.org/](https://pypi.org/) -[^pypi_freeware]: [https://pypi.org/search/?c=License+%3A%3A+Freeware](https://pypi.org/search/?c=License+%3A%3A+Freeware) +### `make clean` +Removes generated files. -## Testing +## Contributing, asking for help, giving feedback, reporting bugs -For tests to pass you need compiled message catalogs to be present. If you've performed the build at least once, they're already there. Otherwise, you need to run `./setup.py compile_catalog`. Then you can run the actual tests: -``` shell -python3 -m pytest -``` - -## Running - -### Hydrilla command - -Hydrilla includes a `hydrilla` shell command that can be used to quickly and easily spawn a local instance, e.g.: -``` -hydrilla -m /path/to/where/package/files/to/serve/are/stored -p 10112 -``` -This will cause the resources from provided path to be served at [http://127.0.0.1:10112/](http://127.0.0.1:10112/). - -The actual packages to serve are made using [Hydrilla builder](https://git.koszko.org/hydrilla-builder/). - -For more information about available options, pass the `--help` flag to `hydrilla` command: -``` shell -hydrilla --help -``` - -If you navigate your POSIX shell to Hydrilla sources directory, you can also consult the included manpage (`man` tool required): -``` shell -man ./doc/man/man1/hydrilla.1 -``` - -Last but not least, you might find it useful to consult the default, internal configuration file of Hydrilla that resides under `src/hydrilla/server/config.json` in the sources repository. - -### WSGI - -If you want to test a more production-suitable deployment option, consult sample Apache2 config files and a WSGI script supplied in `doc/examples` directory. +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 this code in a proprietary program, I am not going to enforce this in court.* - -## Contributing - -Please visit our Redmine instance at https://hydrillabugs.koszko.org. - -You can also write an email to koszko@koszko.org. +*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.* |