Installation¶
When supports several installation types. The easiest way to install it is using one of the packages provided for Ubuntu, that may also be suitable for other Debian based Linux distributions. However, if a different setup is needed (for instance in a per-user based installation), it is possible to install When directly from a source archive or from a clone of the Git repository.
This chapter covers the installation process and the additional actions that should be performed to get When up and running for an user. Information is also provided on how to remove the applet from the system or for an user.
Requirements¶
For the applet to function and before unpacking it to the destination
directory, make sure that Python 3.x, PyGObject for Python 3.x and the
xprintidle
utility are installed. Optionally, to enable file and directory
monitoring, the pyinotify
package can be installed. For example, not all
of these are installed by default on Ubuntu: in this case the following
commands can be used.
$ sudo apt-get install python3-gi
$ sudo apt-get install xprintidle
$ sudo apt-get install gir1.2-appindicator3-0.1
$ sudo apt-get install python3-pyinotify
The gir1.2-appindicator3-0.1
package may not be needed on all systems, but
some Linux distributions do not install it by default. python3-pyinotify
is normally considered optional but it is mandatory to enable conditions
based on changes to the file system. [1]
After the requirements have been fulfilled, the methods below can be used to set up the applet.
Package Based Install¶
As said above, a package provides the quickest and easiest way to have a working installation of When. Packages are provided for Ubuntu, although they might work (at least partially) with other Debian based Linux distributions. When packages come in two flavors:
when-command
: this is a LSB structured package, especially suitable for Ubuntu and derivatives, that installs the applet in a way similar to other standard Ubuntu packages. The actual file name has the formwhen-command_VERSIONSPEC-N_all.deb
whereVERSIONSPEC
is a version specification, andN
is a number. Pros of this package are mostly that it blends with the rest of the operating environment and that thewhen-command
command-line utility is available on the system path by default. Cons are that this setup may conflict with environments that are very different from Ubuntu.when-command-opt
: this version installs When in/opt/when-command
, and should be suitable for.deb
based distributions that differ from Ubuntu. The advantage of this method is that the applet is installed separately from the rest of the operating environment and does not clutter the host system. The main drawback is that thewhen-command
utility is not in the system path by default and, unless the PATH variable is modified, it has to be invoked using the full path, that is as/opt/when-command/when-command
. The package file name has the form:when-command-opt-VERSIONSPEC.deb
.
To install a downloaded package, run
sudo dpkg --install when-command_VERSIONSPEC-N_all.deb
or
sudo dpkg --install when-command-opt-VERSIONSPEC.deb
depending on the chosen version. After installation, each user who desires to
run When has to launch when-command --install
(or
/opt/when-command/when-command --install
if the second method was chosen)
in order to find the applet icon in Dash and to be able to set it up as a
startup application (via the Settings dialog box). [2]
[3]
Warning
The two package types are seen as different by apt and dpkg: this means
that one package type will not be installed over the other. When switching
package type, the old package must be uninstalled before. This also yields
when upgrading from packages up to release 0.9.1, however removal of user
data and desktop shortcuts is not required. After a package type switch or
an upgrade from release 0.9.1 or older, when-command --install
should
be invoked again, using the full path to the command if appropriate.
Install from a PPA¶
It is possible to install When on recent Ubuntu series from a PPA. This has the advantage of automatically resolving dependencies and to directly set up a fairly stable release with the recommended layout, and to let the user automatically update the software in the ordinary way.
To add the repository, you can simply issue
$ sudo add-apt-repository ppa:franzg/when-command
and accept to import the related key. Then refresh the packages and install the applet by running
$ sudo apt-get update
$ sudo apt-get install when-command
from the command line. The other common methods of setting up a PPA using the Software & Updates page in System Settings and the Ubuntu Software Center also work.
Running when-command --install
is still needed for each user to add
When to the desktop when installing for the first time.
Install from the Source¶
A source archive or a Git clone can be used to install the package in a
directory of choice, but some additional operations are required. However this
can be done almost mechanically. In the following example we will suppose that
the source has been downloaded in the form of a when-command-master.zip
archive located in ~/Downloads
, and that the user wants to install
When in ~/Applications/When
. The required steps are the below:
$ cd ~/Applications
$ unzip ~/Downloads/when-command-master.zip
$ mv when-command-master When
$ cd When
$ rm -Rf po scripts .temp .git* setup.* MANIFEST.in stdeb.*
$ for x in applications doc icons man ; do rm -Rf share/$x ; done
$ chmod a+x share/when-command/when-command.py
$ ln -s share/when-command/when-command.py when-command
$ $HOME/Applications/When/when-command --install
The rm
and for
statements are not mandatory: they are only used to
remove stuff that is not used by the installed applet and to avoid a cluttered
setup. Also, with this installation method, When can only be invoked from
the command line using the full path ($HOME/Applications/When/when-command
in the example): to use the when-command
shortcut,
$HOME/Applications/When
has to be included in the PATH variable in
.bashrc
. This means for instance that the creation of a symbolic link in
a directory already in the user path can cause malfunctions to When on
command line invocation. [4]
This installation method is useful in several cases: it can be used for
testing purposes (it can supersede an existing installation, using the
--install
switch with the appropriate script), to run the applet directly
from a cloned repository or to restrict installation to a single user.
The --install
Switch¶
When will try to recognize the way it has been set up the first time it’s
invoked: the --install
switch creates the desktop entries and icons for
each user that opts in to use the applet, as well as the required directories
that When needs to run correctly and an active autostart entry, that is:
~/.config/when-command
where it will store all configuration~/.local/share/when-command
where it stores resources and logs (in thelog
subdirectory).
Note that the full path to the command has to be used on the first run
if the /opt
based package or the manual installation were chosen: in this
way When can recognize the installation type and set up the icons and
shortcuts properly.
Removal¶
When can be uninstalled via apt-get remove when-command
or
apt-get remove when-command-opt
if a package distribution was used, or
by deleting the newly created applet directory (~/Applications/When
in
the above example) if the source was unpacked from an archive or cloned from
Git.
Also, desktop shortcut symbolic links can be removed as follows:
$ rm -f ~/.local/share/applications/when-command.desktop
$ rm -f ~/.config/autostart/when-command-startup.desktop
while the following commands can be used to remove applet data and an extra CLI link (if present):
$ rm -f ~/.local/bin/when-command
$ rm -Rf ~/.local/share/when-command
$ rm -Rf ~/.config/when-command
where the last line can be skipped if When is presumed to be reinstalled at a later time. [5]
Of course it has to be shut down before, for example by killing it via
when-command --kill
.
Note
Removal of user data is not required when switching package type or
changing installation style, provided that the newly installed
when-command
is invoked with the --install
switch before using the
applet. If user data is removed, all tasks and conditions and other
items will have to be recreated from scratch after reinstalling, unless an
export file exists.
[1] | Package based installations depend on this: the installation fails if it is not installed. |
[2] | The first method is the preferred one, and it is
the one usually referred to throughout the documentation: when-command
is considered to be in the path, and in the examples and instructions is
invoked directly, omitting the full path prefix. |
[3] | Although an autostart entry is created, it remains inactive by default if the configuration is not modified in the applet settings. |
[4] | A .tar.gz archive is provided along with
packaged releases, which is the result of a source-based installation:
it extracts all the required files in a directory named When , but the
extraction directory can be moved before the when-command --install
step. |
[5] | Not all rm operations shown here will actually have
effect: the instructions follow the most generic case, and some of the
files listed for deletion could be missing. |