From e18eb4554e938e7341afac999464f22656159fb3 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sat, 2 Nov 2024 21:37:24 +0100 Subject: [PATCH] Update the documentation --- BUILDING.md | 39 +++++++++++++-------------------------- README.md | 46 +++++++++++++--------------------------------- SECURITY.md | 14 ++++++-------- 3 files changed, 32 insertions(+), 67 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index c5b40f5c..05ea5501 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -64,18 +64,17 @@ using the old name.) platforms might work too but never tried) - Recent enough Linux examples: Debian Bookworm; Fedora 36 or CentOS Stream 9; OpenSUSE Leap 15.4; Ubuntu Jammy Jellyfish. -- Qt 5 (either Open Source or Commercial), version 5.15.x or newer (Qt 6.6 - recommended as of this writing) +- Qt 6.4 or newer (either Open Source or Commercial) - CMake 3.16 or newer (from your package management system or [the official website](https://cmake.org/download/)) -- A C++ toolchain with C++20 support: - - GCC 11 (Windows, Linux, macOS), Clang 11 (Linux), Apple Clang 12 (macOS) - and Visual Studio 2019 (Windows) are the oldest officially supported. +- A C++ toolchain with solid C++20 support and elements of C++23: + - GCC 13 (Windows, Linux, macOS), Clang 16 (Linux), Apple Clang 15 (macOS) + and Visual Studio 2022 (Windows) are the oldest officially supported. - Any build system that works with CMake should be fine: GNU Make, ninja (any platform), NMake, jom (Windows) are known to work. -- optionally, libQuotient 0.8.x development files (from your package management +- optionally, libQuotient 0.9.x development files (from your package management system), or prebuilt libQuotient (see "Getting the source code" above); - libQuotient 0.7.x is _not_ compatible with Quaternion 0.0.96 beta 2 and later. + libQuotient 0.8.x is _not_ compatible with any Quaternion 0.0.97 release. - libQuotient dependendencies (see lib/README.md): - [Qt Keychain](https://github.com/frankosterfeld/qtkeychain) - libolm 3.2.5 or newer (the latest 3.x strongly recommended) @@ -83,13 +82,6 @@ using the old name.) the version used to build Quaternion - or libQuotient, if libQuotient is built/installed separately). -Note that in case of using externally built (i.e. not in-tree) libQuotient -you cannot choose whether or not E2EE is enabled; this is defined by your -libQuotient build configuration. Since 0.8, it is strongly recommended to build -libQuotient with E2EE switched on, and manage E2EE via the library API (which -Quaternion already does). If you build libQuotient from within Quaternion build -process then you're in full control how libQuotient is built. - #### Linux 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 @@ -101,18 +93,12 @@ and run but won't show the messages timeline). On Debian/Ubuntu, the following line should get you everything necessary to build and run Quaternion: ```bash -# With Qt 5 -sudo apt-get install cmake qtdeclarative5-dev qttools5-dev qml-module-qtquick-controls2 qtquickcontrols2-5-dev qtmultimedia5-dev qt5keychain-dev libolm-dev libssl-dev -# With Qt 6 -sudo apt-get install cmake libgl1-mesa-dev qt6-declarative-dev qt6-tools-dev qt6-tools-dev-tools qt6-l10n-tools qml6-module-qtquick-controls qt6-multimedia-dev qtkeychain-qt6-dev libolm-dev libssl-dev +sudo apt-get install cmake qt6-declarative-dev qt6-base-private-dev qt6-tools-dev qt6-tools-dev-tools qt6-l10n-tools qml6-module-qtquick-controls qt6-multimedia-dev qtkeychain-qt6-dev libolm-dev libssl-dev ``` On Fedora, the following command should be enough for building and running: ```bash -# With Qt 5 -sudo dnf install cmake qt5-qtdeclarative-devel qt5-qtmultimedia-devel qt5-qtquickcontrols2-devel qt5-linguist qtkeychain-qt5-devel libolm-devel openssl-devel -# With Qt 6 -sudo dnf install cmake qt6-qtdeclarative-devel qt6-qtmultimedia-devel qt6-qttools-devel qtkeychain-qt6-devel libolm-devel openssl-devel +sudo dnf install cmake qt6-qtdeclarative-devel qt6-qtbase-private-devel qt6-qtmultimedia-devel qt6-qttools-devel qtkeychain-qt6-devel libolm-devel openssl-devel ``` #### macOS @@ -159,9 +145,6 @@ Noteworthy CMake variables that you can use: (see below on installing from sources). - `-DUSE_INTREE_LIBQMC=` - force using/not-using the in-tree copy of libQuotient sources (see "Getting the source code" above). -- `-DBUILD_WITH_QT6=` - selects the target Qt major version. By default - it's `ON` (Qt 6 is preferred); set it to `OFF` to build with Qt 5 (which is - generally discouraged; Quaternion 0.0.96 is the last release to support it). ### Install In the root directory of the project sources: `cmake --build build_dir --target install`. @@ -177,7 +160,7 @@ git clone https://github.com/quotient-im/Quaternion.git --recursive cd Quaternion/flatpak ./setup_runtime.sh ./build.sh -flatpak --user install quaternion-nightly com.github.quaternion +flatpak --user install quaternion-nightly io.github.quotient_im.Quaternion ``` Whenever you want to update your Quaternion package, do the following from the flatpak directory: @@ -186,6 +169,10 @@ Whenever you want to update your Quaternion package, do the following from the f flatpak --user update ``` +Be mindful that since Quaternion 0.0.97 beta the Flatpak app-id has changed (it used to be +`com.github.quaternion`). Normally, Flatpak should seamlessly handle an upgrade; if it doesn't, +send us an issue. + ## Troubleshooting If `cmake` fails with... diff --git a/README.md b/README.md index 3cef0a02..582da19d 100644 --- a/README.md +++ b/README.md @@ -36,18 +36,21 @@ The source code is [hosted at GitHub](https://github.com/quotient-im/Quaternion) ### Requirements -Quaternion 0.0.96 needs Qt version 6.2 or higher, with 5.15 -provided as interim for compatibility (6.0, 6.1 are not supported). +Quaternion 0.0.97 needs Qt version 6.4 or higher. ### Linux Quaternion is packaged for many distributions, including various versions of Debian, Ubuntu and OpenSUSE, as well as Arch Linux, NixOS and FreeBSD. A pretty comprehensive list can be found at [Repology](https://repology.org/project/quaternion/versions). Popular -distributions satisfying the mentioned Qt requirement are Debian 11 (Bullseye), -Ubuntu 22.04 (jammy), Fedora 35, OpenSUSE Leap 15.4, anything newer than that +distributions satisfying the mentioned Qt requirement are Debian 12 (Bookworm), +Ubuntu 24.04 (noble), Fedora 39, OpenSUSE Leap 15.6; anything newer than that should be fine, too. +On top of the Quaternion package, you should not normally need to install anything in addition; +if something is not working due to a missing dependency, it's a bug in the package - please +report it to your distribution's Quaternion packager, _not_ to this repository. + There are also flatpaks for Quaternion available from Flathub. To install, use: ``` @@ -59,21 +62,6 @@ any distribution that has Flatpak - even if it's older than mentioned above. Please file issues at https://github.com/flathub/com.github.quaternion if you believe there's a problem specific to the Flatpak package of Quaternion. - - -You should not normally need to install anything in addition; if something -is not working due to a missing dependency, it's a bug - please report it. - ### Windows Since there's no established package management on Windows to resolve dependencies, all needed libraries and a C++ runtime are packaged/installed @@ -101,7 +89,7 @@ continuous integration (CI) in the A few important notes on these packages in case you're new to them: - All of them come bundled with fairly recent (not necessarily latest) Qt 6. - They are only provided for testing; feedback on _any_ release is welcome - as long as you know which build you run; but do not expect the developers + as long as you know which build you run, but do not expect the developers to address issues in any but the latest snapshot. - In case it's still unclear: these builds are UNSTABLE by default; some may not run at all, and if they do, they may ~~tell you obscenities in your @@ -110,13 +98,11 @@ A few important notes on these packages in case you're new to them: including Element ones, and generally corrupt your account in ways unexpected and hard to fix (all of that actually happened in the past). Do NOT run these builds if you're not prepared to deal with the problems. -- If you understand the above, have your backups in order and are still willing - to try things out or just generally help with the project - make sure to - `/join #quotient:matrix.org` and have the URL you downloaded Quaternion from - handy. In case of trouble, ~~show this label to your doctor~~ send the URL - to the binary you used in the chat room (you may need to use another client - or Quaternion version for that), describe what happened and we'll try to pull - you out of it. +- If you understand the above, have your backups in order and are still willing to try things out + or just generally help with the project - make sure to `/join #quotient:matrix.org` and have + the URL you downloaded Quaternion from. In case of trouble, ~~show this label to your doctor~~ + send the URL to the binary you used in the chat room (you may need to use another client or + Quaternion version for that), describe what happened and we'll try to pull you out of it. If you want to build Quaternion from sources, see [BUILDING.md](./BUILDING.md). @@ -308,12 +294,6 @@ Quaternion uses libQuotient under the hood; some Quaternion problems are actually problems of libQuotient. If you haven't found your case below, check also the troubleshooting section in libQuotient README.md. -#### No E2EE support -If you don't see "Enable E2EE (BETA)" box in the login window, it means that -your Quaternion build does not support E2EE at all. Work with the packager if -you use a package, or build Quaternion with E2EE support (see -[BUILDING.md](./BUILDING.md)) to make it possible. - #### Older messages don't get decrypted in E2EE rooms Unfortunately, this is a limitation in the current libQuotient code: it doesn't request older keys and therefore cannot decrypt older messages. Check diff --git a/SECURITY.md b/SECURITY.md index b45e2041..b07099a4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,14 +2,12 @@ ## Supported Versions -Only the latest released version of Quaternion is supported with security -updates. Also, an effort is put into supporting the latest released version -on most recent stable releases of each major Linux distribution (Debian, -Ubuntu, Fedora, OpenSuse). Users of older Quaternion versions are strongly -advised to upgrade to the latest release - support of those versions is very -limited, if provided at all. If you can't do it because your Linux distribution -is too old, you likely have other security problems as well; -upgrade your Linux distribution! +Only the latest stable (i.e. not beta) version of Quaternion is supported with security updates. +Also, an effort is put into supporting the version on most recent stable releases of each major +Linux distribution (Debian, Ubuntu, Fedora, OpenSuse). Users of older Quaternion versions are +strongly advised to upgrade to the latest release - support of those versions is very limited, +if provided at all. If you can't do it because your Linux distribution is too old, you likely +have other security problems as well; upgrade your Linux distribution! ## Reporting a Vulnerability