A Minimalistic Wrapper for Whenever: Whenever_Tray

• A Minimalistic Wrapper for Whenever: Whenever_Tray
  • Configuration
  • Usage
  • Requirements
  • Building
  • Credits
    • Libraries
    • Graphics
  • License

whenever_tray aims at being the most essential, lightweight, and cross-platform wrapper for the whenever automation tool. Its purpose is to launch whenever and control it through its I/O based interface, so that

• the scheduler is started when whenever_tray runs
• it stops when the whenever_tray exits
• whenever activity can be paused or resumed leaving the scheduler running

via menu entries exposed by the wrapper. The menu can be accessed by clicking on an icon in the tray notification area, a common paradigm for applications that run in the background but still require some sporadic user interaction in modern graphical environments. whenever_tray also allows to show the log of whenever (provided that at least a text editor is available) via a menu entry, and to start the scheduler at lower/lowest priority by specifying it in the configuration file.

The functionality of whenever_tray is intentionally reduced to the lowest possible limit, in order to keep the code essential (thus reducing the need of specific code for specific platforms) and to use the least possibile computational resources. While CPU consumption should not be a problem, as both whenever_tray and whenever itself spend most of their time waiting, having a small application that uses a low amount of RAM could be desirable, in order to have the possibility that the whenever "suite" would run on a desktop system without a noticeable impact on it -- except when it checks conditions or executes tasks that, by user design, are resource hungry.

Once configured, whenever_tray takes care of

• starting the whenever scheduler at the desired priority (the lowest possible is a good option)
• forcing whenever to log to the specified location and with the specified level
• capturing the I/O of the scheduler in order to send commands to pause, resume, reset¹ conditions, or exit upon request
• hiding the console window on systems that would show it, such as Windows.

It also can open a text editor, or another app capable of viewing log files if specified in the configuration, to display the log for the current session: the choice of using a third party application to view the log file, thus avoiding to integrate such functionality in the resident application, contributes in keeping its memory footprint low.

Configuration

The TOML configuration file of whenever_tray has the following form:

# The whenever_tray section is mandatory, and the sample values provided below
# correspond to the default values.
[whenever_tray]

# if the full path is not provided, the executable must be in the PATH
whenever_command = "whenever"

# log level can be one of: trace, debug, info, warn, error (as string)
whenever_loglevel = "info"

# APP_DATA is the application data directory (environment variables not used)
whenever_logfile = 'APP_DATA/whenever.log'
whenever_config = 'APP_DATA/whenever.toml'

# priority can be one of: normal, low, minimum (as string)
whenever_priority = "minimum"

# path to the text processor used to view the log file
logview_command = 'gnome-text-editor'

and should be found in the so-called application data directory. The position of this directory varies on different operating systems:

• %AppData%\Whenever\ on Windows
• ~/.whenever/ on UNIX/Linux
• ~/Library/Application Support/.Whenever/ on Mac

and the directory, as well as a well-formed configuration file, have to be present before whenever_tray is launched -- otherwise the application will complain that the configuration file cannot be read, before running using the default values. All entries are optional, but an empty file should at least contain an empty [whenever_tray] section for the application not to show an error pop-up at startup. A sample whenever_tray.toml with the sample contents is provided in the repository. In the whenever_command and logview_command entries, the full path to the executable can be omitted if the executable itself is in a location within the search PATH. Note that the name of the application directory has been chosen to specify the close link to the whenever utility, thus removing the tray suffix that remains in the name of the executable, as this wrapper should be considered a part of the whenever project.

At the moment whenever_tray does not perform any substitution in the paths provided in the configuration file: a ~ is thus not expanded to the user home directory, and environment variable mentions are not replaced by their values. Since all paths will be relative to the path from which the application is launched, it is recommended to explicitly specify full paths for both whenever_logfile and whenever_config.

NOTE: the default values shown above yield for UNIX/Linux systems, while on Windows the default value for whenever_command is whenever.exe and the default value for logview_command is actually notepad.exe. The new gnome-text-editor is the default viewer when not compiling on Windows, however it might not be present, for instance on MacOSX or on versions of GNOME prior to the current one: in such cases it should either be explicitly specified or replaced, in the configuration file, with an available application.²

Usage

As long as no installation utility is provided, all the setup to allow whenever_tray to be launched at session startup has to be done by hand. The steps actually differ on different platforms, but share some concepts that, nowadays, are considered quite common in graphical desktop environments -- such as the definition of startup applications. On both Linux and Windows the streamlined process for requiring an application to automatically run at the beginning of a session consists of the following steps:

