ssokolow/quicktile

View on GitHub
docs/installation.rst

Summary

Maintainability
Test Coverage
Installation
============

.. contents::
   :local:

There are three official installation methods for QuickTile, each with its own
advantages and disadvantages.

Support for other methods will be provided on a best-effort basis.

.. _Dependencies:

Dependencies
------------

Because QuickTile relies on library bindings which are not installable through
:abbr:`PyPI (the Python Package Index)`, :file:`setup.py` cannot be used to
automatically retrieve dependencies.

You must install the following separately (see below for APT and DNF commands):

A desktop based on the X11 windowing system
    QuickTile relies on NETWM hints and X11-style window decorations to do
    its work and Wayland's security model explicitly prevents tools like
    QuickTile from being written.

    If you are running MacOS, see the :ref:`quicktile-macos` FAQ entry.

    If you are running Windows and don't want to download WinSplit Revolution
    from an archive of discontinued software, there are some links which
    include Windows offerings in the :ref:`quicktile-windows` FAQ entry.
Python_ 3.8+
    QuickTile is developed in Python 3.8 with Kubuntu Linux 20.04 LTS as its
    earliest explicitly tested compatibility target.
GTK_ 3.x
    QuickTile is built around a GLib event loop and also relies on GDK for
    certain window operations.
libwnck_
    QuickTile relies on libwnck for most of its window manipulation to avoid
    playing whac-a-mole with the quirks of various window managers.
PyGObject_
    QuickTile accesses GNOME-family libraries via their GObject Introspection
    APIs. If your distro packages the following GIR definition files separately
    from the corresponding libraries, you must also ensure that they are
    installed:

    * ``GLib-2.0`` (``gir1.2-glib-2.0`` on Debian-family distros)
    * ``Gdk-3.0`` and ``GdkX11-3.0``
      (``gir1.2-gtk-3.0`` on Debian-family distros)
    * ``Wnck-3.0`` (``gir1.2-wnck-3.0`` on Debian-family distros)
setuptools_
    Though a fairly standard dependency for modern :file:`setup.py` scripts,
    setuptools is not a part of the Python standard library proper and is often
    not part of the set of packages installed by default on Debian-family
    distros.
python-xlib_
    GDK 3.x and libwnck do not provide wrappers for required functionality,
    such as desktop-agnostic global keybinding and usable getting/setting of
    X11 window properties.
dbus-python_
    Optional, but required if you want to interact with QuickTile over D-Bus.

.. _dbus-python: https://pypi.org/project/dbus-python/
.. _GTK: https://www.gtk.org/download/index.php
.. _libwnck: https://gitlab.gnome.org/GNOME/libwnck
.. _PyGObject: https://pygobject.readthedocs.io/en/latest/
.. _Python: https://www.python.org/
.. _python-xlib: https://pypi.org/project/python-xlib/
.. _setuptools: https://pypi.org/project/setuptools/

Debian and derivatives (Ubuntu, Mint, etc.)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following command should be sufficient to install all required
dependencies:

.. code:: sh

    sudo apt-get install python3 python3-pip python3-setuptools python3-gi python3-xlib python3-dbus gir1.2-glib-2.0 gir1.2-gtk-3.0 gir1.2-wnck-3.0

If you have `AptURL <https://help.ubuntu.com/community/AptURL>`_ set up,
you can also `click here <apt:python3,python3-pip,python3-setuptools,python3-gi,python3-xlib,python3-dbus,gir1.2-glib-2.0,gir1.2-gtk-3.0,gir1.2-wnck-3.0>`_
to trigger an installation prompt.

Fedora and derivatives
^^^^^^^^^^^^^^^^^^^^^^

The following command should be sufficient to install all required
dependencies:

.. code:: sh

    sudo dnf install python3 python3-pip python3-setuptools python3-gobject python3-xlib python3-dbus gtk3 libwnck3

Installation Options
--------------------

A. :command:`pip3` from a URL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Advantages:**

* Simple
* Logs installed files for removal

**Disadvantages:**

* System-wide install (requires :command:`sudo`)
* Setting QuickTile to run on login must be done manually
* Does not allow you to modify QuickTile code before installation
* Requires :command:`pip3` to be installed

**Instructions:**

After installing your dependencies, run the following command to install
QuickTile:

.. code:: sh

    sudo -H pip3 install https://github.com/ssokolow/quicktile/archive/master.zip

.. note:: If you attempt to use the ``--upgrade`` option and it fails to
    properly ignore system-provided dependencies, follow the instructions
    in the `Removal`_ section and then try again.

B. :file:`install.sh` from a local folder
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Advantages:**

* No additional dependencies
* Adds QuickTile as a default autostart task for all desktop sessions
* Automatically attempts to remove old QuickTile installs before upgrading
* Allows local modifications before installation
* Still reasonably simple

**Disadvantages:**

* System-wide install (requires :command:`sudo`)
* Does not log installed files like :command:`pip3`
* Does not allow per-user modifications to the code after installation
* Must manually download and unpack QuickTile before running the installation
  command.

**Instructions:**

After installing your dependencies and downloading a copy of QuickTile
(`zip <http://github.com/ssokolow/quicktile/zipball/master>`_,
`tar <http://github.com/ssokolow/quicktile/tarball/master>`_, or
`git clone <https://github.com/ssokolow/quicktile.git>`_), run the
following commands to install it:

