search

Martchus / syncthingtray

Tray application and Dolphin/Plasma integration for Syncthing
https://martchus.github.io/syncthingtray/
Other
1.78k stars 46 forks source link
dolphin hacktoberfest plasma plasmoid qt-widgets synchronization syncthing tray-application

readme

Syncthing Tray

Syncthing Tray provides a tray icon and further platform integrations for Syncthing. Checkout the website for an overview.

The following integrations are provided:

Checkout the official forum thread for discussions and announcement of new features.

This README document currently serves as the only and main documentation. So read on for details about the configuration. If you are not familiar with Syncthing itself already you should also have a look at the Syncthing documentation as this README is only going to cover the Syncthing Tray integration.

Issues can be created on GitHub but please read the "Known bugs and workarounds" section in this document before.

Supported platforms

Official binaries are provided for Windows and GNU/Linux for the x86_64 architecture and can be download from the website and the release section on GitHub. This is only a fraction of the available downloads, though. I also provide further repositories for some GNU/Linux distributions. There are also binaries/repositories provided by other distributors. For a list with links, checkout the "Download" section of this document.

Syncthing Tray is known to work under:

This does not mean Syncthing Tray is actively tested on all those platforms or desktop environments.

For Plasma 5 and 6, there is in addition to the Qt Widgets based version also a "native" Plasmoid. Note that the latest version of the Plasmoid generally also requires the latest version of Plasma 5 or 6 as no testing on earlier versions is done. Use the Qt Widgets based version on other Plasma versions. Checkout the "Configuring Plasmoid" section for further details.