1. create a shortcut to the application (which includes assigning an icon): the shortcut is a file ending in .desktop on GNOME and in .lnk on Windows.
2. add this shortcut to the list of applications that start at the beginning of the session (startup applications on GNOME and startup apps on Windows)
3. log out and log in again.

If everything is set up correctly,³ the tray notification area shows, from now on, a small metronome icon from which it is possible to access the above described functionalities to interact with a running instance of whenever.

Requirements

In order to correctly build whenever_tray, the following requirements need to be fulfilled:

• WxWidgets and its development libraries and headers must be available: the 3.2 version has been used to develop this software, previous versions are not supported. On Windows the library has been built from scratch in order to obtain statically linkable libraries and not to depend on DLLs; on Linux it is possible to use the packages kindly provided by the folks at CodeLite;
• the preliminary steps to build the application are performed by CMake with the hope to mitigate the hassle of being multiplatform: the CMake build has been tested on Linux and Windows. In other words, the appropriate CMake package is necessary for building the application on all supported systems;
• the STL-based toml11 TOML library has been used to interpret the configuration file: in order to compile whenever_tray the latest released version (at the time of writing: version 3.7.1) should be downloaded from the Releases page and uncompressed in a directory called toml11 under src. The active master works as well, but it is preferable to rely on released versions.

NOTE: on many recent Linux distributions (namely, the ones that include GNOME 3.26 or higher), the tray notification area is no more supported natively on GNOME, at least in the form used by the WxWidgets library: a GNOME shell extension (for example: Appindicator or Tray Icons: Reloaded) might have to be installed. Moreover, there are still many problems with WxWidgets on Wayland, especially when using Xwayland (by defining/exporting GDK_BACKEND=x11 before the command that launches whenever_tray) which is needed for the tray icon to be shown, because WxWidgets uses a legacy protocol to display an icon on the notification area that is only supported on X11. The best solution so far to have whenever_tray working on a recent Linux desktop, is to start the session in Xorg mode. To achieve this, still on the login screen, the user should click the small icon on the lower right corner that appears upon selection of an account, and click the GNOME on Xorg entry. The choice will be remembered for the following sessions. However this might also result in a different user experience, either snappier or slower depending on how the desktop system is used.⁴

At the moment the specific requirements for MacOSX are not known: however they should be similar to the ones summarized above. Where possible, the use of a binary release might be a more viable alternative, even though there are no specific installers or packages for now.

Building

If all the above requirements have been satisfied, then building the application should be as easy as launching the following commands in the main build tree (where CMakeLists.txt is located):

cmake -S. -B_local
cmake --build _local

and the resulting executable will be found in _local/subprojects/Build/whenever_tray_core/, in the Debug or Release subdirectory. On Windows the command

cmake --build _local --config Release

should be used to build a release version.

Credits

Libraries

The TOML library used in whenever_tray is toml11, and the cross platform graphical framework is WxWidgets 3.2, which at the time of writing is the default supported version on Debian 12 -- used as the main linux testbed for the application. The wx_cmake_template has been used for scaffolding the application so that it could remain cross platform in terms of both operating and development environment: there is no need, however, to download this template, since all the files generated using the template itself are directly included in the source repository.

Graphics

The metronome icon used both in the About Box and in the tray notification area has been expressly designed for this application, and is available in the source tree as a SVG file.

License

This tool is licensed under the LGPL v2.1 (may change to LGPL v3 in the future): see the provided LICENSE file for details.

Footnotes

1. in order to remain minimalistic, this wrapper does not (and will not) support resetting specific conditions, nor it supports or will ever support suspending and resuming conditions while the scheduler is running. ↩

2. the best option is actually to use a viewer made explicitly for log files: for instance glogg is free, fast, lightweight, and cross-platform; it also sports features such as searching/highlighting that come handy when dealing with verbose log files like the ones that whenever generates when the log level is set to trace. ↩

3. that is: all required libraries are present (especially on Linux), whenever itself is installed and usable, the configuration and the application data directory exist, and are correctly positioned; obviously the further requirement is that the configuration file for whenever is valid: as a tip, it would be appropriate to test the configuration file by running whenever from the console. ↩

4. there is plenty of discussions about weaknesses and strengths of the two systems, compared to each other: in some aspects it looks like Wayland is still not on par withh a quite mature project as Xorg actually is; on the other hand Wayland is very actively developed, therefore many issues and bugs are fixed very quickly. Being adopted by many major players in the Linux ecosystem, Wayland is becoming the de facto standard for Linux desktop. This feeds the hope that many of the quirks affecting it at the moment will soon be addressed. ↩