.. code:: sh

    cd /path/to/unpacked/quicktile
    ./install.sh

You will be prompted for your :command:`sudo` password.

.. note::
   While an ordinary ``sudo python3 setup.py install`` will also work,
   ``install.sh`` has three advantages:

   1. It runs the ``setup.py build`` step without root privileges to avoid
      leaving root-owned cruft around.
   2. It will attempt to remove old QuickTile files which might cause a newer
      install to break.
   3. It saves you the trouble of setting QuickTile to run on startup.
      (``setup.py`` can't do this because it has no mechanism for adding files
      to ``/etc``.)

.. todo:: Check whether ``./install.sh`` Just Works™ under
    `checkinstall <https://asic-linux.com.mx/~izto/checkinstall/>`_
    and, if so, suggest it as an option for making QuickTile easily
    uninstallable on platforms that no proper package is provided for.

.. _install_quicktile.sh:

C. Run QuickTile without installing it
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Advantages:**

* No additional dependencies
* :command:`sudo` not required
* Allows full customization of QuickTile
* Allows parallel installation of multiple QuickTile versions for development
  or testing purposes.
* Easy removal or upgrade (just delete/replace the folder)

**Disadvantages:**

* Multiple copies of QuickTile may be present on a multi-user system
* QuickTile must be set to run on startup manually
* Must manually make provisions for being able to call :file:`quicktile.sh`
  without placing it in your :envvar:`PATH`.

**Instructions:**

 1. `Download <http://github.com/ssokolow/quicktile/zipball/master>`_ or
    `clone <https://github.com/ssokolow/quicktile.git>`_ QuickTile.
 2. Copy the :file:`quicktile` folder and the :file:`quicktile.sh` script into
     a folder of your choice.
 3. Make sure :file:`quicktile.sh` is marked executable.

.. note:: If you'd rather roll your own, the :file:`quicktile.sh` shell script
    is just three simple lines:

    1. The shebang
    2. A line to ``cd`` to wherever the :file:`quicktile` folder is
    3. A line to run :code:`python3 -m quicktile "$@"`

Setting Up Global Hotkeys
-------------------------

1. Run :command:`quicktile` (or :command:`./quicktile.sh` if appropriate) in a
   terminal to create :file:`~/.config/quicktile.cfg`.

   .. note:: If the ``quicktile`` command dies with a
      ``No module named __main__`` error, you probably have an old copy of
      QuickTile that didn't get properly installed/removed.

      Try following the `Removal`_ instruction and repeating the installation
      process.

      If this doesn't fix the problem, you should still be able to run
      QuickTile as :code:`python3 -m quicktile` instead.

2. Edit :file:`~/.config/quicktile.cfg` to customize your keybindings. (See
   :doc:`config` for further details.)

   .. note:: Customizing the tiling presets beyond altering the number of
      of columns which window widths will cycle through currently requires
      editing the source code.

      (Though it *is* quite simple. Just edit the
      :func:`quicktile.layout.make_winsplit_positions` function.)

      This will be remedied when I have time to design a new config file
      format that supports hierarchical data and write and test the requisite
      code to migrate existing configuration files to the new format.

3. If you didn't use :file:`install.sh`, set your desktop to run
   ``quicktile --daemonize`` or ``/full/path/to/quicktile.sh --daemonize``
   on login.

4. Run ``quicktile --daemonize`` (or ``./quicktile.sh --daemonize`` if
   appropriate) in a terminal to see if it reports any keybinding failures
   and test whether the keybindings work as intended.

5. If QuickTile appears to be working correctly, use :kbd:`Ctrl` + :kbd:`C` to
   quit it, close the terminal, and re-launch it via your :guilabel:`Run...`
   dialog so you won't have a terminal hanging around unnecessarily.

6. Enjoy. :)

.. _Removal:

Removal
-------

As QuickTile does not yet have a one-command uninstall script, you will need to
do the following.

**A. If you installed via pip3...**


.. code:: sh

    sudo pip3 uninstall quicktile
    sudo rm /usr/local/bin/quicktile

.. todo:: Check whether :command:`pip3` is still failing to remove the
    ``console_scripts`` entry-points that it generates.


**B. If you installed via install.sh...**

 ``install.sh`` doesn't yet log what it installed the way ``pip3`` does, so
 this will be a bit more involved.

 1. Remove the system integration files:

    .. code:: sh

        # Remove the command that can be typed at the command-line
        sudo rm /usr/local/bin/quicktile

        # Remove the autostart file
        sudo rm /etc/xdg/autostart/quicktile.desktop

        # Remove the launcher menu entry
        sudo rm /usr/local/share/applications/quicktile.desktop

 2. Remove QuickTile from your Python packages folder.

    While QuickTile itself should be installed as a single folder with a name
    like :file:`QuickTile-0.4-py3.8.egg`, the paths have varied from distro to
    distro and Python version to Python version.

    To ensure a clean removal, I recommend running the following command,
    verifying that nothing looks obviously wrong about its output, and then
    deleting what it found:

    .. code:: sh

       find /usr/local/lib -iname 'quicktile*'

**C. If you run quicktile.sh without installing**

1. Delete your :file:`quicktile` folder and :file:`quicktile.sh` script.
2. Undo whatever changes you made to call :file:`quicktile.sh`. (eg.
   :envvar:`PATH` modifications, shell aliases, desktop session autorun
   entries, etc.)