From 163f0acb78b62eeb5ca75ead2fa0beba816fb68a Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Sun, 16 Dec 2018 17:00:15 +0000 Subject: fix macOS installation instructions --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index cbb8d5f0..72eaf7ab 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ The source code is hosted at GitHub: https://github.com/QMatrixClient/libqmatrix Tags starting with `v` represent released versions; `rc` mark release candidates. ### 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) +- a Linux, macOS 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 @@ -29,18 +29,18 @@ Tags starting with `v` represent released versions; `rc` mark release candidates - 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 + - GCC 5 (Windows, Linux, macOS), Clang 5 (Linux), Apple Clang 8.1 (macOS) 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. #### 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. -#### 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=` +#### macOS +`brew install qt5` should get you a recent Qt5. If you plan to use CMake, you will need to tell it about the path to Qt by passing `-DCMAKE_PREFIX_PATH=$(brew --prefix qt5)` #### 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\\\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. +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\\\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 macOS (see above), also helps. 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. @@ -53,7 +53,7 @@ cd build_dir cmake .. # Pass -DCMAKE_PREFIX_PATH and -DCMAKE_INSTALL_PREFIX here if needed 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). +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/macOS 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). You can install the library with CMake: ``` -- cgit v1.2.3 From 0a09894add1c155279bfe5362d3a676f616b4530 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 6 Jan 2019 18:39:59 +0900 Subject: README.md: add/update badges --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 72eaf7ab..e4303a27 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,15 @@ # libQMatrixClient +Made for Matrix + [![license](https://img.shields.io/github/license/QMatrixClient/libqmatrixclient.svg)](https://github.com/QMatrixClient/libqmatrixclient/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) +[![](https://img.shields.io/cii/percentage/1023.svg)](https://bestpractices.coreinfrastructure.org/projects/1023/badge) +![](https://img.shields.io/github/commit-activity/y/QMatrixClient/libQMatrixClient.svg) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) -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. +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), [Spectral](https://matrix.org/docs/projects/client/spectral.html) and some other projects. ## Contacts You can find authors of libQMatrixClient in the Matrix room: [#qmatrixclient:matrix.org](https://matrix.to/#/#qmatrixclient:matrix.org). -- cgit v1.2.3 From de292f1537863846c9bb43de65a3c1ef4f37d18d Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 6 Jan 2019 19:41:42 +0900 Subject: README.md: make the CII badge a bit more prominent [skip ci] --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index e4303a27..58be072e 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![license](https://img.shields.io/github/license/QMatrixClient/libqmatrixclient.svg)](https://github.com/QMatrixClient/libqmatrixclient/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) -[![](https://img.shields.io/cii/percentage/1023.svg)](https://bestpractices.coreinfrastructure.org/projects/1023/badge) +[![](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/QMatrixClient/libQMatrixClient.svg) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) -- cgit v1.2.3 From 5d570825262a0ac0f78deedbd393c5d258493dc2 Mon Sep 17 00:00:00 2001 From: qso Date: Sun, 6 Jan 2019 23:28:48 +0100 Subject: added info for QMATRIXCLIENT_INSTALL_EXAMPLE option to README --- README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'README.md') diff --git a/README.md b/README.md index 72eaf7ab..be63c994 100644 --- a/README.md +++ b/README.md @@ -60,6 +60,7 @@ You can install the library with CMake: 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. +Installation of `qmc-example` application can be skipped by setting `QMATRIXCLIENT_INSTALL_EXAMPLE` to `OFF`. #### 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: -- cgit v1.2.3 From e7a549d3d7341f66cb84761da9783f39276da116 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Tue, 26 Feb 2019 20:31:19 +0900 Subject: README.md: update versioning convention for pre-releases --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index a0332bef..f885937c 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ So far the library is typically used as a git submodule of another project (such 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. -Tags starting with `v` represent released versions; `rc` mark release candidates. +Tags consisting of digits and periods represent released versions; tags ending with `~betaN` or `~rcN` mark pre-releases. ### Pre-requisites - a Linux, macOS or Windows system (desktop versions tried; Ubuntu Touch is known to work; mobile Windows and iOS might work too but never tried) -- cgit v1.2.3 From e0a0542a812937b189f2adc7da9f2c9bba2d89b1 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Tue, 26 Feb 2019 20:56:05 +0900 Subject: README.md: use dash instead of tilde in pre-releases [skip ci] --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index f885937c..ab275a35 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ So far the library is typically used as a git submodule of another project (such 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. -Tags consisting of digits and periods represent released versions; tags ending with `~betaN` or `~rcN` mark pre-releases. +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. ### Pre-requisites - a Linux, macOS or Windows system (desktop versions tried; Ubuntu Touch is known to work; mobile Windows and iOS might work too but never tried) -- cgit v1.2.3 From a10a06052aa3f85f937844cb72f8775712e4299b Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Thu, 4 Apr 2019 21:29:57 +0900 Subject: Update README.md and CONTRIBUTING.md (attn: LGPL v3 coming) [skip ci] --- README.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index ab275a35..857543e1 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,19 @@ You can find authors of libQMatrixClient in the Matrix room: [#qmatrixclient:mat 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. - -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. +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). After installing the library the CMake package becomes +available for `find_package(QMatrixClient)` to setup the client code with +the installed library files. PRs to enable the same for qmake are most welcome. + +[The source code is hosted at GitHub](https://github.com/QMatrixClient/libqmatrixclient) - +checking out a certain commit or tag (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. 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. @@ -28,6 +38,7 @@ Tags consisting of digits and periods represent released versions; tags ending w - 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 + (5.9 or higher is strongly recommended) - a build configuration tool: - CMake (from your package management system or [the official website](https://cmake.org/download/)) - or qmake (comes with Qt) -- cgit v1.2.3 From 4fdc2af2505da55d384be7d312540d1cbd79aaf8 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sat, 25 May 2019 20:33:53 +0900 Subject: Refer to SECURITY.md from the rest of documentation [skip ci] --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 857543e1..787fa0df 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,13 @@ 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), [Spectral](https://matrix.org/docs/projects/client/spectral.html) and some other projects. ## Contacts -You can find authors of libQMatrixClient in the Matrix room: [#qmatrixclient:matrix.org](https://matrix.to/#/#qmatrixclient:matrix.org). +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. +You can also file issues at +[the project's issue tracker](https://github.com/QMatrixClient/libqmatrixclient/issues). +If you find what looks like a security issue, please use instructions +in SECURITY.md. ## Building and usage So far the library is typically used as a git submodule of another project -- cgit v1.2.3 From 3d2b359b6766c008ba28f16737a9faee79043d07 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 7 Jul 2019 16:48:27 +0900 Subject: Documentation: libQMatrixClient -> libQuotient, QMatrixClient -> quotient-im, etc. --- README.md | 161 +++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 108 insertions(+), 53 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 787fa0df..5568101b 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,57 @@ -# libQMatrixClient +# libQuotient (former libQMatrixClient) Made for Matrix -[![license](https://img.shields.io/github/license/QMatrixClient/libqmatrixclient.svg)](https://github.com/QMatrixClient/libqmatrixclient/blob/master/COPYING) +[![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) +[![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/QMatrixClient/libQMatrixClient.svg) +![](https://img.shields.io/github/commit-activity/y/quotient-im/libQuotient.svg) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) -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), [Spectral](https://matrix.org/docs/projects/client/spectral.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), +[Spectral](https://matrix.org/docs/projects/client/spectral.html) 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 find Quotient developers in the Matrix room: +[#quotient:matrix.org](https://matrix.to/#/#quotient:matrix.org). -You can also file issues at -[the project's issue tracker](https://github.com/QMatrixClient/libqmatrixclient/issues). +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. -## 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). After installing the library the CMake package becomes -available for `find_package(QMatrixClient)` to setup the client code with -the installed library files. PRs to enable the same for qmake are most welcome. - -[The source code is hosted at GitHub](https://github.com/QMatrixClient/libqmatrixclient) - -checking out a certain commit or tag (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. - -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. +## Getting and using libQuotient +Depending on your platform, the library can come as a separate package. +Recent releases of Debian and OpenSuSE, e.g., already have the package +(under the old name). If your Linux repo doesn't provide binary package +(either libqmatrixclient - older - or libquotient - newer), or you're +on Windows or macOS, your best bet is to build the library from the source +and bundle it with your application. In ### Pre-requisites -- a Linux, macOS 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 - (5.9 or higher is strongly recommended) -- a build configuration tool: - - CMake (from your package management system or [the official website](https://cmake.org/download/)) +- A Linux, macOS 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 is good enough out of the box; + older ones will need PPAs at least for a newer Qt. In particular, + if you (still) have xenial and cannot upgrade to a newer release + you'll have to add Kubuntu Backports PPA for it. +- Qt 5 (either Open Source or Commercial), 5.9 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, macOS), Clang 5 (Linux), Apple Clang 8.1 (macOS) 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 C++ toolchain with C++14 support + - GCC 5 (Windows, Linux, macOS), Clang 5 (Linux), Apple Clang 8.1 (macOS) + and Visual Studio 2017 (Windows) are the oldest officially supported; + Clang 3.8, GCC 4.9.2, VS 2015 may work but not actively maintained. +- 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. #### 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. @@ -60,35 +63,73 @@ Just install things from the list above using your preferred package manager. If 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\\\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 macOS (see above), also helps. -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. - -### Building -#### CMake-based +### Using the library +If you use CMake, `find_package(Quotient)` sets up the client code to use +libQuotient, assuming the library development files are installed. There's no +documented procedure to use a preinstalled library with qmake; consider +introducing a submodule in your source tree and build it along with the rest +of the application for now. Patches to provide .prl files for qmake +are welcome. + +Building with dynamic linkage are only tested on Linux at the moment and are +a recommended way of linking your application with libQuotient on this platform. +Feel free +Static linkage is the default on Windows/macOS; feel free to experiment +with dynamic linking and submit PRs if you get reusable results. + +The example/test application that comes with libQuotient, +[qmc-example](https://github.com/quotient-im/libQuotient/tree/master/examples) +includes most common use cases such as sending messages, uploading files, +setting room state etc.; for more extensive usage check out the source code +of [Quaternion](https://github.com/quotient-im/Quaternion) +(the reference client of Quotient) or [Spectral](https://gitlab.com/b0/spectral). + +To ease the first step, `examples/CMakeLists.txt` is a good starting point +for your own CMake-based project using libQuotient. + +## 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) to its master branch. + +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. + +### CMake-based 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 --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/macOS 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). +This will get you the compiled library in `build_dir` inside your project +sources. Static builds are tested on all supported platforms. 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. -Installation of `qmc-example` application can be skipped by setting `QMATRIXCLIENT_INSTALL_EXAMPLE` to `OFF`. +This will also install cmake package config files; once this is done, you +should be able to use `examples/CMakeLists.txt` to compile qmc-example +with the _installed_ library. Installation of the `qmc-example` binary +along with the rest of the library can be skipped +by setting `QMATRIXCLIENT_INSTALL_EXAMPLE` to `OFF`. -#### qmake-based +### 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: -``` +```shell script 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. +Installing the standalone library with qmake is not implemented yet. ## Troubleshooting @@ -105,19 +146,33 @@ CMake Warning at CMakeLists.txt:11 (find_package): #### 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..= +quotient..= ``` where -- `` is one of: `main`, `jobs`, `jobs.sync`, `events`, `events.ephemeral`, and `profiler` (you can always find the full list in the file `logging.cpp`) +- `` is one of: `main`, `jobs`, `jobs.sync`, `events`, `events.ephemeral`, and `profiler` (you can always find the full list in the file `lib/logging.cpp`) - `` is one of `debug` and `warning` - `` 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 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). -- cgit v1.2.3 From b0f259c3aa4ca619a6998184d16f9ab2daf5b5f4 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 4 Aug 2019 09:31:36 +0900 Subject: Updated documentation; bumped up requirements [skip ci] --- README.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 5568101b..cb78dfe0 100644 --- a/README.md +++ b/README.md @@ -35,21 +35,18 @@ on Windows or macOS, your best bet is to build the library from the source and bundle it with your application. In ### Pre-requisites -- A Linux, macOS or Windows system (desktop versions tried; Ubuntu Touch +- A recent Linux, macOS 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 is good enough out of the box; - older ones will need PPAs at least for a newer Qt. In particular, - if you (still) have xenial and cannot upgrade to a newer release - you'll have to add Kubuntu Backports PPA for it. + - Recent enough Linux examples: Debian Jessy; Fedora 28; OpenSUSE 15; + Ubuntu Bionic. - Qt 5 (either Open Source or Commercial), 5.9 or higher. - A build configuration tool: - - CMake (from your package management system or + - CMake 3.5 or newer (from your package management system or [the official website](https://cmake.org/download/)) - or qmake (comes with Qt) -- A C++ toolchain with C++14 support - - GCC 5 (Windows, Linux, macOS), Clang 5 (Linux), Apple Clang 8.1 (macOS) - and Visual Studio 2017 (Windows) are the oldest officially supported; - Clang 3.8, GCC 4.9.2, VS 2015 may work but not actively maintained. +- A C++ toolchain with C++14 support: + - GCC 7 (Windows, Linux, macOS), Clang 6 (Linux), Apple Clang 10 (macOS) + and Visual Studio 2017 (Windows) are the oldest officially supported. - 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. -- cgit v1.2.3 From 0ecc5d4992ad2086ee9e399a23f233b653b74ee3 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 11 Aug 2019 13:17:31 +0900 Subject: Officially bump requirements: CMake 3.10, C++17, Qt 5.9 --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index cb78dfe0..ee1d947f 100644 --- a/README.md +++ b/README.md @@ -32,19 +32,19 @@ Recent releases of Debian and OpenSuSE, e.g., already have the package (under the old name). If your Linux repo doesn't provide binary package (either libqmatrixclient - older - or libquotient - newer), or you're on Windows or macOS, your best bet is to build the library from the source -and bundle it with your application. In +and bundle it with your application. ### Pre-requisites - A recent Linux, macOS or Windows system (desktop versions tried; Ubuntu Touch is known to work; mobile Windows and iOS might work too but never tried) - - Recent enough Linux examples: Debian Jessy; Fedora 28; OpenSUSE 15; - Ubuntu Bionic. + - Recent enough Linux examples: Debian Stretch; Fedora 28; OpenSUSE Leap 15; + Ubuntu Bionic Beaver. - Qt 5 (either Open Source or Commercial), 5.9 or higher. - A build configuration tool: - - CMake 3.5 or newer (from your package management system or + - CMake 3.10 or newer (from your package management system or [the official website](https://cmake.org/download/)) - or qmake (comes with Qt) -- A C++ toolchain with C++14 support: +- A C++ toolchain with C++17 support: - GCC 7 (Windows, Linux, macOS), Clang 6 (Linux), Apple Clang 10 (macOS) and Visual Studio 2017 (Windows) are the oldest officially supported. - Any build system that works with CMake and/or qmake should be fine: -- cgit v1.2.3 From b41acc4c2ee3bf483e89157230655f3695177b60 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 11 Aug 2019 13:37:54 +0900 Subject: README.md: oldest good Debian is Buster, not Stretch [skip ci] --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index ee1d947f..97e1f9de 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ and bundle it with your application. ### Pre-requisites - A recent Linux, macOS or Windows system (desktop versions tried; Ubuntu Touch is known to work; mobile Windows and iOS might work too but never tried) - - Recent enough Linux examples: Debian Stretch; Fedora 28; OpenSUSE Leap 15; + - Recent enough Linux examples: Debian Buster; Fedora 28; OpenSUSE Leap 15; Ubuntu Bionic Beaver. - Qt 5 (either Open Source or Commercial), 5.9 or higher. - A build configuration tool: -- cgit v1.2.3 From 18cb395868f448a34dacd55a0b7b5c5eb9f06e27 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Mon, 12 Aug 2019 20:13:01 +0900 Subject: README.md: a few notes around using with qmake --- README.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 97e1f9de..d0866c93 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,9 @@ and bundle it with your application. is known to work; mobile Windows and iOS might work too but never tried) - Recent enough Linux examples: Debian Buster; Fedora 28; OpenSUSE Leap 15; Ubuntu Bionic Beaver. -- Qt 5 (either Open Source or Commercial), 5.9 or higher. -- A build configuration tool: +- Qt 5 (either Open Source or Commercial), 5.9 or higher; + 5.12 is recommended, especially if you use qmake +- A build configuration tool (CMake is recommended, qmake is yet supported): - CMake 3.10 or newer (from your package management system or [the official website](https://cmake.org/download/)) - or qmake (comes with Qt) @@ -65,8 +66,8 @@ If you use CMake, `find_package(Quotient)` sets up the client code to use libQuotient, assuming the library development files are installed. There's no documented procedure to use a preinstalled library with qmake; consider introducing a submodule in your source tree and build it along with the rest -of the application for now. Patches to provide .prl files for qmake -are welcome. +of the application for now. Note also that qmake is considered for phase-out +in Qt 6 so you should probably think of moving over to CMake eventually. Building with dynamic linkage are only tested on Linux at the moment and are a recommended way of linking your application with libQuotient on this platform. @@ -124,9 +125,15 @@ The library provides a .pri file with an intention to be included from a bigger 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 standalone library with qmake is not implemented yet. +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. Note that +qmake didn't really know about C++17 until Qt 5.12 so if your Qt is older +you may have quite a bit of warnings during the compilation process. + +Installing the standalone library with qmake is not implemented yet; PRs are +welcome though. ## Troubleshooting -- cgit v1.2.3 From 41a3661f353207be4005a2cd9b0bb7cfa5601a69 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 18 Aug 2019 18:22:15 +0900 Subject: New logging categories: events.state, events.messages, and e2ee --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d0866c93..9a847712 100644 --- a/README.md +++ b/README.md @@ -155,8 +155,11 @@ libQuotient uses Qt's logging categories to make switching certain types of logg quotient..= ``` where -- `` is one of: `main`, `jobs`, `jobs.sync`, `events`, `events.ephemeral`, and `profiler` (you can always find the full list in the file `lib/logging.cpp`) -- `` is one of `debug` and `warning` +- `` is one of: `main`, `jobs`, `jobs.sync`, `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`) +- `` is one of `debug`, `info`, and `warning` - `` is either `true` or `false`. `*` 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 -- cgit v1.2.3 From f09665afde34dcf6eb7416ba1a5a8d539db67223 Mon Sep 17 00:00:00 2001 From: Martin Rey <42996147+m-rey@users.noreply.github.com> Date: Tue, 1 Oct 2019 23:11:24 +0200 Subject: Fix openSUSE misspelling Fix #355 The correct spelling of openSUSE can be checked on https://en.opensuse.org/Portal:Distribution --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 9a847712..fc8bd82e 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ in SECURITY.md. ## Getting and using libQuotient Depending on your platform, the library can come as a separate package. -Recent releases of Debian and OpenSuSE, e.g., already have the package +Recent releases of Debian and openSUSE, e.g., already have the package (under the old name). If your Linux repo doesn't provide binary package (either libqmatrixclient - older - or libquotient - newer), or you're on Windows or macOS, your best bet is to build the library from the source @@ -37,7 +37,7 @@ and bundle it with your application. ### Pre-requisites - A recent Linux, macOS or Windows system (desktop versions tried; Ubuntu Touch is known to work; mobile Windows and iOS might work too but never tried) - - Recent enough Linux examples: Debian Buster; Fedora 28; OpenSUSE Leap 15; + - Recent enough Linux examples: Debian Buster; Fedora 28; openSUSE Leap 15; Ubuntu Bionic Beaver. - Qt 5 (either Open Source or Commercial), 5.9 or higher; 5.12 is recommended, especially if you use qmake -- cgit v1.2.3 From a0de0e5621b75c8790012275af851a85ad601dfc Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Wed, 2 Oct 2019 16:38:31 +0900 Subject: Update documentation regarding C++17 support level [skip ci] --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index fc8bd82e..7514d0fd 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ and bundle it with your application. - CMake 3.10 or newer (from your package management system or [the official website](https://cmake.org/download/)) - or qmake (comes with Qt) -- A C++ toolchain with C++17 support: +- A C++ toolchain with _reasonably complete_ C++17 support: - GCC 7 (Windows, Linux, macOS), Clang 6 (Linux), Apple Clang 10 (macOS) and Visual Studio 2017 (Windows) are the oldest officially supported. - Any build system that works with CMake and/or qmake should be fine: -- cgit v1.2.3 From 1d57741c679ec3112ae45e833b8f152fa737b944 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Tue, 19 Nov 2019 15:11:39 +0900 Subject: Add LGTM badge --- README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'README.md') diff --git a/README.md b/README.md index 7514d0fd..d83f1cd7 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ [![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) +[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/quotient-im/libQuotient.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/quotient-im/libQuotient/context:cpp) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) The Quotient project aims to produce a Qt5-based SDK to develop applications -- cgit v1.2.3 From 473483665d03c748f568a823218edfb9f5cbc7c9 Mon Sep 17 00:00:00 2001 From: Alexey Andreev Date: Tue, 18 Feb 2020 20:40:54 +0300 Subject: [quotest] Update README.md Signed-off-by: Alexey Andreev --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d83f1cd7..10f62c48 100644 --- a/README.md +++ b/README.md @@ -77,13 +77,12 @@ Static linkage is the default on Windows/macOS; feel free to experiment with dynamic linking and submit PRs if you get reusable results. The example/test application that comes with libQuotient, -[qmc-example](https://github.com/quotient-im/libQuotient/tree/master/examples) -includes most common use cases such as sending messages, uploading files, +[quotest](tests) includes most common use cases such as sending messages, uploading files, setting room state etc.; for more extensive usage check out the source code of [Quaternion](https://github.com/quotient-im/Quaternion) (the reference client of Quotient) or [Spectral](https://gitlab.com/b0/spectral). -To ease the first step, `examples/CMakeLists.txt` is a good starting point +To ease the first step, `tests/CMakeLists.txt` is a good starting point for your own CMake-based project using libQuotient. ## Building the library @@ -115,18 +114,18 @@ You can install the library with CMake: cmake --build . --target install ``` This will also install cmake package config files; once this is done, you -should be able to use `examples/CMakeLists.txt` to compile qmc-example -with the _installed_ library. Installation of the `qmc-example` binary +should be able to use [`tests/CMakeLists.txt`](tests/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 `QMATRIXCLIENT_INSTALL_EXAMPLE` to `OFF`. +by setting `Quotient_INSTALL_TESTS` to `OFF`. ### 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: +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 `quotest.pro` that will build a minimal example of library usage for you. In the root directory of the project sources: ```shell script -qmake qmc-example.pro +qmake quotest.pro make all ``` -This will get you `debug/qmc-example` and `release/qmc-example` +This will get you `debug/quotest` and `release/quotest` 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. Note that -- cgit v1.2.3 From b27e4e2b75180c920deef1399487228f79882f47 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Wed, 15 Apr 2020 12:52:11 +0200 Subject: README.md: describe used CMake variables In particular, the newly introduced Quotient_ENABLE_E2EE (which people should NOT switch on without proper understanding as yet). [skip ci] --- README.md | 42 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 10f62c48..65fc2217 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,13 @@ on Windows or macOS, your best bet is to build the library from the source and bundle it with your application. ### Pre-requisites -- A recent Linux, macOS or Windows system (desktop versions tried; Ubuntu Touch - is known to work; mobile Windows and iOS might work too but never tried) +- 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 Buster; Fedora 28; openSUSE Leap 15; Ubuntu Bionic Beaver. - Qt 5 (either Open Source or Commercial), 5.9 or higher; 5.12 is recommended, especially if you use qmake -- A build configuration tool (CMake is recommended, qmake is yet supported): +- A build configuration tool (CMake is recommended, qmake is supported): - CMake 3.10 or newer (from your package management system or [the official website](https://cmake.org/download/)) - or qmake (comes with Qt) @@ -103,11 +103,43 @@ 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=...], 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. +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. + +The first CMake invocation 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` 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=`, `OFF` by default - enable work-in-progress + E2EE code in the library. As of 0.6, this code is very incomplete and leaks + memory; only set this to `ON` if you want to help making this code work. + 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 0.6)`) + code; so you can use `#ifdef Quotient_E2EE_ENABLED` to guard the code using + E2EE parts of Quotient. +- `MATRIX_DOC_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 -- cgit v1.2.3 From cf960897089289656fc0f5d9a7d3d1242565b16f Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Sun, 7 Jun 2020 13:53:34 +0200 Subject: README.md: minor cleanup [skip ci] --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 65fc2217..7dbb5dbc 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ QT_LOGGING_RULES="libqmatrixclient.*.debug=true;libqmatrixclient.jobs.debug=fals 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`. +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 a text JSON file (very long and unindented so prepare a good +will be in text JSON files (possibly very long and unindented so prepare a good JSON viewer or text editor with JSON formatting capabilities). -- cgit v1.2.3 From 6e4e22cfa4a807ab18fbf1d704f312d0876a4ef5 Mon Sep 17 00:00:00 2001 From: Kitsune Ral Date: Fri, 4 Sep 2020 21:41:48 +0200 Subject: Update documentation [skip ci] --- README.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 7dbb5dbc..0ed599b3 100644 --- a/README.md +++ b/README.md @@ -59,8 +59,18 @@ Just install things from the list above using your preferred package manager. If `brew install qt5` should get you a recent Qt5. If you plan to use CMake, you will need to tell it about the path to Qt by passing `-DCMAKE_PREFIX_PATH=$(brew --prefix qt5)` #### 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\\\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 macOS (see above), also helps. +Install Qt5, using their official installer; if you plan to build with CMake, +make sure to tick the CMake box in the list of installed components. + +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\\\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 you can alternatively point +`CMAKE_PREFIX_PATH` to your Qt installation and leave PATH unchanged; but +in that case you'll have to supply the full path to CMake when calling it. ### Using the library If you use CMake, `find_package(Quotient)` sets up the client code to use @@ -70,14 +80,13 @@ introducing a submodule in your source tree and build it along with the rest of the application for now. Note also that qmake is considered for phase-out in Qt 6 so you should probably think of moving over to CMake eventually. -Building with dynamic linkage are only tested on Linux at the moment and are +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. -Feel free Static linkage is the default on Windows/macOS; feel free to experiment with dynamic linking and submit PRs if you get reusable results. -The example/test application that comes with libQuotient, -[quotest](tests) includes most common use cases such as sending messages, uploading files, +[Quotest](tests), the test application that comes with libQuotient, includes +most common use cases such as sending messages, uploading files, setting room state etc.; for more extensive usage check out the source code of [Quaternion](https://github.com/quotient-im/Quaternion) (the reference client of Quotient) or [Spectral](https://gitlab.com/b0/spectral). -- cgit v1.2.3 From 8858c40091ed73b730fe62bf565b34cdda1b4e39 Mon Sep 17 00:00:00 2001 From: Vladyslav Hnatiuk Date: Sat, 3 Apr 2021 07:39:41 +0200 Subject: Fix broken links in README. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 0ed599b3..c993c31e 100644 --- a/README.md +++ b/README.md @@ -85,13 +85,13 @@ 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. -[Quotest](tests), the test application that comes with libQuotient, includes +[Quotest](quotest), the test application that comes with libQuotient, includes most common use cases such as sending messages, uploading files, setting room state etc.; for more extensive usage check out the source code of [Quaternion](https://github.com/quotient-im/Quaternion) (the reference client of Quotient) or [Spectral](https://gitlab.com/b0/spectral). -To ease the first step, `tests/CMakeLists.txt` is a good starting point +To ease the first step, `quotest/CMakeLists.txt` is a good starting point for your own CMake-based project using libQuotient. ## Building the library @@ -155,7 +155,7 @@ You can install the library with CMake: cmake --build . --target install ``` This will also install cmake package config files; once this is done, you -should be able to use [`tests/CMakeLists.txt`](tests/CMakeLists.txt) to compile quotest +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`. -- cgit v1.2.3 From e9dace0e22a2aa3727bc842a30b4ad504029c0fc Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Fri, 16 Jul 2021 20:09:42 +0200 Subject: Log thumbnail requests in their own category As pointed out by one of users, thumbnail requests produce quite a bit of logging traffic, so it's better to manage them separately. --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index c993c31e..d5aae543 100644 --- a/README.md +++ b/README.md @@ -196,11 +196,11 @@ libQuotient uses Qt's logging categories to make switching certain types of logg quotient..= ``` where -- `` is one of: `main`, `jobs`, `jobs.sync`, `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`) -- `` is one of `debug`, `info`, and `warning` +- `` 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`); +- `` is one of `debug`, `info`, and `warning`; - `` is either `true` or `false`. `*` 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 -- cgit v1.2.3 From 1f52b5a2da9bce4d25f4c897370e58c8b6d56ba1 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Sat, 7 Aug 2021 11:08:57 +0200 Subject: README.md: replace "PRs welcome" with a merge chance badge --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index d5aae543..05c629f2 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![](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) [![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/quotient-im/libQuotient.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/quotient-im/libQuotient/context:cpp) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) +[![merge-chance-badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fmerge-chance.info%2Fbadge%3Frepo%3Dquotient-im/libquotient)](https://merge-chance.info/target?repo=quotient-im/libquotient) 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 -- cgit v1.2.3 From f14b04157a9cacaf60f815f164939cc42dad04da Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Thu, 2 Sep 2021 19:42:24 +0200 Subject: Require CMake 3.16; drop qmake; use C++20 and newer compilers Also, refresh the documentation a bit. --- README.md | 125 +++++++++++++++++++++++++++----------------------------------- 1 file changed, 55 insertions(+), 70 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 05c629f2..71f2d04c 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,7 @@ 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), -[Spectral](https://matrix.org/docs/projects/client/spectral.html) and -other projects. +[NeoChat](https://matrix.org/docs/projects/client/neo-chat) and other projects. Versions 0.5.x and older use the previous name - libQMatrixClient. ## Contacts @@ -38,61 +37,62 @@ and bundle it with your application. ### Pre-requisites - 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 Buster; Fedora 28; openSUSE Leap 15; - Ubuntu Bionic Beaver. -- Qt 5 (either Open Source or Commercial), 5.9 or higher; - 5.12 is recommended, especially if you use qmake -- A build configuration tool (CMake is recommended, qmake is supported): - - CMake 3.10 or newer (from your package management system or - [the official website](https://cmake.org/download/)) - - or qmake (comes with Qt) -- A C++ toolchain with _reasonably complete_ C++17 support: - - GCC 7 (Windows, Linux, macOS), Clang 6 (Linux), Apple Clang 10 (macOS) - and Visual Studio 2017 (Windows) are the oldest officially supported. -- 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. + - Recent enough Linux examples: Debian Bullseye; Fedora 33; openSUSE Leap 15.3; + Ubuntu Focal Fossa. +- Qt 5 (either Open Source or Commercial), 5.12 or higher +- CMake 3.16 or newer (from your package management system or + [the official website](https://cmake.org/download/)) +- A C++ toolchain with complete (as much as possible) C++17 and basic C++20: + - GCC 10 (Windows, Linux, macOS), Clang 11 (Linux), Apple Clang 12 (macOS) + and Visual Studio 2019 (Windows) are the oldest officially supported. +- 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. #### macOS -`brew install qt5` should get you a recent Qt5. If you plan to use CMake, you will need to tell it about the path to Qt by passing `-DCMAKE_PREFIX_PATH=$(brew --prefix qt5)` +`brew install qt5` should get you a recent Qt5. You may need to pass +`-DCMAKE_PREFIX_PATH=$(brew --prefix qt5)` to make it aware of the Qt location. #### Windows -Install Qt5, using their official installer; if you plan to build with CMake, -make sure to tick the CMake box in the list of installed components. - -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\\\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 you can alternatively point -`CMAKE_PREFIX_PATH` to your Qt installation and leave PATH unchanged; but -in that case you'll have to supply the full path to CMake when calling it. +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. + +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\\\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. ### Using the library -If you use CMake, `find_package(Quotient)` sets up the client code to use -libQuotient, assuming the library development files are installed. There's no -documented procedure to use a preinstalled library with qmake; consider -introducing a submodule in your source tree and build it along with the rest -of the application for now. Note also that qmake is considered for phase-out -in Qt 6 so you should probably think of moving over to CMake eventually. +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. -[Quotest](quotest), the test application that comes with libQuotient, includes -most common use cases such as sending messages, uploading files, -setting room state etc.; for more extensive usage check out the source code -of [Quaternion](https://github.com/quotient-im/Quaternion) -(the reference client of Quotient) or [Spectral](https://gitlab.com/b0/spectral). - -To ease the first step, `quotest/CMakeLists.txt` is a good starting point -for your own CMake-based project using libQuotient. +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). @@ -101,28 +101,29 @@ 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) to its master branch. +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. -### CMake-based -In the root directory of the project sources: +The following commands issued in the root directory of the project sources: ```shell script mkdir build_dir cd build_dir cmake .. # [-D=...], 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, 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. - -The first CMake invocation configures the build. You can pass CMake variables, -such as `-DCMAKE_PREFIX_PATH="path1;path2;..."` and -`-DCMAKE_INSTALL_PREFIX=path` here if needed. +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. + +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: @@ -160,22 +161,6 @@ 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`. -### 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 `quotest.pro` that will build a minimal example of library usage for you. In the root directory of the project sources: -```shell script -qmake quotest.pro -make all -``` -This will get you `debug/quotest` and `release/quotest` -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. Note that -qmake didn't really know about C++17 until Qt 5.12 so if your Qt is older -you may have quite a bit of warnings during the compilation process. - -Installing the standalone library with qmake is not implemented yet; PRs are -welcome though. - ## Troubleshooting #### Building fails -- cgit v1.2.3 From 10197b03cc354f69b9d3cc028d00cf3df00ca91f Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Thu, 19 May 2022 21:21:31 +0200 Subject: README: drop defunct Merge chance badge --- README.md | 1 - 1 file changed, 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 71f2d04c..f2bfcb9e 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,6 @@ [![](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) [![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/quotient-im/libQuotient.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/quotient-im/libQuotient/context:cpp) -[![merge-chance-badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fmerge-chance.info%2Fbadge%3Frepo%3Dquotient-im/libquotient)](https://merge-chance.info/target?repo=quotient-im/libquotient) 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 -- cgit v1.2.3 From 617514cf9da4d444c285ebb27ff1c7fd034a484f Mon Sep 17 00:00:00 2001 From: Tobias Fella Date: Fri, 20 May 2022 22:24:41 +0200 Subject: Adapt update-api target to matrix-doc split --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index f2bfcb9e..15f1fcd7 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ the standard variables coming with CMake. On top of them, Quotient introduces: Quotient and Quotient-dependent (if it uses `find_package(Quotient 0.6)`) code; so you can use `#ifdef Quotient_E2EE_ENABLED` to guard the code using E2EE parts of Quotient. -- `MATRIX_DOC_PATH` and `GTAD_PATH` - these two variables are used to point +- `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 -- cgit v1.2.3 From 9ba97217e2ee6378cc7cf338828d093b81e6b8f4 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Mon, 13 Jun 2022 20:51:06 +0200 Subject: Refresh documentation CONTRIBUTING.md got bitrotten in quite a few places. [skip ci] --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 15f1fcd7..e42cb488 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ and bundle it with your application. - Qt 5 (either Open Source or Commercial), 5.12 or higher - CMake 3.16 or newer (from your package management system or [the official website](https://cmake.org/download/)) -- A C++ toolchain with complete (as much as possible) C++17 and basic C++20: +- A C++ toolchain with that supports at least some subset of C++20: - GCC 10 (Windows, Linux, macOS), Clang 11 (Linux), Apple Clang 12 (macOS) and Visual Studio 2019 (Windows) are the oldest officially supported. - Any build system that works with CMake should be fine: -- cgit v1.2.3 From 3581b9d03fe2f169909b3977606abd3b459c0529 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Thu, 16 Jun 2022 22:44:41 +0200 Subject: CMakeLists and elsewhere: require Qt 5.15 --- README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index e42cb488..2deaa28b 100644 --- a/README.md +++ b/README.md @@ -26,19 +26,17 @@ If you find what looks like a security issue, please use instructions in SECURITY.md. ## Getting and using libQuotient -Depending on your platform, the library can come as a separate package. -Recent releases of Debian and openSUSE, e.g., already have the package -(under the old name). If your Linux repo doesn't provide binary package -(either libqmatrixclient - older - or libquotient - newer), or you're -on Windows or macOS, your best bet is to build the library from the source -and bundle it with your application. +Depending on your platform, the library can be obtained from a package +management system. Recent releases of Debian and openSUSE, e.g., already have +it. Alternatively, just build the library from the source and bundle it with +your application, as described below. ### Pre-requisites - 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 33; openSUSE Leap 15.3; - Ubuntu Focal Fossa. -- Qt 5 (either Open Source or Commercial), 5.12 or higher + - Recent enough Linux examples: Debian Bullseye; Fedora 35; + openSUSE Leap 15.4; Ubuntu 22.04 LTS. +- Qt 5 (either Open Source or Commercial), 5.15 or higher - CMake 3.16 or newer (from your package management system or [the official website](https://cmake.org/download/)) - A C++ toolchain with that supports at least some subset of C++20: -- cgit v1.2.3 From 56575aaed81e1d55e41f577d7b6683702e4c0384 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Tue, 14 Jun 2022 11:22:06 +0200 Subject: Replace LGTM badge with GHA/Sonar Also: add a Matrix chat badge. [skip ci] --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 2deaa28b..e0f4596c 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,10 @@ [![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) -[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/quotient-im/libQuotient.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/quotient-im/libQuotient/context:cpp) +![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) 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 -- cgit v1.2.3 From 955e1314ebfd83d6f44d88547159e6492035681e Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Fri, 8 Jul 2022 09:28:58 +0200 Subject: CI: use GCC 11 and (therefore) ubuntu-22.04 GCC 10 ICE's[1] in qt_connection_util.h code; and ubuntu-20.04 doesn't have GCC 11. Also: patch a Qt 5.15 header when compiling with GCC because a combination of Qt 5.15 and GCC 11 in turn triggers QTBUG-91909/90568... Which in turn required moving Qt setup before the build environment setup. Life's fun. [1] Internal Compiler Error --- README.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index e0f4596c..8be38b5c 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ your application, as described below. - CMake 3.16 or newer (from your package management system or [the official website](https://cmake.org/download/)) - A C++ toolchain with that supports at least some subset of C++20: - - GCC 10 (Windows, Linux, macOS), Clang 11 (Linux), Apple Clang 12 (macOS) + - GCC 11 (Windows, Linux, macOS), Clang 11 (Linux), Apple Clang 12 (macOS) and Visual Studio 2019 (Windows) are the oldest officially supported. - 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. @@ -165,14 +165,37 @@ by setting `Quotient_INSTALL_TESTS` to `OFF`. #### 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 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(ThreadEngine \*_threadEngine) + ``` + and remove the template specialisation from the constructor name so that it + looks like + ```cplusplus + ThreadEngineStarter(ThreadEngine \*_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 -- cgit v1.2.3 From a3ab7dc4bc7cd538d922ea69d2dad158e7bc9770 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Wed, 7 Sep 2022 22:11:51 +0200 Subject: README: add a troubleshooting case with mixed Qt 5/6 --- README.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 8be38b5c..6278535a 100644 --- a/README.md +++ b/README.md @@ -173,6 +173,20 @@ by setting `Quotient_INSTALL_TESTS` to `OFF`. "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 -- cgit v1.2.3 From 747913f2549c1b228395192a73231b96c93f4f40 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Sat, 17 Sep 2022 22:11:53 +0200 Subject: Update README on E2EE [skip ci] --- README.md | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 6278535a..e7597fce 100644 --- a/README.md +++ b/README.md @@ -30,8 +30,8 @@ in SECURITY.md. ## Getting and using libQuotient Depending on your platform, the library can be obtained from a package -management system. Recent releases of Debian and openSUSE, e.g., already have -it. Alternatively, just build the library from the source and bundle it with +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 @@ -39,12 +39,16 @@ your application, as described below. 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 (either Open Source or Commercial), 5.15 or higher -- CMake 3.16 or newer (from your package management system or - [the official website](https://cmake.org/download/)) -- A C++ toolchain with that supports at least some subset of C++20: +- 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.x (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. @@ -56,8 +60,11 @@ 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. #### macOS -`brew install qt5` should get you a recent Qt5. You may need to pass -`-DCMAKE_PREFIX_PATH=$(brew --prefix qt5)` to make it aware of the Qt location. +`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 Install Qt5 using their official installer; make sure to tick the CMake box @@ -72,6 +79,14 @@ 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. +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 @@ -121,6 +136,9 @@ 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. @@ -137,11 +155,14 @@ the standard variables coming with CMake. On top of them, Quotient introduces: 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=`, `OFF` by default - enable work-in-progress - E2EE code in the library. As of 0.6, this code is very incomplete and leaks - memory; only set this to `ON` if you want to help making this code work. + 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 0.6)`) + 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 -- cgit v1.2.3 From a0cc4eaf6af6f047e32713b2926f784fa4087a64 Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Sat, 17 Sep 2022 13:21:35 +0200 Subject: Bump required Olm version to 3.2.5 This is the earliest version shipping olm/error.h. Conversely, stock libolm that comes with Ubuntu 20.04 (version 3.1.3) is no more enough so CI completely switches to jammy now. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index e7597fce..d9f50f0a 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ your application, as described below. - 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.x (the latest 3.x strongly recommended) + - 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. -- cgit v1.2.3