libQuotient
0.9.1
商项目旨在生产基于QT的SDK来开发矩阵的应用程序。 Libquotient是一个启用客户端应用程序的库。它是季节，neochat和其他项目的骨干。
您可以在矩阵室中找到商：＃Quotient：matrix.org。
您可以在项目问题跟踪器中提交问题。如果您发现看起来像安全问题，请使用Security.md中的说明。
根据您的平台，可以从软件包管理系统获得库。 Fedora，Debian和Opensuse的最新版本已经拥有。另外，您可以从源构建库，并将其与您的应用程序捆绑在一起，如下所述。
要使用libquotient（即使用它构建或运行应用程序），您将需要：
要用Libquotient构建应用程序，您还需要：
建立Libquotient本身的要求基本相同，除非您应该为上述依赖项安装开发库。
只需使用首选的软件包管理器安装先决条件即可。如果您的QT软件包基数是细粒度的，则可能需要运行CMAKE并查看错误消息。图书馆完全是屏幕范围的；但是，除了qtcore和qtnetwork之外，它还取决于qtgui，以便无需任何屏幕图即可处理头像缩略图。
brew install qt qtkeychain libolm openssl@3应该为您提供运行时库的最新版本。
您可能需要在CMAKE_PREFIX_PATH （见下文）中添加$(brew --prefix qt) ， $(brew --prefix qtkeychain)等，以使cmake意识到库位置。
使用QT项目官方安装程序安装QT和OpenSSL；请确保还要在要安装的组件列表中的CMAKE框中打勾，除非您已经有。这将为您提供运行时库和开发文件，这些文件也适合构建Libquotient本身。如果您这样做，则必须从源代码构建Qtkeychain。
另外，您可以使用VCPKG安装QT，OpenSSL和Qtkeychain。在这种情况下，您没有得到QT创建者，这是处理基于QT的项目的非常好的IDE；但是，如果您已经使用VSCODE或CLION，则可能更喜欢此路线。您还可以混合匹配，从官方安装程序中安装QT创建者以及VCPKG的其余部分。将官方安装程序的QT与VCPKG的QT键链混合，可能会或可能不起作用，具体取决于用于构建QT键链的QT版本。
如果您是从命令行构建的：进一步的部分中的命令意味着cmake在您的PATH中，否则您必须使用实际路径进行预处理这些命令。运行可以在C:Qt<Qt version><toolchain>bin中找到的qtenv2.bat脚本是一个好主意（假设您将qt安装到C:Qt ）。该脚本添加了通往PATH的必要路径。您可能不想在系统启动上运行该脚本，但是在构建之前设置环境非常方便。
如果您使用C ++ IDE ：您应该能够在其设置中配置CMake路径和额外的选项（尤其是CMAKE_PREFIX_PATH ）。建议不要添加QT（或任何其他库）的路径，以明确PATH ；改用CMAKE_PREFIX_PATH ，然后保持不变PATH 。如果您的IDE是QT创建者，则根本不需要处理QT路径，只需选择合适的套件并直接进入建筑物即可。
您还需要Libolm。您必须自己构建它 - 窗口没有二进制文件，您可以从VCPKG或其他地方下载。源代码可在https://gitlab.matrix.org/matrix-org/olm上找到；对于其他商，您可以使用相同的工具链（CMAKE+MSVC，例如）。
如果您只是从头开始使用libquotient启动一个项目，则可以将quotest/CMakeLists.txt复制到项目中，然后将quotest更改为项目名称。如果您已经有现有的cmakelists.txt，则需要将find_package(Quotient REQUIRED)行插入到适当的find_package(Quotient) （如果libquotient对您不难依赖），然后将Quotient添加到target_link_libraries()行中。
目前仅在Linux上测试动态链接，这是与该平台上的Libquotient链接的推荐方法。静态链接是Windows/MacOS上的默认值；随意尝试动态链接，并为您的结果提供反馈。
可以在各自的Wiki页面上找到（非常基本的）概述。可以在https://quotient-im.github.io/libquotient/上找到库的doxygen文档。此外，查看引号的源代码 - libquotient随附的测试应用程序 - 可能会帮助您处理最常见的用例，例如发送消息，上传文件，设置房间状态等。
有关更广泛用法的示例和模式，可以随意查看（并复制，适当的归因）QUATERNION（LIBQUOTIENT的参考客户端）或Neochat。
由于商0.7.2，因此libquotient的所有标头文件中的符号除了以_p.h结尾的文件和名称空间_impl文件被视为公共，并由API/ABI稳定性保证范围。具体而言，API和ABI在每个次要版本（0.7.x版本）中向后兼容，每个下一个次要版本（0.8，例如）破坏了兼容性。一旦达到1.0，此规则将适用于主要版本，与语义版本管理规则保持一致。 *_p.h文件和命名空间_impl不涵盖这些保证；客户端代码不应直接包含这些文件，也不应使用这些位置中定义的符号。
在Linux以外的其他平台上，您将必须在使用之前建立Libquotient自己 - 到目前为止，没有人打包（欢迎捐款！）。如果您需要更新版本或快照，则可能还需要在Linux上构建库。
源代码在GitHub。强烈建议您查看某个提交或标签（而不是下载档案）以及子模型。如果您想作为另一个项目的一部分在库上进行黑客攻击（例如，您正在从事Quaternion工作，但需要对库代码进行一些更改），则在适当的分支机构内从该项目中进行递归检查（在这种情况下，也可以恢复）是有意义的。请注意API兼容性限制：例如，每个版本的四个版本都可能需要libquotient的特定分支（ 0.8.x ， 0.9.x等）。
仅由数字和全部组成的标签（例如， 0.7.0 ）对应于发布的版本；标签以-betaN或-rcN标记相应的预释放。如果/包装预先发行时，建议用~ （tilde）替换- 。
Libquotient是一个经典的基于CMAKE的项目；假设依赖项已经到位，则在项目来源的根目录中发出的以下命令：
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all将在build中为您提供一个编译的库（确保在运行之前存在它）。与CMAKE一起使用的任何C ++ IDE都可以通过最小的配置工作来做同样的事情。
在所有受支持的平台上测试了静态构建。动态库是Linux上推荐的配置；可能在MacOS上可行；并且在Windows上未经测试（欢迎您尝试报告结果）。
在继续之前，请仔细检查您已安装了上述所有先决条件的开发库。 Cmake会停止告诉您是否缺少某些东西。
上面的第一个CMAKE调用配置了构建。您可以将CMAKE变量（例如-DCMAKE_PREFIX_PATH="path1;path2;..."和-DCMAKE_INSTALL_PREFIX=path ）传递到该调用（如果需要）。 CMAKE文档（选择您使用的页面顶部的CMAKE版本）描述了CMAKE随附的标准变量。最重要的是，商理解：
Quotient_INSTALL_TESTS=<ON/OFF> ，默认情况ON - 调用install目标时安装quotest以及库文件。 quotest是一个小型命令行程序，该程序（假设正确的参数，请参见quotest --help ）试图以给定的用户连接到给定的房间并执行一些基本的矩阵操作，例如发送消息和小文件，修复，设置房间标签等。这对于检查图书馆安装的理智很有用。MATRIX_SPEC_PATH和GTAD_PATH这两个变量用于用包含API文件的Matrix -Doc存储库将CMAKE指向目录，并将其指向GTAD二进制文件。这两个用于从OpenAPI符号中制作的Matrix Client-Server-Server API描述生成C ++文件。如果您只需要构建库，则不需要这一点。如果您真的很喜欢黑客攻击，请阅读condrating.md和code_generation.md中的各个部分。QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , OFF by default (note that QUOTIENT is in caps here, unlike options above) - when this option is set to ON , CMake skips adding <top-level include prefix>/Quotient/ to include paths, thereby forcing the client code to use #include <Quotient/header.h> instead of historically accepted #include <header.h> .默认情况下，这将OFF为向后兼容。最终，此默认可能会更改此默认值，因此建议至少偶尔添加-DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1到cmake Invocation（或设置IDE中的变量）并确保您的代码具有前缀的路径。您可以使用cmake安装库：
cmake --build . --target install这还将安装CMAKE软件包配置文件；完成此操作后，您应该能够使用quotest/CMakeLists.txt与已安装的库一起编译引号。如上所述，可以通过将Quotient_INSTALL_TESTS设置为OFF来跳过quotest二进制文件以及其余的库的安装。
如果cmake失败
CMake Warning at CMakeLists.txt:11 (find_package):
By not providing "FindQt6Widgets.cmake" in CMAKE_MODULE_PATH this project
has asked CMake to find a package configuration file provided by
"Qt6Widgets", but CMake did not find one.
然后，您需要设置正确的-DCMAKE_PREFIX_PATH变量，请参见上文。
如果cmake失败，消息类似：
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
然后，您可能会在系统上同时使用QT 5和QT 6，并且代码使用QT的主要版本与商不同。确保配置构建，以便libquotient和您的代码同时使用相同的主要QT版本。
Libquotient使用QT的记录类别，使切换某些类型的日志记录更加容易。如果在运行时发生麻烦（错误，崩溃），则可以增加日志记录，如果将以下内容添加到QT_LOGGING_RULES环境变量：
quotient.<category>.<level>=<flag>
在哪里
<category>是： main ， jobs ， jobs.sync ， jobs.thumbnail ， events之一（涵盖“常规”房间状态和帐户数据）， events.members ， events.messages ， events.ephemeral ， database ，Database， network ， e2ee和profiler您可以始终在Quotient/logging_categories_p.h events.state<level>是debug ， info和warning之一；<flag>是true或false 。您可以将* （星号）用作两个点之间的任何零件的通配符，而半分离器则用于分离器。后一个语句覆盖了以前的语句，因此QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"如果要打开所有调试jobs
您可能还需要设置QT_MESSAGE_PATTERN ，以使日志更具信息性（请参阅https://doc.qt.io/qt-6/qtlogging.html#qsetmessagepattern有关格式描述的信息）。举个例子，这是其中一个库开发人员用于QT_MESSAGE_PATTERN ：
`%{time h:mm:ss.zzz}|%{category}|%{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}|%{message}`
（可怕的%{if} s只是将记录级别编码到其首字母中）。
如果遇到房间状态和缓存的麻烦，则将缓存格式从二进制CBOR切换到明文JSON可能很有用。为此，将客户端配置文件/注册表中的libQuotient/cache_type键设置为json （您可能需要创建libquotient组，因为它是迄今为止唯一的识别键）。这将使缓存保存和加载工作略慢，但是缓存将在文本JSON文件中（非常长，没有凹痕；准备具有JSON格式化功能的良好JSON查看器或文本编辑器）。
