diff options
Diffstat (limited to 'docs/source/devguide')
| -rw-r--r-- | docs/source/devguide/how-to/curl-jsonrpc.md | 162 | ||||
| -rw-r--r-- | docs/source/devguide/how-to/index.md | 23 | ||||
| -rw-r--r-- | docs/source/devguide/how-to/update-1.3-plugin.md | 160 | ||||
| -rw-r--r-- | docs/source/devguide/index.md | 13 | ||||
| -rw-r--r-- | docs/source/devguide/packaging/index.md | 9 | ||||
| -rw-r--r-- | docs/source/devguide/packaging/launchpad-recipe.md | 43 | ||||
| -rw-r--r-- | docs/source/devguide/packaging/release.md | 54 | ||||
| -rw-r--r-- | docs/source/devguide/packaging/windows.md | 10 | ||||
| -rw-r--r-- | docs/source/devguide/tutorials/01-setup.md | 85 | ||||
| -rw-r--r-- | docs/source/devguide/tutorials/index.md | 10 |
10 files changed, 569 insertions, 0 deletions
diff --git a/docs/source/devguide/how-to/curl-jsonrpc.md b/docs/source/devguide/how-to/curl-jsonrpc.md new file mode 100644 index 0000000..9bb559d --- /dev/null +++ b/docs/source/devguide/how-to/curl-jsonrpc.md @@ -0,0 +1,162 @@ +# How to connect to JSON-RPC with curl + +Before continuing make sure `deluge-web` or Web UI plugin is running. + +## Create a curl configuration file + +To save a lot of typing and to keep the curl command short we shall create +a `curl.cfg` files and put the following contents in it: + + request = "POST" + compressed + cookie = "cookie_deluge.txt" + cookie-jar = "cookie_deluge.txt" + header = "Content-Type: application/json" + header = "Accept: application/json" + url = "http://localhost:8112/json" + write-out = "\n" + +To pretty-print the JSON result see: <https://stackoverflow.com/q/352098/175584> + +## Log in to Web UI + +Log in to the Web UI and get session cookie: + + curl -d '{"method": "auth.login", "params": ["deluge"], "id": 1}' -K curl.cfg + +Result is `true` to signify that login was successful: + + { + "error": null, + "id": 1, + "result": true + } + +Check the contents of the cookie file to verify session ID created. + + cat cookie_deluge.txt + # Netscape HTTP Cookie File + # http://curl.haxx.se/docs/http-cookies.html + # This file was generated by libcurl! Edit at your own risk. + + localhost FALSE /json FALSE 1540061203 _session_id <session_id> + +## Check connected to deluged + +Use the `web.connected` method to get a boolean response if the Web UI is +connected to a deluged host: + + curl -d '{"method": "web.connected", "params": [], "id": 1}' -K curl.cfg + +Result is `false` because Web UI is not yet connected to the daemon: + + { + "error": null, + "id": 1, + "result": false + } + +## Get list of deluged hosts + +Use the `web.get_hosts` method: + + curl -d '{"method": "web.get_hosts", "params": [], "id": 1}' -K curl.cfg + +The result contains the `<hostID>` for using in request `params` field. + + { + "error": null, + "id": 1, + "result": [ + [ + "<hostID>", + "127.0.0.1", + 58846, + "localclient" + ] + ] + } + +## Get the deluged host status + + curl -d '{"method": "web.get_host_status", \ + "params": ["<hostID>"], "id": 1}' -K curl.cfg + +The result shows the version and status; _online_, _offline_ or _connected_. + + { + "error": null, + "id": 1, + "result": [ + "<hostID>", + "Online", + "2.0.0" + ] + } + +## Connect to deluged host + +To connect to deluged with `<hostID>`: + + curl -d '{"method": "web.connect", \ + "params": ["<hostID>"], "id": 1}' -K curl.cfg + +The result contains the full list of available host methods: + + { + "error": null, + "id": 1, + "result": [ + "core.add_torrent_url", + ... + "core.upload_plugin" + ] + } + +## Disconnect from host + + curl -d '{"method": "web.disconnect", "params": [], "id": 1}' -K curl.cfg + +A successful result: + + { + "error": null, + "id": 1, + "result": "Connection was closed cleanly." + } + +## Add a torrent + + curl -d '{"method": "web.add_torrents", "params": \ + [[{"path":"/tmp/ubuntu-12.04.1-desktop-amd64.iso.torrent", \ + "options":null}]], "id": 1}' -K curl.cfg + +## Add a magnet URI + + curl-d '{"method": "core.add_torrent_magnet", \ + "params": ["<magnet_uri>", {}], "id": 1}' -K curl.cfg + +## Get list of files for a torrent + + curl -d '{"method": "web.get_torrent_files", \ + "params": ["<torrentid>"], "id": 1}' -K curl.cfg + +## Set a core config option + + curl -d '{"method": "core.set_config", \ + "params":[{"max_upload_slots_global":"200"}], "id": 1}' -K curl.cfg + + {"error": null, "result": null, "id": 1} + +## Useful curl configuration options + +For full list of options see man page `man curl` or help `curl --help`: + + --cookie (-b) # Load cookie file with session id + --cookie-jar (-c) # Save cookie file with session id + --compressed # responses are gzipped + --include (-i) # Include the HTTP header in output (optional) + --header (-H) # HTTP header + --request (-X) # custom request method + --data (-d) # data to send in POST request '{"method": "", "params": [], "id": ""}' + --insecure (-k) # use with self-signed certs https diff --git a/docs/source/devguide/how-to/index.md b/docs/source/devguide/how-to/index.md new file mode 100644 index 0000000..e63c771 --- /dev/null +++ b/docs/source/devguide/how-to/index.md @@ -0,0 +1,23 @@ +# How-to guides + +A collection of guides for specific issues or to cover more detail than the tutorials. + +## Web JSON-RPC + +```{toctree} +:titlesonly: + +Connect to JSON-RPC using curl <curl-jsonrpc> +``` + +## Plugins + +<!-- +- [Create a plugin](create-plugin.md) +--> + +```{toctree} +:titlesonly: + +Update 1.3 plugin for 2.0 <update-1.3-plugin> +``` diff --git a/docs/source/devguide/how-to/update-1.3-plugin.md b/docs/source/devguide/how-to/update-1.3-plugin.md new file mode 100644 index 0000000..9ce6ae1 --- /dev/null +++ b/docs/source/devguide/how-to/update-1.3-plugin.md @@ -0,0 +1,160 @@ +# How to update a Deluge 1.3 plugin for 2.0 + +With the new code in Deluge 2.0 there are changes that require authors of +existing plugins to update their plugins to work on Deluge 2.0. + +The main changes are with Python 3 support and the new GTK3 user interface with +the dropping of GTK2. However it is still possible for a 1.3 plugin to be made +compatible with 2.0 and this guide aims to helps with that process. + +## Python + +### Python version matching + +Ensure your code is Python >=3.6 compatible. + +In `1.3-stable` the plugins that were built with a specific version of Python +would only be loaded if the system Python also matched. + +This has change in Deluge 2.0 and it will load any Python version of plugin +eggs so compatibility is essential for end-users not to encounter issues. + +## GTK 3 addition + +In order to support both Deluge 1.3 and 2.0 all existing plugin GTK UI files +must be copied and then converted to contain only GTK3 code with the old files +still using PyGTK e.g.: + + cp gtkui.py gtk3ui.py + +### Convert from libglade to GtkBuilder + +With PyGTK there were two library options for creating the user interface from +XML files by default Deluge plugins used libglade but that has been deprecated +and removed in GTK3. So the libglade `.glade` files will need converted to +GtkBuilder `.ui` files and the Python code updated. + +See the official [Migrating to GtkBuilder][migrate-gtkbuilder] document for more details. + +#### GtkBuilder conversion script + +Install the `gtk-builder-convert` converter on Ubuntu with: + + sudo apt install libgtk2.0-dev + +To convert your GTK run it like so: + + gtk-builder-convert data/config.glade data/config.ui + +#### Glade UI designer for GTK2 + +The above conversion can also be done in Glade UI designer (version <=3.8). + +In the preferences select `GtkBuilder` as the project file format. Ensure +that the minimum Gtk version is set to 2.24 and fix any deprecated widgets. + +The updated file should be saved with file extension `.ui`. + +#### Python code changes + +The code needs to replace `gtk.glade` references with `gtk.Builder` and the +first step is updating how the files are loaded: + +```diff +- glade = gtk.glade.XML(get_resource("config.glade")) ++ builder = Gtk.Builder.new_from_file(get_resource("config.ui")) +``` + +Replace signals method: + +```diff +- glade.signal_autoconnect(self) ++ builder.connect_signals(self) +``` + +Replace `get_widget` with `get_object`: + +```diff +- glade.get_widget ++ builder.get_object +``` + +Check for any remaining `glade` methods and replace with the `builder` equivalents. + +### Migrate XML files to GTK3 + +If you open and save the file it will update with the new requirement header: + + <!-- Generated with glade 3.18.3 --> + <interface> + <requires lib="gtk+" version="3.10"/> + +You can fix deprecated widgets but keep the minimum GTK version to <= 3.10 for +desktop compatibility. + +An example of migrating a Deluge plugin to GtkBuilder: [AutoAdd GtkBuilder] + +### Gtk import rename + +Move from PyGTK to GTK3 using Python bindings. + +<https://pygobject.readthedocs.io/en/latest/guide/porting.html> + + wget https://gitlab.gnome.org/GNOME/pygobject/raw/master/tools/pygi-convert.sh + cp gtkui.py gtk3ui.py + sh pygi-convert.sh gtk3ui.py + +```diff +-import gtk ++from gi.repository import Gtk +``` + +```diff +- self.builder = gtk.Builder() ++ self.builder = Gtk.Builder() +``` + +### Deluge GTK3 + +#### Imports + +Imports will need renamed from `deluge.ui.gtkui` to `deluge.ui.gtk3`. + +There is also a new PluginBase for Gtk3 UI: + +```diff +-from deluge.plugins.pluginbase import GtkPluginBase ++from deluge.plugins.pluginbase import Gtk3PluginBase +-class GtkUI(GtkPluginBase): ++class Gtk3UI(Gtk3PluginBase): +``` + +#### Entry points + +To enable the GTK3 UI to find the plugin the entry points requires updating too. + +In the plugin `__init__.py` file add a new `Gtk3UIPlugin` class: + +``` +class Gtk3UIPlugin(PluginInitBase): + def __init__(self, plugin_name): + from .gtk3ui import Gtk3UI as _plugin_cls + self._plugin_cls = _plugin_cls + super(Gtk3UIPlugin, self).__init__(plugin_name) +``` + +A new entry for GTK3 UI can then be added to `setup.py`: + +```diff + [deluge.plugin.gtkui] + %s = %s:GtkUIPlugin ++ [deluge.plugin.gtk3ui] ++ %s = deluge_%s:Gtk3UIPlugin + [deluge.plugin.webui] + %s = %s:WebUIPlugin +- """ % ((__plugin_name__, __plugin_name__.lower())*3) ++ """ % ((__plugin_name__, __plugin_name__.lower())*4) +``` + +[migrate-gtkbuilder]: https://developer.gnome.org/gtk2/stable/gtk-migrating-GtkBuilder.html +[autoadd gtkbuilder]: https://git.deluge-torrent.org/deluge/commit/?h=develop&id=510a8b50b213cab804d693a5f122f9c0d9dd1fb3 diff --git a/docs/source/devguide/index.md b/docs/source/devguide/index.md new file mode 100644 index 0000000..436a72a --- /dev/null +++ b/docs/source/devguide/index.md @@ -0,0 +1,13 @@ +# Development guide + +This is a guide to help with developing Deluge. + +```{toctree} +:titlesonly: + +Tutorials <tutorials/index> +how-to/index +Packaging <packaging/index> +../changelog +../depends +``` diff --git a/docs/source/devguide/packaging/index.md b/docs/source/devguide/packaging/index.md new file mode 100644 index 0000000..aa7293a --- /dev/null +++ b/docs/source/devguide/packaging/index.md @@ -0,0 +1,9 @@ +# Packaging documentation + +```{toctree} +:titlesonly: + +release +launchpad-recipe +windows +``` diff --git a/docs/source/devguide/packaging/launchpad-recipe.md b/docs/source/devguide/packaging/launchpad-recipe.md new file mode 100644 index 0000000..7d48727 --- /dev/null +++ b/docs/source/devguide/packaging/launchpad-recipe.md @@ -0,0 +1,43 @@ +# Launchpad recipe + +The launchpad build recipes are for build from source automatically to provide +Ubuntu packages. They are used to create daily builds of a Deluge git branch. + +Note these don't have the same control as a creating a publishing to PPA. + +Main reference: <https://help.launchpad.net/Packaging/SourceBuilds/Recipes> + +## Deluge Launchpad build recipes + +Recipe configuration: <https://code.launchpad.net/~deluge-team/+recipes> + +An example for building the develop branch: + + # git-build-recipe format 0.4 deb-version 2.0.0.dev{revno}+{git-commit}+{time} + lp:deluge develop + nest-part packaging lp:~calumlind/+git/lp_deluge_deb debian debian develop + +There are two parts, first to get the source code branch and then the `debian` +files for building the package. + +## Testing and building locally + +Create a `deluge.recipe` file with the contents from launchpad and create the +build files with `git-build-recipe`: + + git-build-recipe --allow-fallback-to-native deluge.recipe lp_build + +Setup [pbuilder] and build the deluge package: + + sudo pbuilder build lp_build/deluge*.dsc + +Alternatively to build using local files with [pdebuild]: + + cd lp_build/deluge/deluge + pdebuild + +This will allow modifying the `debian` files to test changes to `rules` or +`control`. + +[pbuilder]: https://wiki.ubuntu.com/PbuilderHowto +[pdebuild]: https://wiki.ubuntu.com/PbuilderHowto#pdebuild diff --git a/docs/source/devguide/packaging/release.md b/docs/source/devguide/packaging/release.md new file mode 100644 index 0000000..e02a09a --- /dev/null +++ b/docs/source/devguide/packaging/release.md @@ -0,0 +1,54 @@ +# Release Checklist + +## Pre-release + +- Update [translation] `po` files from [Launchpad] account. +- Changelog is updated with relevant commits and release date is added. +- Docs [release notes] are updated. +- Tag release in git and push upstream e.g. + + git tag -a deluge-2.0.0 -m "Deluge 2.0.0 Release" + +## Release + +- Create source and wheel distributions: + + python setup.py sdist bdist_wheel + +- Upload to PyPi (only accepts `tar.gz`): + + twine upload dist/deluge-2.0.0.tar.gz dist/deluge-2.0.0-py3-none-any.whl + +- Calculate `sha256sum` for each file e.g. + + cd dist; sha256sum deluge-2.0.0.tar.xz > deluge-2.0.0.tar.xz.sha256 + +- Upload source tarballs and packages to `ftp-osl.osuosl.org`. + + - Ensure file permissions are global readable: `0644` + - Sub-directories correspond to _major.minor_ version e.g. all `2.0.x` patch + releases are stored in `source/2.0`. + - Change release version in `version*` files, create a new version file for + any major releases. + - SSH into OSUOSL FTP site and run `trigger-deluge` to sync files. + +- Create packages (Ubuntu, Windows, OSX). + - Ubuntu: <https://code.launchpad.net/~deluge-team/+recipe/stable-releases> + - Ensure launchpad git repo has sync'd to get latest version + - Update version in recipe (reset any dash number to 0) + - Check for new distribution series needing selected. + - Request build for selected series. + +## Post-release + +- Update with version, hashes and release notes: + - Publish new docs version on [ReadTheDocs]. + - [Wikipedia] +- Close Trac milestone and add new milestone version for future tickets. +- Ensure all stable branch commits are also applied to development branch. + +[readthedocs]: https://deluge.readthedocs.io +[wikipedia]: http://en.wikipedia.org/wiki/Deluge_%28software%29 +[launchpad]: https://translations.launchpad.net/deluge +[translation]: ../../contributing/translations.md +[release notes]: ../../releases/index.md diff --git a/docs/source/devguide/packaging/windows.md b/docs/source/devguide/packaging/windows.md new file mode 100644 index 0000000..253eac0 --- /dev/null +++ b/docs/source/devguide/packaging/windows.md @@ -0,0 +1,10 @@ +# Packaging for Windows + +Currently there is no working package for Deluge 2.0. The previous Python freezing +application `bbfreeze` is not compatible with Python 3 and the project is no longer +maintained. + +There are two alternatives `cxfreeze` and `pyinstaller` but neither is trivial with +the GTKUI application. + +See [#3201](https://dev.deluge-torrent.org/ticket/3201) diff --git a/docs/source/devguide/tutorials/01-setup.md b/docs/source/devguide/tutorials/01-setup.md new file mode 100644 index 0000000..02195b1 --- /dev/null +++ b/docs/source/devguide/tutorials/01-setup.md @@ -0,0 +1,85 @@ +# Setup tutorial for Deluge development + +The aim of this tutorial is to download the source code and setup an +environment to enable development work on Deluge. + +## Pre-requisites + +To build and run the Deluge applications they depends on tools and libraries as +listed in DEPENDS.md. + +Almost all of the Python packages dependencies will be installed using pip but +there are some packages or libraries that are required to be installed to the +system. + +### Ubuntu + +#### Build tools + + sudo apt install git intltool closure-compiler python3-pip + pip3 install --user tox + +You might need to add `~/.local/bin` to your PATH. + +#### Runtime libraries and tools + + sudo apt install python3-libtorrent python3-geoip python3-dbus python3-gi \ + python3-gi-cairo gir1.2-gtk-3.0 gir1.2-appindicator3 python3-pygame libnotify4 \ + librsvg2-common xdg-utils + +## Setup development environment + +### Clone Deluge git repository + +Download the latest git code to local folder. + + git clone git://deluge-torrent.org/deluge.git + cd deluge + +### Create Python virtual environment + +Creation of a [Python virtual environment] keeps the development isolated +and easier to maintain and Tox has an option to make this process easier: + + tox -e denv + +Activate virtual environment: + + source .venv/bin/activate + +Deluge will be installed by Tox in _develop_ mode which creates links back +to source code so that changes will be reflected immediately without repeated +installation. Check it is installed with: + + (.venv) $ deluge --version + deluge-gtk 2.0.0b2.dev149 + libtorrent: 1.1.9.0 + Python: 2.7.12 + OS: Linux Ubuntu 16.04 xenial + +### Setup pre-commit hook + +Using [pre-commit] ensures submitted code is checked for quality when +creating git commits. + + (.venv) $ pre-commit install + +You are now ready to start playing with the source code. + +### Reference + +- [Contributing] +- [Key requirements concepts] + +<!-- +## How-to guides + +- How to install plugins in develop mode? +- How to setup and test translations? +- How to run tests? +- How to create a plugin? +--> + +[pre-commit]: https://pre-commit.com +[contributing]: https://dev.deluge-torrent.org/wiki/Contributing +[requirements topic]: ../topics/requirements.md diff --git a/docs/source/devguide/tutorials/index.md b/docs/source/devguide/tutorials/index.md new file mode 100644 index 0000000..2a47252 --- /dev/null +++ b/docs/source/devguide/tutorials/index.md @@ -0,0 +1,10 @@ +# Developer tutorials + +A list of articles to help developers get started with Deluge. + +```{toctree} +:numbered: 1 +:titlesonly: + +Development setup <01-setup> +``` |