2018-05-14 17:17:08 +02:00
# [Syncthing](https://github.com/syncthing/syncthing) Tray
* Qt 5-based tray application
* [Dolphin ](https://www.kde.org/applications/system/dolphin )/[Plasma](https://www.kde.org/plasma-desktop)
integration
* command-line interface
* Qt-ish C++ interface to control Syncthing
2016-08-25 00:45:32 +02:00
2019-09-30 18:02:44 +02:00
---
Checkout the [official forum thread ](https://forum.syncthing.net/t/yet-another-syncthing-tray ) for discussions
and announcement of new features.
Issues can be created on GitHub but please read the "Known bugs" and "Planned features" sections in this document
before.
2016-09-12 21:54:25 +02:00
## Supported platforms
* Designed to work under any desktop environment supported by Qt 5 with tray icon
2016-12-26 19:06:54 +01:00
support
2018-01-28 18:33:48 +01:00
* No desktop environment specific libraries required (only for optional features)
2019-06-22 17:38:16 +02:00
* Tested under
* X Window System
* Plasma 5 (beside Qt Widgets based version there is a native "Plasmoid")
* Openbox/lxqt/LXDE
* Openbox/qt5ct/Tint2
* Awesome/qt5ct
2019-08-10 01:47:49 +02:00
* Cinnamon (native look and feel using [adwaita-qt ](https://github.com/FedoraQt/adwaita-qt ))
* Deepin Desktop Environment
2019-08-12 00:33:23 +02:00
* Xfce
2019-06-22 17:38:16 +02:00
* Wayland
2019-07-27 15:43:20 +02:00
* Plasma 5
* native "Plasmoid" works well
* for Qt Widgets based version see note below
2019-07-31 20:06:32 +02:00
* other desktop environments
* for Qt Widgets based version see note below
* besides, the Qt Widgets based version would only work if the platform integration plugin
used for Qt 5 applications uses the D-Bus protocol (or whatever is supported by your system
tray) to show the tray icon
2017-08-29 23:58:49 +02:00
* Windows 10
2019-07-21 16:23:01 +02:00
* macOS 10.14 Mojave
2016-09-24 16:19:23 +02:00
* Can be shown as regular window if tray icon support is not available
2016-09-12 21:54:25 +02:00
2019-07-27 15:43:20 +02:00
The Qt Widgets based version basically works under Wayland but there are positioning issues (see known bugs
section).
2019-06-22 17:38:16 +02:00
If you can confirm it works under other desktop environments, please add it
2019-07-21 16:23:01 +02:00
to the list.
2016-12-26 19:06:54 +01:00
2016-09-12 21:54:25 +02:00
## Features
2016-08-25 00:45:32 +02:00
* Provides quick access to most frequently used features but does not intend to replace the official web UI
2017-08-29 23:58:49 +02:00
* Check state of directories and devices
* Check current traffic statistics
* Display further details about directories and devices, like last file, last
scan, items out of sync, ...
* Display ongoing downloads
* Display Syncthing log
* Trigger re-scan of a specific directory or all directories at once
* Open a directory with the default file browser
* Pause/resume a specific device or all devices at once
* Pause/resume a specific directory
2016-08-25 00:45:32 +02:00
* Shows Syncthing notifications
2017-03-29 23:32:48 +02:00
* Can read the local Syncthing configuration file for quick setup when just connecting to local instance
2017-03-15 22:12:21 +01:00
* Can show the status of the Syncthing systemd unit and allows to start and stop it (see section *Use of systemd* )
2016-09-03 19:39:43 +02:00
* Provides an option to conveniently add the tray to the applications launched when the desktop environment starts
2017-03-17 00:42:36 +01:00
* Can launch Syncthing and syncthing-inotify automatically when started and display stdout/stderr (useful under
Windows)
2016-08-25 00:45:32 +02:00
* Provides quick access to the official web UI
2017-08-29 23:58:49 +02:00
* Utilizes either Qt WebKit or Qt WebEngine
* Can be built without web view support as well (then the web UI is opened in the regular browser)
2016-09-03 20:14:52 +02:00
* Allows quickly switching between multiple Syncthing instances
2016-12-12 23:43:06 +01:00
* Shows notifications via Qt or uses D-Bus notification daemon directly
2017-10-03 17:03:03 +02:00
* Also features a simple command line utility `syncthingctl`
2018-08-25 11:35:47 +02:00
* Check status
2017-10-03 17:03:03 +02:00
* Trigger rescan/pause/resume/restart
* Wait for idle
2018-08-25 11:35:47 +02:00
* View and modify configuration
2017-10-03 17:03:03 +02:00
* Supports Bash completion, even for directory and device names
2017-02-25 18:28:35 +01:00
* Also bundles a KIO plugin which shows the status of a Syncthing directory
and allows to trigger Syncthing actions in Dolphin file manager
2017-08-29 23:58:49 +02:00
* Rescan selected items
* Rescan entire Syncthing directory
* Pause/resume Syncthing directory
* See also screenshots section
2018-08-25 11:35:47 +02:00
* Also has an implementation as Plasmoid for Plasma 5 desktop
2019-09-30 18:02:44 +02:00
* Build Syncthing as a library to run it in the same process as the tray/GUI (optional build configuration, not enabled
by default)
2017-01-08 21:22:25 +01:00
* English and German localization
2016-09-12 21:54:25 +02:00
## Planned features
2018-05-14 17:17:08 +02:00
The tray is still under development; the following features are under construction or planned:
2017-08-29 23:58:49 +02:00
2018-05-14 17:17:08 +02:00
* Create Qt Quick Controls 2 and Kirigami 2 based frontend for mobile devices (focusing on Android)
2016-09-12 21:54:25 +02:00
* Show recently processed items
2017-10-03 16:57:25 +02:00
* Make some notifications configurable on folder level
* Optionally notify for single file updates (https://github.com/Martchus/syncthingtray/issues/7)
2016-08-25 00:45:32 +02:00
## Screenshots
2019-02-23 13:56:16 +01:00
The screenshots might not be up-to-date.
2016-09-12 21:54:25 +02:00
2019-03-09 14:55:29 +01:00
### Qt Widgets based GUI under Openbox/Tint2 with dark Breeze theme
2016-08-26 16:43:53 +02:00
2016-10-30 18:20:00 +01:00
### Under Plasma 5
2019-05-28 17:59:43 +02:00
#### Light theme
2019-03-09 14:55:29 +01:00
2019-05-28 17:59:43 +02:00
#### Dark theme
2019-03-09 14:55:29 +01:00
2019-05-28 17:59:43 +02:00
#### Customized icons
2016-08-26 16:43:53 +02:00
2016-10-30 18:20:00 +01:00
### Settings dialog
2016-09-30 23:55:25 +02:00
2016-08-26 16:43:53 +02:00
2016-10-30 18:20:00 +01:00
### Web view
2016-09-30 23:55:25 +02:00
2016-10-30 18:20:00 +01:00
2016-08-25 00:45:32 +02:00
2017-02-25 18:28:35 +01:00
### Syncthing actions for Dolphin
2016-12-12 23:58:06 +01:00
## Hotkeys
To create hotkeys, you can use the same approach as for any other
application. Just make it invoke the `syncthingctl` application with
the arguments for the desired action.
### Hotkey for web UI
Just add `--webui` to the `syncthingtray` arguments to trigger the web UI.
2016-09-24 16:19:23 +02:00
Syncthing Tray ensures that no second instance will be spawned if it is already
2016-12-12 23:58:06 +01:00
running and just trigger the web UI.
2016-09-24 16:19:23 +02:00
2017-03-15 22:12:21 +01:00
## Use of systemd
Use of systemd can be explicitely enabled/disabled by adding
`-DSYSTEMD_SUPPORT=ON/OFF` to the CMake arguments. There will be no hard
dependency to systemd in any case.
With systemd support the tray can start and stop the systemd unit of Syncthing.
It will also take the unit status into account when connecting to the local
instance. So connection attempts can be prevented when Syncthing isn't running
anyways. However, those features are optional. To use them they must be enabled
in the settings dialog first.
Note that this only works when starting Syncthing as user service. This is
described in the [Arch Wiki ](https://wiki.archlinux.org/index.php/Systemd/User ).
2016-11-26 12:49:40 +01:00
## Download
### Source
See the release section on GitHub.
### Packages and binaries
* Arch Linux
2017-07-31 23:51:26 +02:00
* for PKGBUILDs checkout [my GitHub repository ](https://github.com/Martchus/PKGBUILDs ) or
[the AUR ](https://aur.archlinux.org/packages?SeB=m&K=Martchus )
2018-03-14 18:56:39 +01:00
* for a binary repository checkout [my website ](http://martchus.no-ip.biz/website/page.php?name=programming )
2019-02-06 17:33:18 +01:00
* Tumbleweed, Leap, Fedora
2017-07-31 23:51:26 +02:00
* for RPM \*.spec files and binary repository checkout
[openSUSE Build Servide ](https://build.opensuse.org/project/show/home:mkittler )
2019-02-06 17:33:18 +01:00
* there's also a [repo with builds of Git master ](https://build.opensuse.org/project/show/home:mkittler:vcs )
* Exherbo
* packages for my other project "Tageditor" and dependencies could serve as a base and are provided
by [the platypus repository ](https://git.exherbo.org/summer/packages/media-sound/tageditor )
2018-02-09 00:20:50 +01:00
* Gentoo
2018-03-14 18:56:39 +01:00
* packages for my other projects (which are built in the same way) are provided by perfect7gentleman; checkout his
2018-02-09 00:20:50 +01:00
[repository ](https://github.com/perfect7gentleman/pg_overlay )
2019-02-06 17:33:18 +01:00
* Other GNU/Linux systems
* [AppImage repository for releases on the openSUSE Build Service ](https://download.opensuse.org/repositories/home:/mkittler:/appimage/AppImage )
* [AppImage repository for builds from Git master the openSUSE Build Service ](https://download.opensuse.org/repositories/home:/mkittler:/appimage:/vcs/AppImage/ )
2016-11-26 12:49:40 +01:00
* Windows
2017-07-31 23:51:26 +02:00
* for mingw-w64 PKGBUILDs checkout [my GitHub repository ](https://github.com/Martchus/PKGBUILDs )
2018-02-09 00:20:50 +01:00
* for statically linked binaries checkout the [release section on GitHub ](https://github.com/Martchus/syncthingtray/releases )
2018-01-28 18:33:48 +01:00
* [my website ](http://martchus.no-ip.biz/website/page.php?name=programming ) also contains an occasionally
updated archive with a dynamically linked executable
2019-07-21 16:23:01 +02:00
* Mac OS X/macOS
2019-08-29 07:18:57 +02:00
* package syncthingtray is available from [MacPorts ](https://ports.macports.org/port/syncthingtray/ )
2016-08-25 00:45:32 +02:00
## Build instructions
2018-10-15 17:46:38 +02:00
The application depends on [c++utilities ](https://github.com/Martchus/cpp-utilities ) and
[qtutilities ](https://github.com/Martchus/qtutilities ) and is built the same way as these libaries.
For basic instructions checkout the README file of [c++utilities ](https://github.com/Martchus/cpp-utilities ).
For building this straight, see the section below. There's also documentation about
[various build variables ](https://github.com/Martchus/cpp-utilities/blob/master/doc/buildvariables.md ) which
can be passed to CMake to influence the build.
2016-08-25 00:45:32 +02:00
2018-04-01 23:26:29 +02:00
### Further dependencies
The following Qt 5 modules are requried (version 5.6 or newer): core network dbus gui widgets svg webenginewidgets/webkitwidgets
2016-08-25 00:45:32 +02:00
2017-02-26 19:15:21 +01:00
The built-in web view is optional (see section "Select Qt module for WebView").
2018-04-01 23:26:29 +02:00
To build the plugin for Dolphin integration KIO is also requried. Additionally, the Dolphin plugin requires Qt 5.8 or newer. To skip
building the plugin, add `-DNO_FILE_ITEM_ACTION_PLUGIN:BOOL=ON` to the CMake arguments.
2017-02-26 19:15:21 +01:00
2017-10-05 00:31:51 +02:00
To build the Plasmoid for the Plasma 5 desktop, the Qt 5 module QML and the KF5 module
Plasma are required as well. Additionally, the Plasmoid requires Qt 5.8 or newer. To skip
building the Plasmoid, add `-DNO_PLASMOID:BOOL=ON` to the CMake arguments.
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` to the CMake arguments.
In this case the Qt module D-Bus is not required anymore. Note that there is no hard dependency
to systemd in any case.
2017-02-26 19:15:21 +01:00
2018-04-01 23:26:29 +02:00
Building the testsuite requires CppUnit and Qt 5.8 or higher.
### Building this straight
2018-10-15 17:46:38 +02:00
0. Install (preferably the latest version of) the CGG toolchain or Clang, the required Qt 5 modules and CMake.
2016-09-30 23:55:25 +02:00
1. Get the sources. For the lastest version from Git clone the following repositories:
```
cd $SOURCES
2017-07-19 23:53:36 +02:00
git clone https://github.com/Martchus/cpp-utilities.git c++utilities
2016-09-30 23:55:25 +02:00
git clone https://github.com/Martchus/qtutilities.git
2017-02-20 14:22:58 +01:00
git clone https://github.com/Martchus/syncthingtray.git
2016-09-30 23:55:25 +02:00
git clone https://github.com/Martchus/subdirs.git
```
2. Build and install everything in one step:
```
cd $BUILD_DIR
cmake \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX="/install/prefix" \
$SOURCES/subdirs/syncthingtray
make install -j$(nproc)
```
2019-05-28 17:58:46 +02:00
### Select Qt module for web view and JavaScript
* Add `-DWEBVIEW_PROVIDER:STRING=webkit/webengine/none` to the CMake arguments to use either Qt WebKit (works with
'revived' version as well), Qt WebEngine or no web view at all. If no web view is used, the Syncthing web UI is
opened in the default web browser. Otherwise the user can choose between the built-in web view and the web browser.
* Add `-DJS_PROVIDER:STRING=script/qml/none` to the CMake arguments to use either Qt Script, Qt QML or no JavaScript
engine at all. If no JavaScript engine is used, the CLI does not support scripting configuration changes.
2016-09-01 16:34:30 +02:00
2019-02-28 17:09:35 +01:00
#### Limitations of Qt WebEngine compared to Qt WebKit
2016-09-25 20:54:09 +02:00
* Currently there is no way to allow a particular self-signed certificate in Qt
WebEngine. Currently any self-signed certificate is accepted! See:
2016-09-30 23:55:25 +02:00
https://bugreports.qt.io/browse/QTBUG-51176
2016-09-01 16:34:30 +02:00
* Qt WebEngine can not be built with mingw-w64.
2016-11-16 20:40:54 +01:00
* QWebEngineView seems to eat `keyPressEvent` .
2016-09-01 16:34:30 +02:00
* Qt WebEngine is more buggy in my experience.
2016-09-30 23:55:25 +02:00
* Security issues are not a concern because no other website than the
Syncthing web UI is shown. Any external links will be opened in the
regular web browser anyways.
2017-01-08 21:22:25 +01:00
2019-02-28 17:09:35 +01:00
### Troubleshooting KDE integration
If the Dolphin integration or the Plasmoid don't 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
```
The directory the `*.so` file needs to be installed to seems to differ from distribution to
distribution. The right directory for your distribution can be queried from qmake using
`qmake-qt5 -query QT_INSTALL_PLUGINS` . In doubt, just look where other Qt 5 plugins are stored.
Actually the build system should be able to do that query automatically. It is also possible to
specify the directory manually, e.g. for Tumbleweed one would add
`-DQT_PLUGIN_DIR=/usr/lib64/qt5/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. That can for instance easily happen when using
`tumbleweed-cli` for sticking to a previous snapshot but having the lastest version of the plasmoid
from my home repository installed.
---
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.
2017-10-06 17:07:45 +02:00
## Contributing
### Adding translations
2017-01-08 21:22:25 +01:00
Currently translations for English and German are available. Further translations
can be added quite easily:
1. Append a new translation file for the desired locale to the `TS_FILES` list
2017-10-06 17:12:55 +02:00
in `connector/CMakeLists.txt` , `model/CMakeLists.txt` , `widgets/CMakeLists.txt` ,
2019-07-31 20:04:25 +02:00
`fileitemactionplugin/CMakeLists.txt` , `plasmoid/CMakeLists.txt` and
`tray/CMakeLists.txt` .
2017-01-08 21:22:25 +01:00
2. Trigger a new build, eg. follow steps under *Building this straight* .
3. New translation files should have been created by the build system under
2019-07-31 20:04:25 +02:00
`connector/translations` , `model/translations` , `widgets/translations` ,
`fileitemactionplugin/translations` , `plasmoid/translations` and
`tray/translations` .
2017-01-08 21:22:25 +01:00
4. Open the files with Qt Linguist to add translations. Qt Linguist is part of
the [Qt Tools repository ](http://code.qt.io/cgit/qt/qttools.git/ ) and its usage
is [well documented ](http://doc.qt.io/qt-5/linguist-translators.html ).
2017-05-22 00:26:51 +02:00
2019-08-20 22:32:40 +02:00
#### Remarks
* Syncthing Tray displays also text from [qtutilities ](https://github.com/Martchus/qtutilities ).
Hence it makes sense adding translations there as well (following the same procedure).
* The CLI `syncthingctl` currently does not support translations.
2017-10-06 17:12:55 +02:00
2017-10-06 17:07:45 +02:00
### Using backend libraries
2018-04-01 23:26:29 +02:00
The contained backend libraries (which provide connecting to Syncthing, data models and more) are written for internal
2017-10-06 17:07:45 +02:00
use whithin 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 changeing the API.
2018-01-28 18:33:48 +01:00
### 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 ](/fileitemactionplugin/testing.md )
and [Testing and debugging Plasma 5 plasmoid with Qt Creator ](/plasmoid/testing.md ).
2017-05-22 00:26:51 +02:00
## Known bugs
The following bugs are caused by dependencies and hence tracked externally. For bugs of Syncthing Tray itself, checkout the issues
on GitHub.
2019-07-27 15:43:20 +02:00
* Wayland limitations
* The tray menu can not be positioned correctly under Wayland because the protocol does not allow setting window positions from
the client-side (at least I don't know a way to do it). This issue can not be fixed unless Wayland provides an API to set the
window position to specific coordinates or a system tray icon.
See discussion on [freedesktop.org ](https://lists.freedesktop.org/archives/wayland-devel/2014-August/017584.html ).
Note that the Plasmoid is not affected by this limitation.
* While the tray menu is shown its entry is shown in the taskbar. Not sure whether there is a way to avoid this.
* Qt bugs
* Any self-signed certificate is accepted when using Qt WebEngine due to Qt bug https://bugreports.qt.io/browse/QTBUG-51176.
* Pausing/resuming folders and devices doesn't work when using scan-intervalls with a lot of zeros because of Syncthing bug
https://github.com/syncthing/syncthing/issues/4001. This has already been fixed on the Qt-side with
https://codereview.qt-project.org/#/c/187069/. However, the fix is only available in Qt 5.9 and above.
* The tray disconnects from the local instance when the network connection goes down. The network connection must be restored or
the tray restarted to be able to connect to local Syncthing again. This is caused by Qt bug
https://bugreports.qt.io/browse/QTBUG-60949.
2019-02-17 23:45:53 +01:00
## Attribution for 3rd party content
2019-02-18 00:35:32 +01:00
* Some icons are taken from the Syncthing project.
* Some icons are taken from [Font Awesome ](https://fontawesome.com ) (see [their license ](https://fontawesome.com/license )).
* Fallback icons are taken from KDE/Breeze project.
