You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Quaternion is a cross-platform desktop IM client for the [Matrix](https://matrix.org) protocol in development.
8
+
Quaternion is a cross-platform desktop IM client for the [Matrix](https://matrix.org) protocol.
7
9
8
-
## Version 0.0.4 out now!
9
-
The release (including binaries for Windows) can be found [here](https://github.com/QMatrixClient/Quaternion/releases/tag/v0.0.4).
10
+
## Contacts
11
+
Most of talking around Quaternion happens in our Matrix room: [#quaternion:matrix.org](https://matrix.to/#/#quaternion:matrix.org).
12
+
13
+
You can also file issues at [the project's issue tracker](https://github.com/QMatrixClient/Quaternion/issues). If you have what looks like a security issue, please see respective instructions in CONTRIBUTING.md.
10
14
11
15
## Download
12
-
### Binaries
13
-
There are no official packaging at the moment. Some links to unofficial packages follow:
The latest release (with links to cross-platform source code archives, as well as archived binaries for Windows) can be found at [GitHub Releases page](https://github.com/QMatrixClient/Quaternion/releases/latest). Build instructions for the source code can be found further in this file (see "Building").
15
17
16
-
Windows: automatic builds are packaged upon every commit (CI) at https://ci.appveyor.com/project/QMatrixClient/quaternion (go to "Jobs", select the job for your architecture, then "Artifacts")
18
+
Automatic builds for Windows are packaged by AppVeyor CI upon every commit. To get an archive, surf to the [AppVeyor CI page for Quaternion](https://ci.appveyor.com/project/QMatrixClient/quaternion), then go to "Jobs", click on a job for your architecture and find the archive in "Artifacts".
17
19
18
-
#### OpenSSL on Windows
19
-
Since we can't rely on package management on Windows, Qt libraries and the runtime are packaged/installed together with Quaternion. However, two libraries, namely ssleay32.dll and libeay32.dll from OpenSSL project, are not installed automatically because of export restrictions. Unless you already have them around (e.g., they are a part of any Qt development installation, see `Tools/<MinGW toolchain>/opt/bin`), your best bet is to download these libraries yourself and either install them system-wide (which probably makes sense as soon as you keep them up-to-date) or put them next to quaternion.exe. Having the libraries system-wide implies they are in your PATH.
20
+
Unofficial package for Arch Linux: https://aur.archlinux.org/packages/quaternion/
20
21
21
-
In case of trouble with libraries on Windows, [the Dependencies Walker tool aka depends.exe](http://www.dependencywalker.com/) helps a lot in navigating the DLL hell - especially when you have a mixed 32/64-bit environment or have different versions of the same library scattered around. OpenSSL, in particular, is notoriously often dragged along by all kinds of software; and you may have other copies of Qt around which you didn't even know about - e.g., with CMake GUI.
22
+
Work in progress to get Quaternion to Flathub: https://github.com/flathub/flathub/pull/90.
22
23
23
-
### Source code
24
-
Quaternion source code repository at GitHub: https://github.com/QMatrixClient/Quaternion
24
+
## Running
25
+
Just start the executable in your most preferred way - either from build_dir and from the installed location.
26
+
27
+
### Before you run it on Windows
28
+
Since we can't rely on package management on Windows, Qt libraries and a C++ runtime are packaged/installed together with Quaternion. However, OpenSSL libraries (ssleay32.dll and libeay32.dll) are not installed automatically because of export restrictions. Unless you already have them around (e.g., they are a part of any Qt development installation, see `Tools/<MinGW toolchain>/opt/bin`), your best bet is to find and download these libraries yourself, and either install them system-wide (which probably makes sense as soon as you keep them up-to-date; make sure the location is in your PATH) or put them next to quaternion.exe.
29
+
30
+
### Configuration and cache files
31
+
Quaternion stores its configuration in a way standard for Qt applications. It will read and write the configuration in the user-specific location (creating it if non-existent) and will only read the system-wide location with reasonable defaults if the configuration is nowhere to be found.
32
+
- Linux:
33
+
- system-wide: `$XDG_CONFIG_DIR/QMatrixClient/quaternion` or `/etc/xdg/QMatrixClient/quaternion`
NOTE: as of version 0.0.4, your access tokens are stored in the configuration as well; this means that unless your HKEY_USERS registry nodes (Windows)/$HOME files (Linux, OSX) are inaccessible to other users on the same computer, another user can take your access token and impersonate you on Matrix. This is [a known issue](https://github.com/QMatrixClient/Quaternion/issues/181). A workaround is to not set "Stay logged in" flag upon login; in that case access tokens are only stored in memory but you have to login at each Quaternion startup.
43
+
44
+
Quaternion caches the rooms state on the file system in a conventional location for your platform, as follows:
Cache files are safe to delete at any time. If Quaternion doesn't find them when starting up it downloads the whole state from Matrix servers, which can take much time (up to a minute and even more, depending on the number of rooms and the number of users in them). Deleting cache files may help to fix problems such as missing avatars, rooms stuck in a wrong state etc.
50
+
51
+
## Building
52
+
53
+
Quaternion source code is hosted at GitHub: https://github.com/QMatrixClient/Quaternion - checking out a certain commit or tag from GitHub (rather than downloading the archive) is the recommended way for packagers.
25
54
26
55
Quaternion uses libqmatrixclient that is developed in a separate GitHub repo and is fetched as a git submodule. To get all necessary sources:
27
56
- if you haven't cloned the Quaternion sources yet:
@@ -36,17 +65,10 @@ git submodule update
36
65
37
66
There are very few tags so far; there will be more, as new versions are released.
38
67
39
-
## Contacts
40
-
Most of talking around Quaternion happens in our Matrix room: [#quaternion:matrix.org](https://matrix.to/#/#quaternion:matrix.org).
41
-
42
-
You can also file issues at [the project's issue tracker](https://github.com/QMatrixClient/Quaternion/issues). If you have what looks like a security issue, please see respective instructions in CONTRIBUTING.md.
43
-
44
-
## Building
45
-
46
68
### Pre-requisites
47
69
- a Linux, MacOS or Windows system (desktop versions tried; mobile Linux/Windows might work too)
48
70
- For Ubuntu flavours - Trusty Tar or later (or a derivative) is good enough; older ones will need PPAs at least for a newer Qt
49
-
- a Git client (to check out this repo)
71
+
- a Git client to check out this repo
50
72
- CMake (from your package management system or [the official website](https://cmake.org/download/))
51
73
- Qt 5 (either Open Source or Commercial), version 5.2.1 or higher as of this writing (check the CMakeLists.txt for most up-to-date information). Qt 5.3 or higher recommended on Windows.
52
74
- a C++ toolchain supported by your version of Qt (see a link for your platform at [the Qt's platform requirements page](http://doc.qt.io/qt-5/gettingstarted.html#platform-requirements))
`brew install qt5` should get you Qt5. You may need to tell CMake about the path to Qt by passing `-DCMAKE_PREFIX_PATH=<where-Qt-installed>`
67
89
68
90
#### Windows
69
-
1. Install a Git client and CMake. The commands in further sections imply that git and cmake are in your PATH - otherwise you have to prepend them with your actual paths.
70
-
1. Install Qt5, using their official installer. If for some reason you need to use Qt 5.2.1, select its Add-ons component in the installer as well; for later versions, no extras are needed. If you don't have a toolchain and/or IDE, you can easily get one by selecting Qt Creator and at least one toolchain under Qt Creator. At least Qt 5.3 is recommended on Windows; `windeployqt` in Qt 5.2.1 is not functional enough to provide a standalone installation for Quaternion though you can still compile and run it from your build directory.
91
+
1. Install CMake. The commands in further sections imply that cmake is in your PATH - otherwise you have to prepend them with actual paths.
92
+
1. Install Qt5, using their official installer. If for some reason you need to use Qt 5.2.1, select its Add-ons component in the installer as well; for later versions, no extras are needed. If you don't have a toolchain and/or IDE, you can easily get one by selecting Qt Creator and at least one toolchain under Qt Creator. At least Qt 5.3 is recommended on Windows; `windeployqt` in Qt 5.2.1 is not functional enough to provide a standalone installation for Quaternion though you can still compile and run from your build directory.
71
93
1. Make sure CMake knows about Qt and the toolchain - the easiest way is to run a qtenv2.bat script that can be found in `C:\Qt\<Qt version>\<toolchain>\bin` (assuming you installed Qt to `C:\Qt`). The only thing it does is adding necessary paths to PATH - you might not want to run it on system startup but it's very handy to setup environment before building. Setting CMAKE_PREFIX_PATH, the same way as for OS X (see above), also helps.
72
94
73
95
There are no official MinGW-based 64-bit packages for Qt. If you're determined to build 64-bit Quaternion, either use a Visual Studio toolchain or build Qt5 yourself as described in Qt documentation.
74
96
75
-
### Building
97
+
### Build
76
98
In the root directory of the project sources:
77
99
```
78
100
mkdir build_dir
@@ -82,12 +104,15 @@ cmake --build . --target all
82
104
```
83
105
This will get you an executable in `build_dir` inside your project sources. `CMAKE_INSTALL_PREFIX` variable of CMake controls where Quaternion will be installed - pass it to `cmake ..` above if you wish to alter the default (see the output from `cmake ..` to find out the configured values).
84
106
85
-
### Installation
107
+
### Install
86
108
In the root directory of the project sources: `cmake --build build_dir --target install`.
87
109
88
110
On Linux, `make install` (with `sudo` if needed) will work equally well.
89
111
90
-
### Flatpak
112
+
### Package
113
+
Packagers are very scarce so far, so please step up and support your favourite system! Notably, we still need a MacOS maintainer - Quaternion sees no actual usage/testing on this platform yet.
114
+
115
+
#### Flatpak
91
116
If you run Linux and your distribution supports flatpak, you can easily build and install Quaternion as a flatpak package:
92
117
93
118
```
@@ -104,24 +129,6 @@ Whenever you want to update your Quaternion package, do the following from the f
104
129
flatpak --user update
105
130
```
106
131
107
-
## Running
108
-
Just start the executable in your most preferred way - either from build_dir and from the installed location. Especially on Windows, make sure that Qt5 dynamic libraries and their dependencies are either in your PATH (see the note about `qtenv2.bat` in "Pre-requisites" above) or next to the executable. See also "OpenSSL on Windows" section above.
109
-
110
-
### Configuration and cache files
111
-
Quaternion stores its configuration in a way standard for Qt applications. It will read and write the configuration in the user-specific location (creating it if non-existent) and will only read the system-wide location with reasonable defaults if the configuration is nowhere to be found.
112
-
- Linux: files under $XDG_CONFIG_DIR/QMatrixClient/quaternion or /etc/xdg/QMatrixClient/quaternion (system-wide) and $HOME/.config/QMatrixClient/quaternion (user-specific)
113
-
- OSX: /Library/Preferences/com.QMatrixClient.quaternion.plist (system-wide) and $HOME/Library/Preferences/com.QMatrixClient.quaternion.plist (user-specific)
114
-
- Windows: registry keys under HKEY_LOCAL_MACHINE\Software\QMatrixClient\quaternion (system-wide) and HKEY_CURRENT_USER\Software\QMatrixClient\quaternion (user-specific)
115
-
116
-
NOTE: as of 0.0.4, your access tokens are stored in the configuration as well; this means that unless your HKEY_USERS registry nodes (Windows)/$HOME files (Linux, OSX) are inaccessible to other users on the same computer, another user can take your access token and impersonate you on Matrix. This is [a known issue](https://github.com/QMatrixClient/Quaternion/issues/181). A workaround is to not set "Stay logged in" flag upon login; in that case access tokens are only stored in memory but you have to login at each Quaternion startup.
117
-
118
-
Quaternion caches the rooms state on the file system - also in a location standard for your platform, as follows:
Cache files are safe to delete at any time. If Quaternion doesn't find them it downloads the whole state from Matrix servers upon its startup, which can take much time (up to a minute and even more, depending on the number of rooms and the number of users in them). Deleting cache files may help to fix problems such as missing avatars, rooms stuck in a wrong state etc.
124
-
125
132
## Troubleshooting
126
133
127
134
If `cmake` fails with...
@@ -146,10 +153,14 @@ CMake Error at CMakeLists.txt:30 (add_subdirectory):
146
153
147
154
If you have made sure that your toolchain is in order (versions of compilers and Qt are among supported ones, PATH is set correctly etc.) but building fails with strange Qt-related errors such as not found symbols or undefined references, double-check that you don't have Qt 4.x packages around ([here is a typical example](https://github.com/QMatrixClient/Quaternion/issues/185)). If you need those packages reinstalling them may help; but if you use Qt4 by default you have to explicitly pass Qt5 location to CMake (see notes about CMAKE_PREFIX_PATH in "Building").
148
155
156
+
If Quaternion starts displaying the message that it couldn't connect to the server and retries more than a couple of times without success, while you're sure you have the network connection - sorry but you might probably have to find an alternative network connection so far. Qt, even the newest one, has issues with losing connectivity on some WiFi networks (and not recovering from that), and libqmatrixclient doesn't have a workaround for this yet.
157
+
149
158
If Quaternion runs but you can't see any messages in the chat (though you can type them in) - you have a problem with Qt Quick. Most likely, you don't have Qt Quick libraries and/or plugins installed. On Linux, double check "Pre-requisites" above and also see the stdout/stderr logs, they are quite clear in such cases. On Windows and Mac, just open an issue (see "Contacts" in the beginning of this README), because most likely not all necessary Qt parts got copied along with Quaternion (which is a bug).
150
159
151
160
Especially on Windows, if Quaternion starts up but upon an attempt to connect returns a message like "Failed to make SSL context" - you haven't made sure that SSL libraries are reachable buy the Quaternion binary. See the "OpenSSL on Windows" section above for details.
152
161
162
+
If you have troubles with dynamic libraries on Windows, [the Dependencies Walker tool aka depends.exe](http://www.dependencywalker.com/) helps a lot in navigating the DLL hell - especially when you have a mixed 32/64-bit environment or have different versions of the same library scattered around. OpenSSL, in particular, is notoriously often dragged along by all kinds of software; and you may have other copies of Qt around which you didn't even know about - e.g., with CMake GUI.
163
+
153
164
When chasing bugs and investigating crashes, it helps to increase the debug level. Thanks to @eang:matrix.org, libqmatrixclient uses Qt logging categories - the "Troubleshooting" section of `lib/README.md` elaborates on how to setup logging. Note that Quaternion itself doesn't use Qt logging categories yet, only the library does.
0 commit comments