.. contents:: **Contents**

rTorrent-PS-CH - Fork notes
===========================

.. figure:: docs/_static/img/rTorrent-PS-CH-happy-pastel-kitty-s.png
   :align: center
   :alt: Extended Canvas Screenshot
   
*rTorrent-PS-CH*

This fork is another set of UI patches on top of the original, it also includes a set of fixes and enhancements for `rtorrent <https://github.com/rakshasa/rtorrent>`_. It was originally created to use with `rtorrent-ps-ch_setup <https://github.com/chros73/rtorrent-ps-ch_setup/>`_  project but it doesn't depend on it in any way.

UI changes
----------

UI changes on the fully customizable `extended canvas <docs/Manual.rst#extended-canvas-explained>`_:

- column/color lengths are shortened by 1 in column definition
- extra `dynamic color schemes <https://rtorrent-ps.readthedocs.io/en/latest/customize.html#column-layout-definitions>`_: ``C70``, ``C71``, ``C72``, ``C73``
- sacrificial columns by default: Item state (☢), Number of connected peers (℞)
- modified columns: Message (❢), Uprate (∆⋮ ⟲), Uploaded data size (Σ⇈)
- added column: Throttle name (⊘)
- the order and colorization of some columns are changed


Extra keyboard shortcuts
------------------------

It adds couple of new `keyboard shortcuts <docs/Manual.rst#extra-keyboard-shortcuts>`_: ``F``, ``↑``, ``↓``, ``ESC``


Important enhancements, fixes
-----------------------------

Over latest ``rtorrent v0.9.8/0.13.8``:

-  `inotify fix <https://github.com/chros73/rtorrent-ps/issues/87>`_
-  `throttle status bar mod <https://github.com/chros73/rtorrent-ps/issues/74>`_
-  `partially done downloads fix <https://github.com/chros73/rtorrent-ps/issues/69#issuecomment-284245459>`_
-  `choke groups fix <https://github.com/chros73/rtorrent-ps/issues/69>`_
-  `partial system.file.allocate.set=1 fix <https://github.com/chros73/rtorrent-ps/issues/68>`_

Merged into ``rtorrent v0.9.8/0.13.8``:

-  `list method type fix <https://github.com/chros73/rtorrent-ps-ch/issues/154>`_
-  `min_peers* settings fix <https://github.com/chros73/rtorrent-ps/issues/126>`_
-  `input history <https://github.com/chros73/rtorrent-ps/issues/83>`_
-  `basic arithmetic operators <https://github.com/chros73/rtorrent-ps/issues/71>`_
-  `temp filter <https://github.com/chros73/rtorrent-ps/issues/63>`_

Merged into ``rtorrent v0.9.7/0.13.7``:

-  `IPv4 filter enhancement <https://github.com/chros73/rtorrent-ps/issues/112>`_
-  `system.file.allocate.set=0 fix <https://github.com/chros73/rtorrent-ps/issues/38>`_
-  `scheduled sorting/filtering fix <https://github.com/chros73/rtorrent-ps/issues/19>`_

Differences between ``rTorrent-PS``:

-  `CPU optimized build <https://github.com/chros73/rtorrent-ps/issues/109>`_
-  `relative rpath linking <https://github.com/chros73/rtorrent-ps/issues/93>`_
-  `git version support <https://github.com/chros73/rtorrent-ps/issues/78>`_
-  `vanilla build of rtorrent is completely separated <https://github.com/chros73/rtorrent-ps/issues/99>`_
-  no docker support (due to CPU optimized build)


Extra commands
--------------

It also adds the following extra `attributes, commands <docs/Manual.rst#extra-commands>`_:

- ``d.custom=last_active``, ``d.custom=tm_completed`` `custom fields <https://github.com/chros73/rtorrent-ps/issues/120>`_
- ``d.is_enough_diskspace``, ``d.allocatable_size_bytes``, ``f.is_fallocatable``, ``f.is_fallocatable_file``, ``f.set_fallocate``, ``f.unset_fallocate`` (`system.file.allocate fix  <https://github.com/chros73/rtorrent-ps/issues/68>`_)
- ``convert.group``, ``d.is_done``, ``d.selected_size_bytes`` (`partially done downloads and choke groups fix  <https://github.com/chros73/rtorrent-ps/issues/69>`_)
- ``view.filter.temp``, ``match``, ``view.filter.temp.log``, ``view.filter.temp.excluded`` (`temp filter  <https://github.com/chros73/rtorrent-ps/issues/63>`_)
-  `math.* <https://github.com/chros73/rtorrent-ps/issues/71>`_ command group
-  ``ui.throttle.global.step.small.set``, ``ui.throttle.global.step.medium.set``, ``ui.throttle.global.step.large.set``  (`global throttle steps <https://github.com/chros73/rtorrent-ps/issues/84>`_)
-  ``ui.input.history.size``, ``ui.input.history.size.set``, ``ui.input.history.clear`` (`input history <https://github.com/chros73/rtorrent-ps/issues/83>`_)
-  `directory.watch.removed <https://github.com/chros73/rtorrent-ps/issues/87>`_
-  `d.parent_dir <docs/Manual.rst#d-parent-dir>`_ command and `d.tracker_scrape.* <https://github.com/chros73/rtorrent-ps/issues/119>`_ command group
-  `ui.status.throttle.{up|down} <docs/Manual.rst#ui-status-throttle-up-down-set-throttlename-throttlename>`_
-  `d.eta.* <https://github.com/chros73/rtorrent-ps-ch/issues/145>`_ command group
-  `try <https://github.com/chros73/rtorrent-ps-ch/issues/146>`_
-  `event.system.{startup_done|shutdown} <https://github.com/chros73/rtorrent-ps-ch/issues/152>`_
-  `array.size <https://github.com/chros73/rtorrent-ps-ch/issues/154>`_
-  `method.insert.{bool|string|list} <https://github.com/chros73/rtorrent-ps-ch/issues/154>`_


