New upstream version 0.7.0

1 files changed, 228 insertions, 63 deletions

diff --git a/README.md b/README.md
index cbb8d5f0..d9f50f0a 100644
--- a/README.md
+++ b/README.md
@@ -1,104 +1,269 @@
-# libQMatrixClient
+# libQuotient (former libQMatrixClient)
 
-[![license](https://img.shields.io/github/license/QMatrixClient/libqmatrixclient.svg)](https://github.com/QMatrixClient/libqmatrixclient/blob/master/COPYING)
+<a href='https://matrix.org'><img src='https://matrix.org/docs/projects/images/made-for-matrix.png' alt='Made for Matrix' height=64 target=_blank /></a>
+
+[![license](https://img.shields.io/github/license/quotient-im/libQuotient.svg)](https://github.com/quotient-im/libQuotient/blob/master/COPYING)
 ![status](https://img.shields.io/badge/status-beta-yellow.svg)
-[![release](https://img.shields.io/github/release/QMatrixClient/libqmatrixclient/all.svg)](https://github.com/QMatrixClient/libqmatrixclient/releases/latest)
-[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1023/badge)](https://bestpractices.coreinfrastructure.org/projects/1023)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
+[![release](https://img.shields.io/github/release/quotient-im/libQuotient/all.svg)](https://github.com/quotient-im/libQuotient/releases/latest)
+[![](https://img.shields.io/cii/percentage/1023.svg?label=CII%20best%20practices)](https://bestpractices.coreinfrastructure.org/projects/1023/badge)
+![](https://img.shields.io/github/commit-activity/y/quotient-im/libQuotient.svg)
+![CI Status](https://img.shields.io/github/workflow/status/quotient-im/libQuotient/CI)
+![Sonar Tech Debt](https://img.shields.io/sonar/tech_debt/quotient-im_libQuotient?server=https%3A%2F%2Fsonarcloud.io)
+![Sonar Coverage](https://img.shields.io/sonar/coverage/quotient-im_libQuotient?server=https%3A%2F%2Fsonarcloud.io)
+![Matrix](https://img.shields.io/matrix/quotient:matrix.org?logo=matrix)
 
-libQMatrixClient is a Qt5-based library to make IM clients for the [Matrix](https://matrix.org) protocol. It is the backbone of [Quaternion](https://github.com/QMatrixClient/Quaternion), [Tensor](https://matrix.org/docs/projects/client/tensor.html) and some other projects.
+The Quotient project aims to produce a Qt5-based SDK to develop applications
+for [Matrix](https://matrix.org). libQuotient is a library that enables client
+applications. It is the backbone of
+[Quaternion](https://github.com/quotient-im/Quaternion),
+[NeoChat](https://matrix.org/docs/projects/client/neo-chat) and other projects.
+Versions 0.5.x and older use the previous name - libQMatrixClient.
 
 ## Contacts
-You can find authors of libQMatrixClient in the Matrix room: [#qmatrixclient:matrix.org](https://matrix.to/#/#qmatrixclient:matrix.org).
-
-You can also file issues at [the project's issue tracker](https://github.com/QMatrixClient/libqmatrixclient/issues). If you have what looks like a security issue, please see respective instructions in CONTRIBUTING.md.
-
-## Building and usage
-So far the library is typically used as a git submodule of another project (such as Quaternion); however it can be built separately (either as a static or as a dynamic library). As of version 0.2, the library can be installed and CMake package config files are provided; projects can use `find_package(QMatrixClient)` to setup their code with the installed library files. PRs to enable the same for qmake are most welcome.
+You can find Quotient developers in the Matrix room:
+[#quotient:matrix.org](https://matrix.to/#/#quotient:matrix.org).
 
-The source code is hosted at GitHub: https://github.com/QMatrixClient/libqmatrixclient - checking out a certain commit or tag from GitHub (rather than downloading the archive) is the recommended way for one-off building. If you want to hack on the library as a part of another project (e.g. you are working on Quaternion but need to do some changes to the library code), you're advised to make a recursive check out of that project (in this case, Quaternion) and update the library submodule to its master branch.
+You can file issues at
+[the project issue tracker](https://github.com/quotient-im/libQuotient/issues).
+If you find what looks like a security issue, please use instructions
+in SECURITY.md.
 
-Tags starting with `v` represent released versions; `rc` mark release candidates.
+## Getting and using libQuotient
+Depending on your platform, the library can be obtained from a package
+management system. Recent releases of Fedora, Debian and openSUSE already have
+it. Alternatively, you can build the library from the source and bundle it with
+your application, as described below.
 
 ### Pre-requisites
-- a Linux, OSX or Windows system (desktop versions tried; Ubuntu Touch is known to work; mobile Windows and iOS might work too but never tried)
-  - For Ubuntu flavours - zesty or later (or a derivative) is good enough out of the box; older ones will need PPAs at least for a newer Qt; in particular, if you have xenial you're advised to add Kubuntu Backports PPA for it
-- a Git client to check out this repo
-- Qt 5 (either Open Source or Commercial), version 5.6 or higher
-- a build configuration tool:
-  - CMake (from your package management system or [the official website](https://cmake.org/download/))
-  - or qmake (comes with Qt)
-- 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))
-  - GCC 5 (Windows, Linux, OSX), Clang 5 (Linux), Apple Clang 8.1 (OSX) and Visual C++ 2015 (Windows) are the oldest officially supported; Clang 3.8 and GCC 4.9.2 are known to still work, maintenance patches for them are accepted
-  - any build system that works with CMake and/or qmake should be fine: GNU Make, ninja (any platform), NMake, jom (Windows) are known to work.
+- A recent Linux, macOS or Windows system (desktop versions are known to work;
+  mobile operating systems where Qt is available might work too)
+  - Recent enough Linux examples: Debian Bullseye; Fedora 35;
+    openSUSE Leap 15.4; Ubuntu 22.04 LTS.
+- Qt 5.15 or 6 (experimental, as of libQuotient 0.7) - either Open Source or
+  Commercial
+- CMake 3.16 or newer
+- A C++ toolchain that supports at least some subset of C++20 (concepts,
+  in particular):
+  - GCC 11 (Windows, Linux, macOS), Clang 11 (Linux), Apple Clang 12 (macOS)
+    and Visual Studio 2019 (Windows) are the oldest officially supported.
+- If using E2EE (beta, as of libQuotient 0.7):
+  - libolm 3.2.5 or newer (the latest 3.x strongly recommended)
+  - OpenSSL (1.1.x is known to work; 3.x should likely work too).
+- Any build system that works with CMake should be fine:
+  GNU Make and ninja on any platform, NMake and jom on Windows are known to work.
+  Ninja is recommended.
 
 #### 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 run cmake/qmake and look at error messages. The library is entirely offscreen (QtCore and QtNetwork are essential) but it also depends on QtGui in order to handle avatar thumbnails.
+Just install things from the list above using your preferred package manager.
+If your Qt package base is fine-grained you might want to run cmake and look
+at error messages. The library is entirely offscreen but aside from QtCore and
+QtNetwork it also depends on QtGui in order to handle avatar thumbnails.
 
-#### OS X
-`brew install qt5` should get you a recent Qt5. If you plan to use CMake, you may need to tell it about the path to Qt by passing `-DCMAKE_PREFIX_PATH=<where-Qt-installed>`
+#### macOS
+`brew install qt5` should get you a recent Qt5. You may need to add the output
+of `brew --prefix qt5` to `CMAKE_PREFIX_PATH` (see below) to make CMake aware
+of the Qt location.
+
+If using E2EE, you need to perform the same dance for libolm and openssl.
 
 #### Windows
-1. Install Qt5, using their official installer.
-1. If you plan to build with CMake, install CMake; if you're ok with qmake, you don't need to install anything on top of Qt. The commands in further sections imply that cmake/qmake is in your PATH - otherwise you have to prepend those commands with actual paths. As an option, it's a good idea 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 that script on system startup but it's very handy to setup the environment before building. For CMake, setting `CMAKE_PREFIX_PATH` in the same way as for OS X (see above), also helps.
+Install Qt5 using their official installer; make sure to tick the CMake box
+in the list of installed components unless you already have it installed.
 
-There are no official MinGW-based 64-bit packages for Qt. If you're determined to build a 64-bit library, either use a Visual Studio toolchain or build Qt5 yourself as described in Qt documentation.
+The commands in further sections imply that cmake is in your PATH, otherwise
+you have to prepend those commands with actual paths. It's a good idea to run
+a `qtenv2.bat` script that can be found in `C:\Qt\<Qt version>\<toolchain>\bin`
+(assuming you installed Qt to `C:\Qt`) if you're building from the command line;
+the script adds necessary paths to PATH. You might not want to run that script
+on system startup but it's very handy to setup the environment before building.
+Alternatively you can add the Qt path to `CMAKE_PREFIX_PATH` and leave PATH
+unchanged.
 
-### Building
-#### CMake-based
-In the root directory of the project sources:
-```
+If you're trying out E2EE, you will also need libolm and OpenSSL. Unfortunately,
+neither project provides official binary libraries for Windows. libolm can
+be compiled from the sources (available at ) using the same toolchain
+(CMake+MSVC). It's not recommended to compile OpenSSL yourself; instead, use
+one of the "OpenSSL for Windows" links in
+[unofficial list on the project Wiki](https://wiki.openssl.org/index.php/Binaries).
+
+
+### Using the library
+If you're just starting a project using libQuotient from scratch, you can copy
+`quotest/CMakeLists.txt` to your project and change `quotest` to your
+project name. If you already have an existing CMakeLists.txt, you need to insert
+a `find_package(Quotient REQUIRED)` line to an appropriate place in it (use
+`find_package(Quotient)` if libQuotient is not a hard dependency for you) and
+then add `Quotient` to your `target_link_libraries()` line.
+
+Building with dynamic linkage is only tested on Linux at the moment and is
+a recommended way of linking your application with libQuotient on this platform.
+Static linkage is the default on Windows/macOS; feel free to experiment
+with dynamic linking and submit PRs if you get reusable results.
+
+As for the actual API usage, a (very basic) overview can be found at
+[the respective wiki page](https://github.com/quotient-im/libQuotient/wiki/libQuotient-overview).
+Beyond that, looking at [Quotest](quotest) - the test application that comes
+with libQuotient - may help you with most common use cases such as sending
+messages, uploading files, setting room state etc. For more extensive usage
+feel free to check out (and copy, with appropriate attribution) the source code
+of [Quaternion](https://github.com/quotient-im/Quaternion) (the reference client
+for libQuotient) or [NeoChat](https://invent.kde.org/network/neochat).
+
+## Building the library
+[The source code is at GitHub](https://github.com/quotient-im/libQuotient).
+Checking out a certain commit or tag (rather than downloading the archive)
+along with submodules is strongly recommended. If you want to hack on
+the library as a part of another project (e.g. you are working on Quaternion
+but need to do some changes to the library code), it makes sense
+to make a recursive check out of that project (in this case, Quaternion)
+and update the library submodule (also recursively) within the appropriate
+branch. Be mindful of API compatibility restrictions: e.g., Quaternion 0.0.95
+will not build with the master branch of libQuotient.
+
+Tags consisting of digits and periods represent released versions; tags ending
+with `-betaN` or `-rcN` mark pre-releases. If/when packaging pre-releases,
+it is advised to replace a dash with a tilde.
+
+The following commands issued in the root directory of the project sources:
+```shell script
 mkdir build_dir
 cd build_dir
-cmake .. # Pass -DCMAKE_PREFIX_PATH and -DCMAKE_INSTALL_PREFIX here if needed
+cmake .. # [-D<cmake-variable>=<value>...], see below
 cmake --build . --target all
 ```
-This will get you the compiled library in `build_dir` inside your project sources. Static builds are tested on all supported platforms. Dynamic builds of libqmatrixclient are only tested on Linux at the moment; experiments with dynamic builds on Windows/OSX are welcome. Taking a look at [qmc-example](https://github.com/QMatrixClient/libqmatrixclient/tree/master/examples) (used to test the library) should give you a basic idea of using libQMatrixClient; for more extensive usage check out the source code of [Quaternion](https://github.com/QMatrixClient/Quaternion) (the reference client built on QMatrixClient).
+will get you a compiled library in `build_dir` inside your project sources.
+Static builds are tested on all supported platforms, building the library as
+a shared object (aka dynamic library) is supported on Linux and macOS but is
+very likely to be broken on Windows.
+
+Before proceeding, double-check that you have installed development libraries
+for all prerequisites above. CMake will stop and tell you if something's missing.
+
+The first CMake invocation above configures the build. You can pass CMake
+variables (such as `-DCMAKE_PREFIX_PATH="path1;path2;..."` and
+`-DCMAKE_INSTALL_PREFIX=path`) here if needed.
+[CMake documentation](https://cmake.org/cmake/help/latest/index.html)
+(pick the CMake version at the top of the page that you use) describes
+the standard variables coming with CMake. On top of them, Quotient introduces:
+- `Quotient_INSTALL_TESTS=<ON/OFF>`, `ON` by default - install `quotest` along
+  with the library files when `install` target is invoked. `quotest` is a small
+  command-line program that (assuming correct parameters, see `quotest --help`)
+  that tries to connect to a given room as a given user and perform some basic
+  Matrix operations, such as sending messages and small files, redaction,
+  setting room tags etc. This is useful to check the sanity of your library
+  installation. As of now, `quotest` expects the used homeserver to be able
+  to get the contents of `#quotient:matrix.org`; this is being fixed in
+  [#401](https://github.com/quotient-im/libQuotient/issues/401).
+- `Quotient_ENABLE_E2EE=<ON/OFF>`, `OFF` by default - enable work-in-progress
+  E2EE code in the library. As of 0.6, this code is very incomplete and buggy;
+  you should NEVER use it. In 0.7, the enabled code is beta-quality and is
+  generally good for trying the technology and API but really not for
+  mission-critical applications.
+
+  Switching this on will define `Quotient_E2EE_ENABLED` macro (note
+  the difference from the CMake switch) for compiler invocations on all
+  Quotient and Quotient-dependent (if it uses `find_package(Quotient)`)
+  code; so you can use `#ifdef Quotient_E2EE_ENABLED` to guard the code using
+  E2EE parts of Quotient.
+- `MATRIX_SPEC_PATH` and `GTAD_PATH` - these two variables are used to point
+  CMake to the directory with the matrix-doc repository containing API files
+  and to a GTAD binary. These two are used to generate C++ files from Matrix
+  Client-Server API description made in OpenAPI notation. This is not needed
+  if you just need to build the library; if you're really into hacking on it,
+  CONTRIBUTING.md elaborates on what these two variables are for.
 
 You can install the library with CMake:
-```
+```shell script
 cmake --build . --target install
 ```
-This will also install cmake package config files; once this is done, you can use `examples/CMakeLists.txt` to compile the example with the _installed_ library. This file is a good starting point for your own CMake-based project using libQMatrixClient.
-
-#### qmake-based
-The library provides a .pri file with an intention to be included from a bigger project's .pro file. As a starting point you can use `qmc-example.pro` that will build a minimal example of library usage for you. In the root directory of the project sources:
-```
-qmake qmc-example.pro
-make all
-```
-This will get you `debug/qmc-example` and `release/qmc-example` console executables that login to the Matrix server at matrix.org with credentials of your choosing (pass the username and password as arguments), run a sync long-polling loop and do some tests of the library API.
-
-Installing the library with qmake is not possible; similarly, a .prl file is not provided. A PR to fix this is welcome.
+This will also install cmake package config files; once this is done, you
+should be able to use [`quotest/CMakeLists.txt`](quotest/CMakeLists.txt) to compile quotest
+with the _installed_ library. Installation of the `quotest` binary
+along with the rest of the library can be skipped
+by setting `Quotient_INSTALL_TESTS` to `OFF`.
 
 ## Troubleshooting
 
 #### Building fails
 
-If `cmake` fails with...
-```
-CMake Warning at CMakeLists.txt:11 (find_package):
-  By not providing "FindQt5Widgets.cmake" in CMAKE_MODULE_PATH this project
-  has asked CMake to find a package configuration file provided by
-  "Qt5Widgets", but CMake did not find one.
-```
-...then you need to set the right `-DCMAKE_PREFIX_PATH` variable, see above.
+- If `cmake` fails with
+  ```
+  CMake Warning at CMakeLists.txt:11 (find_package):
+    By not providing "FindQt5Widgets.cmake" in CMAKE_MODULE_PATH this project
+    has asked CMake to find a package configuration file provided by
+    "Qt5Widgets", but CMake did not find one.
+  ```
+  then you need to set the right `-DCMAKE_PREFIX_PATH` variable, see above.
+  
+- If `cmake` fails with a message similar to:
+  ```
+  CMake Error at /usr/lib64/cmake/Qt6Core/Qt6CoreVersionlessTargets.cmake:37 (message):
+    Some (but not all) targets in this export set were already defined.
+  
+    Targets Defined: Qt::Core
+  
+    Targets not yet defined: Qt::CorePrivate
+  ```
+  then you likely have both Qt 5 and Qt 6 on your system, and your client code
+  uses a different major version than Quotient. Make sure you use the client
+  version that matches libQuotient (e.g. you can't configure Quaternion 0.0.95
+  with libQuotient 0.7 in Qt 6 mode).
+
+- If you use GCC and get an "unknown declarator" compilation error in the file
+`qtconcurrentthreadengine.h` - unfortunately, it is an actual error in Qt 5.15
+sources, see https://bugreports.qt.io/browse/QTBUG-90568 (or
+https://bugreports.qt.io/browse/QTBUG-91909). The Qt company did not make
+an open source release with the fix, therefore:
+
+  - if you're on Linux - try to use Qt from your package management system, as
+    most likely this bug is already fixed in the packages
+  - if you're on Windows, or if you have to use Qt (5.15) from download.qt.io
+    for any other reason, you should apply the fix to Qt sources: locate
+    the file (the GCC error message tells exactly where it is), find the line
+    with the (strange-looking) `ThreadEngineStarter` constructor definition:
+    ```cplusplus
+    ThreadEngineStarter<void>(ThreadEngine<void> \*_threadEngine)
+    ```
+    and remove the template specialisation from the constructor name so that it
+    looks like
+    ```cplusplus
+    ThreadEngineStarter(ThreadEngine<void> \*_threadEngine)
+    ```
+    This will fix your build (and any other build involving QtConcurrent from
+    this installation of Qt - the fix is not specific to Quotient in any way).
 
 #### Logging configuration
 
-libqmatrixclient uses Qt's logging categories to make switching certain types of logging easier. In case of troubles at runtime (bugs, crashes) you can increase logging if you add the following to the `QT_LOGGING_RULES` environment variable:
+libQuotient uses Qt's logging categories to make switching certain types of logging easier. In case of troubles at runtime (bugs, crashes) you can increase logging if you add the following to the `QT_LOGGING_RULES` environment variable:
 ```
-libqmatrixclient.<category>.<level>=<flag>
+quotient.<category>.<level>=<flag>
 ```
 where
-- `<category>` is one of: `main`, `jobs`, `jobs.sync`, `events`, `events.ephemeral`, and `profiler` (you can always find the full list in the file `logging.cpp`)
-- `<level>` is one of `debug` and `warning`
+- `<category>` is one of: `main`, `jobs`, `jobs.sync`, `jobs.thumbnail`,
+  `events`, `events.state` (covering both the "usual" room state and account
+  data), `events.messages`, `events.ephemeral`, `e2ee` and `profiler` (you can
+  always find the full list in `lib/logging.cpp`);
+- `<level>` is one of `debug`, `info`, and `warning`;
 - `<flag>` is either `true` or `false`.
 
-`*` can be used as a wildcard for any part between two dots, and comma is used for a separator. Latter statements override former ones, so if you want to switch on all debug logs except `jobs` you can set
+`*` can be used as a wildcard for any part between two dots, and semicolon is used for a separator. Latter statements override former ones, so if you want to switch on all debug logs except `jobs` you can set
+```shell script
+QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"
 ```
-QT_LOGGING_RULES="libqmatrixclient.*.debug=true,libqmatrixclient.jobs.debug=false"
+Note that `quotient` is a prefix that only works since version 0.6 of
+the library; 0.5.x and older used `libqmatrixclient` instead. If you happen
+to deal with both libQMatrixClient-era and Quotient-era versions,
+it's reasonable to use both prefixes, to make sure you're covered with no
+regard to the library version. For example, the above setting could look like
+```shell script
+QT_LOGGING_RULES="libqmatrixclient.*.debug=true;libqmatrixclient.jobs.debug=false;quotient.*.debug=true;quotient.jobs.debug=false"
 ```
 
 #### Cache format
-In case of troubles with room state and caching it may be useful to switch cache format from binary to JSON. To do that, set the following value in your client's configuration file/registry key (you might need to create the libqmatrixclient key for that): `libqmatrixclient/cache_type` to `json`. This will make cache saving and loading work slightly slower but the cache will be in a text JSON file (very long and unindented so prepare a good JSON viewer or text editor with JSON formatting capabilities).
+In case of troubles with room state and caching it may be useful to switch
+cache format from binary to JSON. To do that, set the following value in
+your client's configuration file/registry key (you might need to create
+the libQuotient key for that): `libQuotient/cache_type` to `json`.
+This will make cache saving and loading work slightly slower but the cache
+will be in text JSON files (possibly very long and unindented so prepare a good
+JSON viewer or text editor with JSON formatting capabilities).