The syntax of XMLRPC commands changed with rTorrent version 0.8.9,
and continues to change. Make sure that the versions of rTorrent
and PyroScope you plan to install or update to are actually compatible.
There are compensation mechanisms in both projects, but there are limits to those
— scan the respective changelogs for breaking changes.

pyrocore 0.5+ will no longer support the old syntax, and thus not work
with rTorrent 0.8.x versions.
rTorrent 0.9.6 has the old commands disabled by default, and only a
special command line switch will enable them again, for now.
Also, this documentation uses the new syntax (mostly).

Since repairing broken files resulting from faulty updates usually is
either a lot of work or simply impossible, always make a backup.
Backups should be made when either PyroScope or rTorrent is changed to
a new release version or git revision.

Depending on how you installed rTorrent, make a copy of the rtorrent
executable and libtorrent*.so*.
Note that the rTorrent-PS build script installs into versioned directories,
i.e. using that you don’t have to worry if changing to a new rTorrent version
­— the old one is still available, and you can switch back easily.

Before adapting and extending your configuration to make use of new
features, you first have to update the software itself. How to do that
depends on the way you initially installed it, so follow one of the
following sections, depending on whether you did a
release installation
or one from source.

After you installed a new version of the software,
you have to check for necessary changes to the default configuration,
after calling the pyroadmin--create-config or the update-to-head.sh command.

Note that only the *.default files (config.ini.default, config.py.default,
and so on) will be overwritten, they are a literal copy of
the defaults packaged into the software, and are there for informational purposes only.
You can then use the diff tool to check for the differences between
your current configuration and the new default one, and add any changes
you want to adopt.

Also note that sections of the configuration you
leave out, and keys that you do not overwrite, are automatically taken
from the defaults, which greatly simplifies any update.
That is the reason why it is recommended to have a minimal configuration
with just your customizations, in addition to the defaults.

The file ~/.pyroscope/rtorrent-pyro.rc.default,
and those contained in ~/.pyroscope/rtorrent.d, are a different story.
They change quite often, and since there is no merging of *.rc.default with
*.rc files, the default ones are normally used.
You can still disable those default files one by one using the rtorrent.d/.rcignore file,
in order to provide your own versions or simply disable certain features.
That is way better than switching altogether to *.rc files,
again for the reason updates become way more painless.
See the comments at the start of files in rtorrent.d for details.

The 0.5.x release line adds a queue manager,
watching a directory tree for loading metafiles,
and removes support for ancient versions of Python and rTorrent.
More details on the contained changes can be found at GitHub releases and the changelog.
Install at least version 0.5.3, which has a few important fixes.

To upgrade your existing installation, follow these steps:

For people that run a source code installation, just use the update-to-head.sh
script as described in Installing from GitHub.
When your old installation is still in ~/lib, you’ll be presented with
the necessary commands to move to ~/.localafter calling
~/lib/pyroscope/update-to-head.sh.
Since all the documentation now points to ~/.local paths, you should switch over.

For PyPI installs, just do a fresh install to the new location
at ~/.local.

Call pyroadmin--create-config to update the .default configuration
examples, and create the new rtorrent.d directory.

You also MUST change the import command in your rtorrent.rc
that loads the PyroScope configuration include:

# Remove the ".default" if you want to change something (else your changes# get over-written on update, when you put them into ``*.default`` files).import=~/.pyroscope/rtorrent-pyro.rc.default

Read the rTorrent Queue Manager section if you plan to use item queueing
and/or the tree watch feature; both are inactive by default and need to be
enabled. You also need to add the new pyro_watchdog schedule into your
configuration, as shown in the Configuration Guide.

Remember to restart rTorrent after any configuration changes.

When you have a rather aged configuration, also consider switching to the up-to-date
set of configuration files as found in the pimp-by-box project, that use
the new command names through-out and are thus way more future-proof.

There is an easy to use make-rtorrent-config.sh script, see
`rTorrent Configuration`_ on how to use it.
At the same time, update the start script.
Note that these configuration files also work with a plain vanilla rTorrent version,
you do not need rTorrent-PS for them to work.

In any case, make a backup of your configuration and scripts,
as mentioned at the start of this chapter. After creating the new configuration,
merge in what’s missing from your old configuration, but migrate to the new syntax first.
For adding your custom settings, you can use your own files in the ~/rtorrent/rtorrent.d directory.

The 0.6.x release line adds support for the new canvas v2 feature of rTorrent-PS v1.1
in the configuration files.

Notable rtcontrol changes are a new timestamp field last_xfer,
useful in sorting views and selecting items for deletion that are not in high demand.
The --alter-view option allows manipulating filter results in views
incrementally (using several command calls).

When you have a rather aged configuration, also consider switching to the new
set of configuration files as found in the pimp-by-box project, that use
the new command names through-out and are thus way more future-proof.
They are also compatible with changes in rTorrent v0.9.7 and rTorrent-PS v1.1
– older files are not and most likely will greet you with errors after an upgrade.
More on that in the upgrade steps below, and right ahead in the next paragraph.

Note that v0.9.7 of rTorrent finally does away with many of those old comamnds.
Read the section on 0.5.x, right above this one,
regarding the make-rtorrent-config.sh script, which provides compatible config files
covering most of what people typically need.

To upgrade your existing installation, follow these steps:

For people that run a source code installation, just use the update-to-head.sh
script as described in Installing from GitHub.

Call pyroadmin--create-config to update the .default configuration.

You also MUST change the pyrocore config snippet in your rtorrent.rc,
and add the system.has fallback for vanilla rTorrent and pre-1.1 rTorrent-PS.

Re-read the Configuration Guide, which has more information generally, and extensions
to not only rtorrent.rc but also the minimal config.ini.

Specifically if you use rTorrent-PS 1.1 with the new canvas v2 feature,
you then MUST update the files in ~/rtorrent/rtorrent.d/,
because there’s lots of relevant changes.

The make-rtorrent-config.sh does that, but overwrites any changes you
might have made. The best way to handle that is to put your config into git
before calling the script a second time.
That way, diffs get easy and nothing can be lost
– you ‘just’ need to do the merging.

Read rTorrent Configuration about how to avoid changing standard files
by using _rtlocal.rc instead,
and/or your own added files in rtorrent.d.
Then you have a way more painless updating experience – next time, anyway.

Remember to restart rTorrent after any configuration changes.

In any case, make a backup of your configuration and scripts,
as mentioned at the start of this chapter, before performing any update steps.
By the way, putting stuff into git, and also committing it, counts as a backup.