On GTK-centered desktops have a look at the Arch Wiki for how to achieve a more native look and feel. Under GNOME one needs to install an extension for tray icon support (unless one's distribution already provides such an extension by default).

Limitations of your system tray might affect Syncthing Tray. For instance when using the mentioned GNOME extension the Syncthing Tray UI shown in the screenshots below is only shown by double-clicking the icon. If your system tray is unable to show the Syncthing Tray UI at all you can still use Syncthing Tray for the tray icon and basic functionality accessible via the menu.

Note that under Wayland-based desktops there will be positioning issues. The Plasmoid is not affected by this, though.

The section "Known bugs and workarounds" below contains further information and workarounds for certain caveats like the positioning issues under Wayland.

Features

Does this launch or bundle Syncthing itself? What about my existing Syncthing installation?

Syncthing Tray does not launch Syncthing itself by default. There should be no interference with your existing Syncthing installation. You might consider different configurations:

Note that the experimental UI tailored for mobile devices is more limited. So far it can only start a built-in version of Syncthing or connect to an externally started Syncthing instance. It will set a custom config/data directory for Syncthing so any Syncthing instance launched via the mobile UI will not interfere with existing setups.

Installation and deinstallation

Checkout the website for obtaining the executable or package. This README also lists more options and instructions for building from sources.

If you are using one of the package manager options you should follow the usual workflow of that package manager.

Otherwise, you just have to extract the archive and launch the contained executable. Especially on Windows, please read the notes on the website before filing any issues. Note that automatic updates haven't been implemented yet. To uninstall, just delete the executable again.

For further cleanup you may ensure that autostart is disabled (to avoid a dangling autostart entry). You may also delete the configuration files (see "Location of the configuration file" section below).

Screenshots

The screenshots are not up-to-date.

Qt Widgets based GUI under Windows 11

Qt Widgets based GUI under Windows 11

Qt Widgets based GUI under Openbox/Tint2 with dark Breeze theme

Qt Widgets based GUI under Openbox/Tint2

Plasmoid (for KDE's Plasma shell)

Light theme

Plasmoid (light theme)

Dark theme

Plasmoid (dark theme)

Icon customization dialog

Plasmoid (customized icons)

Settings dialog

Settings dialog

Web view

Web view Web view (dark)

Syncthing actions for Dolphin

Rescan/pause/status

General remarks on the configuration

You need to configure how Syncthing Tray should connect to Syncthing itself. The previous section "Does this launch or bundle Syncthing itself…" mentions available options. Additionally, a wizard is shown on the first launch which can guide though the configuration for common setups. If you have dismissed the wizard you can still open it at any point via a button on the top-right corner of the settings dialog.

It may be worthwhile to browse though the pages of the configuration dialog to tweak Syncthing Tray to your needs, e.g. to turn off notification you may find annoying.

Location of the configuration file

The configuration file is usually located under ~/.config/syncthingtray.ini on GNU/Linux and under %appdata%\syncthingtray.ini on Windows. For other platforms and further details, checkout the Qt documentation (Syncthing Tray uses the "IniFormat"). For portable installations it is also possible to place an empty file called syncthingtray.ini directly next to the executable.

You may remove the configuration file under the mentioned location to start from scratch.

Note that this only counts for Syncthing Tray. For Syncthing itself, checkout its own documentation.

The Plasmoid is using the same configuration file but in addition also Plasma's configuration management for settings specific to a concrete instance of the Plasmoid.

The experimental UI tailored for mobile devices is using a distinct configuration which is located under ~/.config/Martchus/Syncthing Tray on GNU/Linux and /storage/emulated/0/Android/data/io.github.martchus.syncthingtray on Android and %appdata%\Martchus\Syncthing Tray on Windows. The configuration and database of Syncthing itself are also located within this directory when Syncthing is launched via the mobile UI.

Configuring Plasmoid

The Plasmoid requires installing Syncthing Tray via distribution-specific packaging. It is not available via the generic GNU/Linux download or the Flatpak. Checkout the relevant notes on the downloads page for available options and details on package names. For further information about supported versions of Plasma, checkout the "Supported platforms" section.

Once installed, Plasma might need to be restarted for the Plasmoid to be selectable.

The Plasmoid can be added/shown in two different ways:

  1. It can be shown as part of the system tray Plasmoid.
    • This is likely the preferred way of showing it and may also happen by default.
    • Whether the Plasmoid is shown as part of the system tray Plasmoid can be configured in the settings of the system tray Plasmoid. You can access the settings of the system tray Plasmoid from its context-menu which can be opened by right-clicking on the arrow for expanding/collapsing.
    • This way it is also possible to show the icon only in certain states by choosing to show it only when important and selecting the states in the Plasmoid's settings.
    • Configuring the size has no effect when the Plasmoid is displayed as part of the system tray Plasmoid.
  2. It can be added to a panel or the desktop like any other Plasmoid.

This allows you to add multiple instances of the Plasmoid but it is recommended to pick only one place. For that it makes also most sense to ensure the autostart of the stand-alone tray application is disabled. Otherwise you would end up having two icons at the same time (one of the Plasmoid and one of the stand-alone application).

The Plasmoid cannot be closed via its context menu like the stand-alone application. Instead, you have to disable it in the settings of the system tray Plasmoid as explained before. If you have added the Plasmoid to a panel or the desktop you can delete it like any other Plasmoid.

In case the Plasmoid won't show up, checkout the "Troubleshooting KDE integration" section below for further help.

Configuring Dolphin integration

The Dolphin integration can be enabled/disabled in Dolphin's context menu settings. It will read Syncthing's API key automatically from its config file. If your Syncthing config file is not in the default location you need to select it via the corresponding menu action.

Configuring systemd integration

The next section explains what it is good for and how to use it. If it doesn't work on your system please read the subsequent sections as well before filing an issue.

Using the systemd integration

With the system configured correctly and systemd support enabled at build-time the following features are available:

However, these features are optional. To use them they must be enabled in the settings dialog first.

It is recommended to enable "Consider unit status …". Note that Syncthing might still not be immediately ready to serve API requests when the systemd unit turns active. Hence it is still required to configure a re-connect interval. The re-connect interval will only be in effect while the systemd unit is active. So despite the re-connect interval there will be no connection attempts while the systemd unit is inactive. That's all the systemd integration can optimize in that regard.

Be aware that Syncthing Tray assumes by default that the systemd unit is a user unit. If you are using a regular system-wide unit (including those started with …@username) you need to enable the "System unit" checkbox in the settings. Note that starting and stopping the system-wide Syncthing unit requires authorization (systemd can ask through PolicyKit).

Required system configuration

The communication between Syncthing Tray and systemd is implemented using systemd's D-Bus service. That means systemd's D-Bus service (which is called org.freedesktop.systemd1) must be running on your D-Bus. For user units the session D-Bus is relevant and for regular units (including those started with …@username) the system D-Bus is relevant.

It seems that systemd's D-Bus service is only available when D-Bus itself is started via systemd. That is by default the case under Arch Linux and openSUSE and likely most other modern distributions where it is usually started via "socket activation" (e.g. /usr/lib/systemd/user/dbus.socket for the session D-Bus).

All of this counts for the session D-Bus and for the system D-Bus although the startup of the session D-Bus can be screwed up particularly easy. One easy way to screw it up is to start a second instance of the session D-Bus manually e.g. via dbus-run-session. When starting the session D-Bus this way the systemd integration will not work and you will likely end up with two session D-Bus processes. It is also worth noticing that you do not need to set the DBUS_SESSION_BUS_ADDRESS variable manually because the systemd file dbus.socket should take care of this.

Note that the Plasma Wayland session screwed things up in the way I've described. This has been fixed with Only spawn dbus-run-session if there isn't a session already but this change might not be available on older distributions.

Build-time configuration

The systemd integration can be explicitly enabled/disabled at compile time by adding -DSYSTEMD_SUPPORT=ON/OFF to the CMake arguments. If the systemd integration does not work be sure your version of Syncthing Tray has been compiled with systemd support.

Note for distributors: There will be no hard dependency to systemd in any case. Distributions supporting alternative init systems do not need to provide differently configured versions of Syncthing Tray. Disabling the systemd integration is mainly intended for systems which do not use systemd at all (e.g. Windows and MacOS).

Configuring the built-in launcher

The built-in launcher can be accessed and configured within the settings dialog. The GUI should be self-explaining.

It is recommended to enable "Consider process status …". Note that Syncthing might not be immediately ready to serve API requests when started. Hence it is still required to configure a re-connect interval. The re-connect interval will only be in effect while the Syncthing process is running. So despite the re-connect interval there will be no connection attempts while the Syncthing process is not running.

Using the command-line interface

Syncthing Tray provides two command-line interfaces:

Configuring hotkeys

Use the same approach as for launching an arbitrary application via a hotkey in your graphical environment. Make it invoke

The Plasmoid can be shown via a hot-key as well by configuring one in the Plasmoid settings.

Using the Android app

The Android app requires Android 9 or later. So far it has only been tested on Android 14 and 15, though. Depending on the Android version and vendor-specific limitations you might run into permission errors and problems with the app being stopped by the OS. For me it works well enough on a three year old average Samsung device. It probably works on most recent phones except very low-end devices.

If you're starting from scratch you can simply install and start the app. At this point you will have to manually configure that you want to run Syncthing itself. Then you can add devices and folders as usual. If you have already another Syncthing app installed, read the next sections for testing/migrating.

The Android app is still experimental. Use it with care and create backups of your configuration and data before trying it. No builds are provided at this point so you have to build it from sources.

Testing the app without migrating

To only test the app without migrating your setup you can:

  1. Start the Syncthing app you are currently using (e.g. the Syncthing-Fork app) and ensure that Syncthing itself is running as well.
  2. Do an export of your Syncthing config so you know the web UI listening address and API key.
  3. Install and start the Syncthing app from Syncthing Tray.
  4. Ensure that running Syncthing is disabled under the runtime condition settings.
  5. Configure the information from step 1 in the connection settings.
  6. After applying all settings, the app UI can be used to control your existing Syncthing setup. Note that changes will affect your syncthing setup. You are not working in a read-only mode or on a copy.

Migrating data from your existing app setup

  1. Start the Syncthing app you are currently using (e.g. the Syncthing-Fork app).
  2. Do an export of your Syncthing config and data
  3. Stop the Syncthing app you are currently using.
  4. Start the Syncthing app from Syncthing Tray.
  5. Import the config and data from step 1 and select what parts of the config/data you want to import. (The import with selection is still WIP.)

Download

Checkout the download section on the website for an overview. Keep reading here for a more detailed list.

Source

See the release section on GitHub.

Packages and binaries

Build instructions

The application depends on c++utilities, qtutilities and qtforkawesome and is built the same way as these libraries. For basic instructions and platform-specific details checkout the README file of c++utilities.

To avoid building c++utilities/qtutilities/qtforkawesome separately, follow the instructions under "Building this straight". There's also documentation about various build variables which can be passed to CMake to influence the build.

Further dependencies

The following Qt modules are required (only the latest Qt 5 and Qt 6 version tested): Qt Core, Qt Concurrent, Qt Network, Qt D-Bus, Qt Gui, Qt Widgets, Qt Svg, Qt WebEngineWidgets/WebKitWidgets

It is recommended to use at least Qt 5.14 to avoid limitations in previous versions (see "Known bugs" section).

The built-in web view and therefore the modules WebEngineWidgets/WebKitWidgets are optional (see section "Select Qt module for web view and JavaScript").

The Qt Quick UI needs at least Qt 6.8 and also additional Qt modules found in the Qt Declarative repository. Its built-in web view uses the Qt WebView module which is optional.

To build the plugin for Dolphin integration KIO is also required. To skip building the plugin, add -DNO_FILE_ITEM_ACTION_PLUGIN:BOOL=ON to the CMake arguments.

To build the Plasmoid for the Plasma desktop, the Qt module QML and the KDE Frameworks module Plasma are required as well. Additionally, the Plasmoid requires the latest Qt version (5.15) for certain Qt Quick features. To skip building the Plasmoid, add -DNO_PLASMOID:BOOL=ON to the CMake arguments.

To specify the major Qt version to use, set QT_PACKAGE_PREFIX (e.g. add -DQT_PACKAGE_PREFIX:STRING=Qt6 to the CMake arguments). There's also KF_PACKAGE_PREFIX for KDE dependencies. Note that KDE integrations always require the same major Qt version as your KDE installation uses.

The following Boost libraries are required: Boost.Asio, Boost.Process, Boost.Filesystem

The launcher uses these libraries by default to handle sub processes correctly (and avoid leftover processes). Add -DUSE_BOOST_PROCESS:BOOL:OFF to the CMake arguments to get rid of the dependency to Boost libraries. This disables handling sub processes and QProcess (from Qt Core) is used instead.

It is also possible to build only the CLI (syncthingctl) by adding -DNO_MODEL:BOOL=ON and -DNO_FILE_ITEM_ACTION_PLUGIN:BOOL=ON to the CMake arguments. Then only the Qt modules core, network and dbus are required.

To get rid of systemd support, add -DENABLE_SYSTEMD_SUPPORT_BY_DEFAULT:BOOL=OFF to the CMake arguments. In this case the Qt module dbus is not required anymore. Note that there is no hard dependency to systemd in any case.

Building the testsuite requires CppUnit and Syncthing itself. Tests will spawn (and eventually terminate) a test instance of Syncthing that does not affect a possibly existing Syncthing setup on the build host.

Building this straight

  1. Install (preferably the latest version of) the GCC toolchain or Clang, the required Qt modules, iconv, CMake and Ninja.
  2. Get the sources. For the latest version from Git clone the following repositories: 
    cd "$SOURCES"
export MSYS=winsymlinks:nativestrict # only required when using MSYS2
git clone -c core.symlinks=true https://github.com/Martchus/cpp-utilities.git c++utilities
git clone -c core.symlinks=true https://github.com/Martchus/qtutilities.git
git clone -c core.symlinks=true https://github.com/Martchus/qtforkawesome.git
git clone -c core.symlinks=true https://github.com/ForkAwesome/Fork-Awesome.git forkawesome
git clone -c core.symlinks=true https://github.com/Martchus/syncthingtray.git
git clone -c core.symlinks=true https://github.com/Martchus/subdirs.git

    Note that core.symlinks=true is only required under Windows to handle symlinks correctly. This requires a recent Git version and a filesystem which supports symlinks (NTFS works). Additionally, you need to enable Windows Developer Mode. If you run into "not found" errors on symlink creation use git reset --hard within the repository to fix this.

  3. Configure the build 
    cd "$BUILD_DIR"
cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="/install/prefix" \
-DFORK_AWESOME_FONT_FILE="$SOURCES/forkawesome/fonts/forkawesome-webfont.woff2" \
-DFORK_AWESOME_ICON_DEFINITIONS="$SOURCES/forkawesome/src/icons/icons.yml" \
"$SOURCES/subdirs/syncthingtray"
    • Replace /install/prefix with the directory where you want to install.
    • Checkout the "Providing the font file" section of qtforkawesome's README for details regarding the ForkAwesome-related parameters.
  4. Build and install everything in one step: 
    cd "$BUILD_DIR"
ninja install
    • If the install directory is not writable, do not conduct the build as root. Instead, set DESTDIR to a writable location (e.g. DESTDIR="temporary/install/dir" ninja install) and move the files from there to the desired location afterwards.

Select Qt module for web view and JavaScript

Troubleshooting KDE integration

All KDE integrations are provided for KDE 5 and 6. The Qt version you have built Syncthing Tray against must match the KDE version you want to build the integrations for.

If the Dolphin integration or the Plasmoid does not work, check whether the files for those components have been installed in the right directories.

For instance, under Tumbleweed it looks like this for the Plasmoid:

/usr/lib64/qt5/plugins/plasma/applets/libsyncthingplasmoid.so
/usr/share/kservices5/plasma-applet-martchus.syncthingplasmoid.desktop
/usr/share/plasma/plasmoids/martchus.syncthingplasmoid/contents/ui/*.qml
/usr/share/plasma/plasmoids/martchus.syncthingplasmoid/metadata.desktop
/usr/share/plasma/plasmoids/martchus.syncthingplasmoid/metadata.json

The files for the Dolphin integration look like this under Tumbleweed:

/usr/lib64/qt5/plugins/libsyncthingfileitemaction.so
/usr/share/kservices5/syncthingfileitemaction.desktop

These examples were for KDE 5. It looks a bit different for KDE 6. Checkout my Arch Linux and openSUSE packaging for further examples.

The directory where the *.so file needs to be installed to, seems to differ from distribution to distribution. The right directory for your distribution can be queried using qmake using, e.g. qmake-qt5 -query QT_INSTALL_PLUGINS or qmake6 -query QT_INSTALL_PLUGINS depending on the Qt version. In doubt, just look where other Qt plugins are stored.

The build system is able to do that query automatically. In case this does not work, it is also possible to specify the directory manually, e.g. for Tumbleweed one would add -DQT_PLUGIN_DIR=/usr/lib64/qt6/plugins to the CMake arguments.

Also be sure that the version of the Plasma framework the Plasmoid was built against is not newer than the version actually installed on the system. This can happen if repositories are misconfigured, e.g. when using Fedora 39 but adding the Fedora 40 repo.

If the Plasmoid still won't load, checkout the log of plasmashell/plasmoidviewer/plasmawindowed. Also consider using strace to find out at which paths the shell is looking for *.desktop and *.so files.

For a development setup of the KDE integration, continue reading the subsequent section.

Contributing, developing, debugging

Translations

Currently translations for English and German are available. Qt's built-in localization/translation framework is used under the hood.

Note that syncthingctl has not been internationalized yet so it supports only English.

Add a new locale

Translations for further locales can be added quite easily:

  1. Append a new translation file for the desired locale to the TS_FILES list in connector/CMakeLists.txt, model/CMakeLists.txt, widgets/CMakeLists.txt, fileitemactionplugin/CMakeLists.txt, plasmoid/CMakeLists.txt and tray/CMakeLists.txt.
  2. Configure a new build, e.g. follow steps under Building this straight.
  3. Conduct a full build or generate only translation files via the translations target.
  4. New translation files should have been created by the build system under connector/translations, model/translations, widgets/translations, fileitemactionplugin/translations, plasmoid/translations and tray/translations and the translations folder of qtutilities.
  5. Open the files with Qt Linguist to add translations. Qt Linguist is part of the Qt Tools repository and its usage is well documented.

Extend/update existing translations

Remarks

Using backend libraries

The contained backend libraries (which provide connecting to Syncthing, data models and more) are written for internal use within the components contained by this repository.

Hence those libraries do not provide a stable ABI/API. If you like to use them to develop Syncthing integration or tooling with Qt and C++, it makes most sense to contribute it as an additional component directly to this repository. Then I will be able to take it into account when changing the API.

KDE integration

Since the Dolphin integration and the Plasmoid are plugins, testing and debugging requires a few extra steps. See Testing and debugging Dolphin/KIO plugin with Qt Creator and Testing and debugging Plasmoid with Qt Creator.

Logging

It is possible to turn on logging of the underlying library by setting environment variables:

Useful environment variables for development

Known bugs and workarounds

The following bugs are caused by dependencies or limitations of certain platforms. For bugs of Syncthing Tray itself, checkout the issues on GitHub.

Workaround positioning issues under Wayland

The Qt Widgets based version basically works under Wayland but there are positioning issues and the settings regarding positioning have no effect (see "List of bugs" section below). One can workaround this limitation by telling the window manager how to place the window, e.g. under Sway one could add a configuration like this:

for_window [title="^Syncthing Tray( \(.*\))?$"] floating enable, border none, resize set 450 400, move position 916 0

Alternatively, one can also configure Syncthing Tray to use a normal window in the appearance settings. That doesn't fix the positioning issue but then it looks just like a normal application so not being positioned in the tray area is less problematic.

You can also select the window type "None". This disables Syncthing Tray's own UI completely and instead opens Syncthing directly when the tray icon is clicked.

Tweak GUI settings for dark mode under Windows

The dark mode introduced in Windows 10 does not affect traditional desktop applications like Syncthing Tray. As of version 6.7 the underlying toolkit Qt nevertheless provides a style specifically for Windows 11 that supports dark mode. So as of Qt 6.7 the dark mode should work out of the box on Windows 11. Otherwise you can select the widgets style "Fusion" under "Qt/Appearance". Then Syncthing Tray will no longer use native styling of traditional desktop apps and follow the dark mode setting (as Qt 6.5 added dark mode support).

It is also recommended to apply some further tweaks:

When using an older Qt version than 6.5 you will also have to resort to more manual tweaking:

When using Syncthing Tray 1.3.x or older, you need to restart Syncthing Tray for these changes to have any effect. It is not sufficient to close the last window; the process needs to be restarted.

Note that one can alternatively also enable Windows' "High contrast" setting which seems to bring back the traditional theming/coloring (which has normally been removed). Unfortunately it doesn't look very nice overall. Checkout https://github.com/tomasz1986/classic2000 to see how Windows looks like with high contrast applied, or if you're in need for themes that look at least nicer than what's shipped with Windows.

DPI awareness under Windows

Syncthing Tray supports PMv2 out of the box as of Qt 6. You may tweak settings according to the Qt documentation.

Workaround broken High-DPI scaling of Plasmoid under X11

This problem has been resolved so make sure you are using an up-to-date Plasma version. Otherwise, setting the environment variable PLASMA_USE_QT_SCALING=1 might help.

List of bugs

Copyright notice and license

Copyright © 2016-2024 Marius Kittler

All code - unless stated otherwise in a comment on top of the file - is licensed under GPL-2-or-later. This does not apply to code contained in Git repositories included as Git submodule (which contain their own README and licensing information).

Attribution for 3rd party content

Syncthing Tray contains icons from various sources:

None of these icons have been (intentionally) modified so no copyright for modifications is asserted.

Some of the code is based on code from other open source projects:

The original code has been modified. Copyright as mentioned in the previous section applies to modifications.