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
Whenever you want to update your Quaternion package, just run again the `build.sh` script and then use:
58
-
59
-
```
60
-
flatpak --user update
61
-
```
62
-
63
46
### Pre-requisites
64
47
- a Linux, MacOS or Windows system (desktop versions tried; mobile Linux/Windows might work too)
65
48
- For Ubuntu flavours - Trusty Tar or later (or a derivative) is good enough; older ones will need PPAs at least for a newer Qt
@@ -72,7 +55,7 @@ flatpak --user update
72
55
#### Linux
73
56
Just install things from the list above using your preferred package manager. If your Qt package base is fine-grained you might want to take a look at `CMakeLists.txt` to figure out which specific libraries Quaternion uses (or blindly run cmake and look at error messages). Note also that you'll need several Qt Quick plugins for Quaternion to work (without them, it will compile and run but won't show the messages timeline). In case of Trusty Tar the following line will get you everything necessary to build and run Quaternion (thanks to `@onlnr:matrix.org`):
On Fedora 26, the following command should be enough for building and running:
78
61
```
@@ -99,16 +82,46 @@ cmake --build . --target all
99
82
```
100
83
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).
101
84
102
-
### Running
103
-
Linux, MacOS: Just start the executable in your most preferred way.
104
-
105
-
Windows: the same but make sure that Qt5 dlls 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).
106
-
107
85
### Installation
108
86
In the root directory of the project sources: `cmake --build build_dir --target install`.
109
87
110
88
On Linux, `make install` (with `sudo` if needed) will work equally well.
111
89
90
+
### Flatpak
91
+
If you run Linux and your distribution supports flatpak, you can easily build and install Quaternion as a flatpak package:
Whenever you want to update your Quaternion package, do the following from the flatpak directory:
101
+
102
+
```
103
+
./build.sh
104
+
flatpak --user update
105
+
```
106
+
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
+
112
125
## Troubleshooting
113
126
114
127
If `cmake` fails with...
@@ -131,11 +144,13 @@ CMake Error at CMakeLists.txt:30 (add_subdirectory):
131
144
```
132
145
...then you don't have libqmatrixclient sources - most likely because you didn't do the `git submodule init && git submodule update` dance.
133
146
134
-
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" section in the beginning of this README), because most likely not all necessary Qt parts got copied along with Quaternion (which is a bug).
147
+
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
+
149
+
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).
135
150
136
151
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.
137
152
138
-
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.
153
+
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