Notes
-----

Notes about ``git`` build script parameter:

- if commits point to the release version of ``rtorrent``/``libtorrent`` in build script then there shouldn't be a difference between release and git builds
- client versions (``rtorrent``/``libtorrent``) are still untouched, that means client still report the latest release version (e.g. ``0.9.8``) to trackers, only title bar and directory names are changed to display the increased version number (e.g. ``0.9.9``).


Compiling instructions
-----------------------

For static building, run the code below at this project's root directory to apply the static building patch and build with options:

.. code-block:: shell

   quilt push rtorrent-static-build
   optimize_build=no cfg_opts_lt='--disable-debug --enable-static=yes --enable-shared=no' cfg_opts_rt='--enable-static=yes --enable-shared=no --disable-debug --enable-ipv6 LDFLAGS=--static' ./build.sh ch ; strip -s rtorrent-0.9.8/src/rtorrent

An error occurs when chrpath after static building. But it doesn't matter if you just want the static linked binary.

The static linked executable binary's path is ``rtorrent-0.9.8/src/rtorrent``

For dynamic build:

See `Debian Install From Source - The Easy Way <docs/DebianInstallFromSourceTheEasyWay.rst>`_ to get ``rTorrent-PS-CH`` and ``pyrocore`` utilities up and running in ``tmux`` in 20 minutes.
Also @QDesjardin has created source packages for Arch Linux that can be `compiled and installed on Arch <docs/ArchInstallFromSource.rst>`_ easily.


Binary tarballs, packages
-------------------------

Note: published binaries are **NOT** CPU optimized builds (for obvious reasons) hence `Installing from Source <docs/DebianInstallFromSourceTheEasyWay.rst>`_ is still the preferred way. If you still want to use them then see `Debian Install From Tarballs, Packages <docs/DebianInstallFromTarballsPackages.rst>`_. 


Manual
------

See the `Manual <docs/Manual.rst>`_ for explanation of basic concepts and command extensions.


Change log
----------

See `CHANGELOG.md <CHANGELOG.md>`_ for more details.


rTorrent-PS
===========

Extended `rTorrent`_ *distribution* with UI enhancements, colorization,
some added features, and a comprehensive standard configuration.

.. figure:: https://raw.githubusercontent.com/pyroscope/rtorrent-ps/master/docs/_static/img/rT-PS-1.0-301-g573a782-2018-06-10-small.png
   :align: center
   :alt: Extended Canvas Screenshot


What is this?
-------------

``rTorrent-PS`` is a `rTorrent`_ *distribution* (*not* a fork of it),
in form of a set of patches that **improve the user experience and stability**
of official ``rTorrent`` releases.
See the `changelog`_ for a timeline of applied changes,
especially those since the last `official release`_.

Note that ``rTorrent-PS`` is *not* the same as the ``PyroScope`` `command line
utilities <https://github.com/pyroscope/pyrocore#pyrocore>`_, and
doesn't depend on them; the same is true the other way 'round. It's just
that both unsurprisingly have synergies if used together, and some
features *do* only work when both are present.


How do I use it?
----------------

See the
`main documentation <http://rtorrent-ps.readthedocs.io/en/latest/overview.html>`_
for details about installing and using ``rTorrent-PS``.

To get in contact and share your experiences with other users of
``rTorrent-PS``, join the
`pyroscope-users <http://groups.google.com/group/pyroscope-users>`_
mailing list or the inofficial ``##rtorrent`` channel on
``irc.freenode.net``.


References
----------

-  The `main rTorrent-PS documentation <http://rtorrent-ps.readthedocs.io/>`_
-  The `rTorrent <https://github.com/rakshasa/rtorrent>`_
   and `libtorrent <https://github.com/rakshasa/libtorrent>`_ projects
-  `rTorrent Documentation Wiki`_
-  `rTorrent Community Wiki`_
   and the `rTorrent Handbook <http://rtorrent-docs.rtfd.io/>`_


.. _`official release`: https://github.com/pyroscope/rtorrent-ps/releases
.. _`changelog`: https://github.com/pyroscope/rtorrent-ps/blob/master/CHANGES.md
.. _`rTorrent`: https://github.com/rakshasa/rtorrent
.. _`Bintray`: https://bintray.com/pyroscope/rtorrent-ps/rtorrent-ps
.. _`rTorrent Documentation Wiki`: https://github.com/rakshasa/rtorrent/wiki
.. _`rTorrent Community Wiki`: https://github.com/rtorrent-community/rtorrent-community.github.io/wiki
.. _`DebianInstallFromSource`: https://github.com/pyroscope/rtorrent-ps/blob/master/docs/DebianInstallFromSource.md
.. _`RtorrentExtended`: https://github.com/pyroscope/rtorrent-ps/blob/master/docs/RtorrentExtended.md
.. _`RtorrentExtendedCanvas`: https://github.com/pyroscope/rtorrent-ps/blob/master/docs/RtorrentExtendedCanvas.md
