libQuotient
0.9.1
Das Quotient-Projekt zielt darauf ab, ein QT-basierter SDK zur Entwicklung von Anwendungen für Matrix zu erstellen. libquotient ist eine Bibliothek, die Client -Anwendungen ermöglicht. Es ist das Rückgrat von Quaternion, Neochat und anderen Projekten.
Sie können Quotientenentwickler im Matrixraum finden: #quotient: matrix.org.
Sie können Probleme im Projektproblem -Tracker einreichen. Wenn Sie ein Sicherheitsproblem finden, verwenden Sie Anweisungen in Security.md.
Abhängig von Ihrer Plattform kann die Bibliothek von einem Paketverwaltungssystem erhalten werden. Jüngste Veröffentlichungen von Fedora, Debian und OpenSuse haben es bereits. Alternativ können Sie die Bibliothek aus der Quelle erstellen und sie mit Ihrer Anwendung bündeln, wie unten beschrieben.
Um libquotient zu verwenden (dh Build oder Ausführen von Anwendungen damit), benötigen Sie:
Um Anwendungen mit libquotient zu erstellen, benötigen Sie auch:
Die Anforderungen für den Aufbau von libquotient selbst sind im Grunde genommen gleich, außer dass Sie Entwicklungsbibliotheken für die oben aufgeführten Abhängigkeiten installieren sollten.
Installieren Sie einfach die Voraussetzungen mit Ihrem bevorzugten Paketmanager. Wenn Ihre QT-Paketbasis feinkörnig ist, möchten Sie möglicherweise CMake ausführen und Fehlermeldungen ansehen. Die Bibliothek ist völlig außerhalb des Bildschirms; Abgesehen von QTCORE und QTNETWORK hängt es jedoch auch von QTGUI ab, um Avatar-Miniaturansichten ohne Zeichnung auf dem Bildschirm zu verarbeiten.
brew install qt qtkeychain libolm openssl@3 sollte Ihnen die neuesten Versionen der Laufzeitbibliotheken erhalten.
Möglicherweise müssen Sie $(brew --prefix qt) , $(brew --prefix qtkeychain) usw. zu CMAKE_PREFIX_PATH (siehe unten) hinzufügen, um CMake auf die Bibliotheksorte aufmerksam zu machen.
Installieren Sie QT und OpenSSL mit dem QT Project Official Installer; Stellen Sie sicher, dass Sie das CMAKE -Feld auch in der zu installierenden Liste der Komponenten ankreuzen, es sei denn, Sie haben es bereits. Auf diese Weise erhalten Sie sowohl die Laufzeitbibliotheken als auch die Entwicklungsdateien, die auch dazu geeignet sind, selbst Libquotient selbst zu erstellen. Wenn Sie diesen Weg gehen, müssen Sie Qtkeychain aus dem Quellcode erstellen.
Alternativ können Sie VCPKG verwenden, um QT, OpenSSL und Qtkeychain zu installieren. In diesem Fall erhalten Sie keinen QT-Schöpfer, was eine sehr schöne IDE ist, um mit QT-basierten Projekten umzugehen. Wenn Sie jedoch VSCODE oder Clion bereits verwenden, bevorzugen Sie diese Route möglicherweise. Sie können auch QT Creator aus dem offiziellen Installateur und den Rest von VCPKG mischen und übereinstimmen. Das Mischen von QT aus dem offiziellen Installationsprogramm mit QT -Schlüsselbund von VCPKG kann je nach QT -Version, die zum Erstellen von QT -Schlüsselbund verwendet wird, funktioniert oder nicht.
Wenn Sie aus der Befehlszeile erstellen : Die Befehle in weiteren Abschnitten implizieren, dass cmake in Ihrem PATH liegt. Andernfalls müssen Sie diese Befehle mit tatsächlichen Pfaden vorbereiten. Es ist eine gute Idee, das qtenv2.bat -Skript auszuführen, das in C:Qt<Qt version><toolchain>bin (unter der Annahme, dass Sie QT nach C:Qt installiert haben) gefunden werden. Dieses Skript fügt den erforderlichen Pfaden zum PATH hinzu. Möglicherweise möchten Sie dieses Skript beim Systemstart nicht ausführen, aber es ist sehr praktisch, die Umgebung vor dem Aufbau einzustellen.
Wenn Sie eine C ++ - IDE verwenden : Sie sollten in seinen Einstellungen in der Lage sein, CMake -Pfad und zusätzliche Optionen (insbesondere CMAKE_PREFIX_PATH ) zu konfigurieren. Es wird empfohlen, den Pfad für QT (oder eine andere Bibliothek) nicht explizit zum PATH hinzuzufügen. Verwenden Sie stattdessen CMAKE_PREFIX_PATH und lassen Sie PATH unverändert. Wenn Ihre IDE QT -Schöpfer ist, sollten Sie sich überhaupt nicht mit QT -Pfaden befassen, einfach das richtige Kit auswählen und direkt zum Gebäude gehen.
Sie brauchen auch Libolm. Sie müssen es selbst bauen - es gibt kein Binärdauer für Windows, die Sie zum Zeitpunkt dieser Schrift von VCPKG oder anderswo herunterladen können. Der Quellcode ist unter https://gitlab.matrix.org/matrix-org/olm verfügbar; Sie können dieselbe Toolchain (CMake+MSVC, z. B. für den Rest des Quotienten verwenden.
Wenn Sie gerade ein Projekt mit libquotient von Grund auf neu starten, können Sie quotest/CMakeLists.txt in Ihr Projekt kopieren und quotest in Ihren Projektnamen ändern. Wenn Sie bereits über eine vorhandene cmakelists.txt verfügen, müssen Sie eine find_package(Quotient REQUIRED) -Zeile an einem geeigneten Ort einfügen (verwenden Sie find_package(Quotient) wenn libquotient für Sie keine harte Abhängigkeit ist) und fügen Sie dann Ihrer Linie target_link_libraries() Zeile () Quotient hinzu.
Die dynamische Verknüpfung wird momentan nur auf Linux getestet und ist die empfohlene Methode, um auf dieser Plattform mit libquotient zu verknüpfen. Die statische Verknüpfung ist die Standardeinstellung unter Windows/MacOS. Fühlen Sie sich frei, mit dynamischer Verknüpfung zu experimentieren und Feedback mit Ihren Ergebnissen zu geben.
Eine (sehr einfache) Übersicht finden Sie auf der jeweiligen Wiki -Seite. Die Doxygen-Dokumentation für die Bibliothek finden Sie unter https://quotient-im.github.io/libquotient/. Wenn Sie den Quellcode für Quotest untersuchen - die mit libquotient gelieferte Testanwendung - kann Ihnen bei den meisten häufigsten Anwendungsfällen wie dem Senden von Nachrichten, dem Hochladen von Dateien, dem Raumstatus usw. helfen, usw.
Beispiele und Muster von umfassenderen Nutzungsverbrauch finden Sie im Quellcode von Quaternion (den Referenzclient für libquotient) oder Neochat.
Seit Quotienten 0,7.2 werden Symbole in allen Header -Dateien von libquotient mit Ausnahme von Dateien, die mit _p.h und Namespace _impl enden, als öffentlich angesehen und durch API/ABI -Stabilitätsgarantien abgedeckt. Insbesondere sind API und ABI in jeder kleinen Version (0,7.x -Releases) rückwärts kompatibel, wobei jede nächste kleine Version (0,8, z. B. die Kompatibilität brechen. Sobald wir 1.0 erreicht sind, gilt diese Regel für die Hauptversion und stimmt mit den semantischen Versionsregeln aus. *_p.h -Dateien und Namespace _impl werden nicht von diesen Garantien abgedeckt. Der Client -Code sollte diese Dateien nicht direkt einschließen oder Symbole verwenden, die an diesen Standorten definiert sind.
Auf anderen Plattformen als Linux müssen Sie sich vor dem Gebrauch selbst libquotient aufbauen - bisher niemand verpackt (Beiträge willkommen!). Möglicherweise möchten Sie auch die Bibliothek unter Linux erstellen, wenn Sie eine neuere Version oder eine Snapshot benötigen, als dass Sie in Ihrer Distribution kommen.
Der Quellcode befindet sich bei GitHub. Es wird dringend empfohlen, ein bestimmtes Commit oder ein bestimmtes Tag (anstatt das Archiv herunterzuladen) zusammen mit Submodules herauszufinden. Wenn Sie als Teil eines anderen Projekts in die Bibliothek hacken möchten (z. B. Sie arbeiten an Quaternion, müssen jedoch einige Änderungen am Bibliothekscode vornehmen), ist es sinnvoll, eine rekursive Überprüfung dieses Projekts (in diesem Fall Quaternion) vorzunehmen und das Submodul der Bibliothek (ebenfalls regelmäßig) innerhalb des entsprechenden Zweigs zu aktualisieren. Achten Sie auf API -Kompatibilitätsbeschränkungen: 0.8.x , 0.9.x .
Tags, die ausschließlich aus Ziffern und FullStops (z. B. 0.7.0 ) bestehen, entsprechen freigegebenen Versionen; Tags, die mit -betaN oder -rcN -Marke enden, die jeweiligen Vorablösungen sind. Wenn/wenn die vorab der Verpackung Verpackung ist, wird empfohlen, das führende - durch ~ (Tilde) zu ersetzen.
Libquotient ist ein klassisches CMake-basierte Projekt. Unter der Annahme, dass die Abhängigkeiten vorhanden sind, wurden die folgenden Befehle im Stammverzeichnis der Projektquellen ausgegeben:
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all Sie erhalten eine kompilierte Bibliothek in build (stellen Sie sicher, dass sie vor dem Laufen existiert). Jede C ++ - IDE, die mit CMake funktioniert, sollte in der Lage sein, dasselbe mit minimaler Konfigurationsaufwand zu tun.
Statische Builds werden auf allen unterstützten Plattformen getestet. Dynamische Bibliotheken sind die empfohlene Konfiguration unter Linux. Wahrscheinlich auf macOS funktionieren; und ungetestet unter Windows (Sie können gerne versuchen, über die Ergebnisse zu berichten).
Überprüfen Sie vor dem Fortfahren, dass Sie Entwicklungsbibliotheken für alle oben genannten Voraussetzungen installiert haben. CMake wird aufhören und Ihnen sagen, ob etwas fehlt.
Der erste CMake -Aufruf oben konfiguriert den Build. Sie können CMake -Variablen (wie -DCMAKE_PREFIX_PATH="path1;path2;..." und -DCMAKE_INSTALL_PREFIX=path ) an diesen Aufruf übergeben. CMAKE -Dokumentation (wählen Sie die CMake -Version oben auf der von Ihnen verwendeten Seite aus) beschreibt die Standardvariablen, die mit CMAKE kommen. Darüber hinaus versteht Quotient:
Quotient_INSTALL_TESTS=<ON/OFF> ON - Installieren Sie quotest zusammen mit den Bibliotheksdateien, wenn das install aufgerufen wird. quotest ist ein kleines Befehlszeilenprogramm, das (unter der Annahme korrekter Parameter siehe quotest --help HELP), das versucht, als Benutzer ein bestimmtes Raum herzustellen und einige grundlegende Matrixvorgänge auszuführen, z. B. Senden von Nachrichten und kleinen Dateien, Redaktion, Einstellungsraum-Tags usw. Dies ist nützlich, um die Vernunft Ihrer Bibliotheksinstallation zu überprüfen.MATRIX_SPEC_PATH und GTAD_PATH - Diese beiden Variablen werden verwendet, um CMake mit dem Matrix -Doc -Repository, das API -Dateien enthält, und auf eine GTAD -Binärdatei auf das Verzeichnis zu richten. Diese beiden werden verwendet, um C ++-Dateien aus der Matrix-Client-Server-API-Beschreibung in OpenAPI-Notation zu generieren. Dies ist nicht erforderlich, wenn Sie nur die Bibliothek erstellen müssen. Wenn Sie wirklich darauf hacken möchten, lesen Sie bitte die jeweiligen Abschnitte in beitragen.md und code_generation.md.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , standardmäßig OFF (Beachten Sie, dass Quotient hier in den oben genannten Optionen oben ist) - Wenn diese Option auf ON gesetzt ist, überspringt cmake übertrifft <top-level include prefix>/Quotient/ #include <Quotient/header.h> #include <header.h> wodurch der Client -Code gezwungen wird. Standardmäßig ist dies für die Rückwärtskompatibilität OFF . Letztendlich kann sich dieser Standard ändern. Daher wird empfohlen, mindestens gelegentlich -DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1 zu einem CMAKE -Aufruf (oder der Variablen in Ihrer IDE festzulegen) und sicherstellen, dass Ihr Code vorangestellt hat.Sie können die Bibliothek mit CMake installieren:
cmake --build . --target install Dadurch werden auch CMAKE -Paket -Konfigurationsdateien installiert. Sobald dies erledigt ist, sollten Sie in der Lage sein, quotest/CMakeLists.txt zu verwenden, um Quotest mit der installierten Bibliothek zu kompilieren. Wie oben erwähnt, kann die Installation des quotest Binärs zusammen mit dem Rest der Bibliothek übersprungen werden, indem Quotient_INSTALL_TESTS OFF .
Wenn cmake mit fehlschlägen
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.
Anschließend müssen Sie die rechte Variable -DCMAKE_PREFIX_PATH festlegen, siehe oben.
Wenn cmake mit einer ähnlichen Nachricht fehlschlägt:
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
Dann haben Sie wahrscheinlich sowohl QT 5 als auch QT 6 in Ihrem System, und Ihr Code verwendet eine andere Hauptversion von QT als Quotient. Stellen Sie sicher, dass Sie den Build so konfigurieren, dass dieselbe Haupt -QT -Version sowohl von libquotient als auch in Ihrem Code verwendet wird.
Libquotient verwendet die Protokollierungskategorien von QT, um das Umschalten bestimmter Arten von Protokollierung zu erleichtern. Bei Problemen zur Laufzeit (Fehler, Abstürze) können Sie die Protokollierung erhöhen, wenn Sie die Folgende der Umgebungsvariablen QT_LOGGING_RULES hinzufügen:
quotient.<category>.<level>=<flag>
Wo
<category> ist einer von: main e2ee jobs , jobs.sync profiler jobs.thumbnail , events , events.state events.messages Abdeckung sowohl events.ephemeral "üblichen" database und network Kontodaten Quotient/logging_categories_p.h events.members<level> ist eine von debug , info und warning ;<flag> ist entweder true oder false . Sie können * (Sternchen) als Platzhalter für jeden Teil zwischen zwei Punkten verwenden, und Semikolon wird für einen Trennzeichen verwendet. Letztere Anweisungen überschreiben frühere. Wenn Sie also alle Debug -Protokolle außer jobs einschalten möchten, können Sie QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"
Möglicherweise möchten Sie auch QT_MESSAGE_PATTERN so festlegen, dass Protokolle etwas informativer werden (siehe https://doc.qt.io/qt-6/qtlogging.html#qsetMessagePattern für die Formatbeschreibung). Um ein Beispiel zu geben, verwendet einer der Bibliotheksentwickler für 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}`
(Die gruseligen %{if} s codieren nur die Protokollierungsstufe in seinen Anfangsbuchstaben).
Bei Problemen mit Raumzustand und Caching kann es nützlich sein, das Cache -Format von Binary CBOR auf Klartext JSON zu wechseln. Setzen Sie dazu libQuotient/cache_type in der Konfigurationsdatei/Registrierung Ihres Clients auf json (Sie müssen möglicherweise die libquotient -Gruppe erstellen, da sie bisher der einzige anerkannte Schlüssel darin ist). Dadurch wird das Speichern und das Laden von Cache etwas langsamer funktioniert, aber der Cache wird in Text -JSON -Dateien (sehr lang und ohne Eindrückung; bereiten
