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查看器或文本編輯器）。
