libQuotient
0.9.1
Le projet Quotient vise à produire un SDK basé sur QT pour développer des applications pour la matrice. Libquotient est une bibliothèque qui permet les applications clients. C'est l'épine dorsale de Quaternion, Neochat et d'autres projets.
Vous pouvez trouver des développeurs Quotient dans la salle Matrix: #quotient: matrix.org.
Vous pouvez déposer des problèmes chez Project Issue Tracker. Si vous trouvez ce qui ressemble à un problème de sécurité, veuillez utiliser des instructions dans Security.md.
Selon votre plate-forme, la bibliothèque peut être obtenue à partir d'un système de gestion des packages. Les sorties récentes de Fedora, Debian et OpenSuse l'ont déjà. Alternativement, vous pouvez construire la bibliothèque à partir de la source et le regrouper avec votre application, comme décrit ci-dessous.
Pour utiliser libquotient (c'est-à-dire générer ou exécuter des applications avec lui), vous aurez besoin:
Pour créer des applications avec libquotient, vous aurez également besoin:
Les exigences pour construire libquotient lui-même sont essentiellement les mêmes, sauf que vous devez installer des bibliothèques de développement pour les dépendances énumérées ci-dessus.
Installez simplement les conditions préalables à l'aide de votre gestionnaire de packages préféré. Si votre base de package QT est à grain fin, vous voudrez peut-être exécuter CMake et consulter les messages d'erreur. La bibliothèque est entièrement hors écran; Cependant, à part QTCore et Qtnetwork, il dépend également de QTGUI afin de gérer les miniatures d'avatar, sans aucun dessin à l'écran.
brew install qt qtkeychain libolm openssl@3 devrait vous offrir les versions les plus récentes des bibliothèques d'exécution.
Vous devrez peut-être ajouter $(brew --prefix qt) , $(brew --prefix qtkeychain) etc. à CMAKE_PREFIX_PATH (voir ci-dessous) pour sensibiliser Cmake aux emplacements de la bibliothèque.
Installer QT et OpenSSL à l'aide du programme d'installation officiel du projet QT; Assurez-vous également de cocher la boîte CMake dans la liste des composants à installer, sauf si vous l'avez déjà. Cela vous permettra à la fois les bibliothèques d'exécution et les fichiers de développement, qui sont également adaptés à la création de libquotient lui-même. Si vous allez de cette façon, vous devrez construire QtkeyChain à partir du code source.
Alternativement, vous pouvez utiliser VCPKG pour installer QT, OpenSSL et QTKEYCHAIN. Dans ce cas, vous n'obtenez pas QT Creator, ce qui est un IDE très agréable à traiter avec des projets basés sur QT; Mais si vous utilisez déjà VScode ou Clion, vous préférez peut-être cet itinéraire. Vous pouvez également mélanger et assortir, installer QT Creator à partir de l'installateur officiel et le reste de VCPKG. Mélanger QT à partir du programme d'installation officiel avec le clés QT à partir de VCPKG peut fonctionner ou non, selon la version QT utilisée pour créer un trousseau QT.
Si vous construisez à partir de la ligne de commande : les commandes dans d'autres sections impliquent que cmake est sur votre PATH , sinon vous devez prétendre ces commandes avec des chemins réels. C'est une bonne idée d'exécuter le script qtenv2.bat qui peut être trouvé dans C:Qt<Qt version><toolchain>bin (en supposant que vous avez installé QT sur C:Qt ). Ce script ajoute des chemins nécessaires au PATH . Vous ne voudrez peut-être pas exécuter ce script sur le démarrage du système, mais il est très pratique de configurer l'environnement avant de construire.
Si vous utilisez un IDE C ++ : vous devriez pouvoir configurer le chemin CMake et les options supplémentaires ( CMAKE_PREFIX_PATH , en particulier) dans ses paramètres. Il est recommandé de ne pas ajouter le chemin de la route pour QT (ou toute autre bibliothèque) pour PATH explicitement; Utilisez CMAKE_PREFIX_PATH à la place et laissez PATH inchangé. Si votre IDE est Créateur QT, vous ne devriez pas du tout avoir besoin de gérer les chemins QT, choisissez simplement le bon kit et allez directement à la construction.
Vous aurez également besoin de libolm. Vous devrez le construire vous-même - il n'y a pas de binaire pour Windows que vous pouvez télécharger à partir de VCPKG ou ailleurs, à ce jour. Le code source est disponible sur https://gitlab.matrix.org/matrix-org/olm; Vous pouvez utiliser la même chaîne d'outils (CMake + MSVC, par exemple) que pour le reste du quotient.
Si vous commencez simplement un projet à l'aide de libquotient à partir de zéro, vous pouvez copier quotest/CMakeLists.txt à votre projet et changer quotest au nom de votre projet. Si vous avez déjà une ligne CMakelists.txt existante, vous devez insérer une ligne find_package(Quotient REQUIRED) à un endroit approprié (utilisez find_package(Quotient) si libquotient n'est pas une dépendance difficile pour vous) puis ajoutez Quotient à votre ligne target_link_libraries() .
La liaison dynamique n'est testée que sur Linux pour le moment et est le moyen recommandé de lier avec LibQuoient sur cette plate-forme. La liaison statique est la valeur par défaut sur Windows / MacOS; N'hésitez pas à expérimenter la liaison dynamique et à fournir des commentaires avec vos résultats.
Un aperçu (très basique) peut être trouvé sur la page Wiki respective. La documentation de Doxygen pour la bibliothèque se trouve sur https://quotient-im.github.io/libquotient/. Plus loin, en regardant le code source de Quotest - l'application de test fournie avec libquotient - peut vous aider avec les cas d'utilisation les plus courants tels que l'envoi de messages, le téléchargement de fichiers, la définition de l'état de la salle, etc.
Pour des exemples et des modèles d'utilisation plus étendue, n'hésitez pas à consulter (et à copier, avec une attribution appropriée), le code source de Quaternion (le client de référence pour libquotient) ou Neochat.
Depuis le quotient 0.7.2, les symboles dans tous les fichiers d'en-tête de libquotient , sauf les fichiers se terminant par _p.h et l'espace de noms _impl sont considérés comme publics et couverts par des garanties de stabilité API / ABI. Plus précisément, l'API et l'ABI sont compatibles en arrière dans chaque version mineure (0,7.x versions) avec chaque version mineure suivante (0,8, par exemple) brisant la compatibilité. Une fois que nous aurons atteint 1.0, cette règle s'appliquera à la version principale, s'alignant avec les règles de versioning sémantique. *_p.h Les fichiers et l'espace de noms _impl ne sont pas couverts par ces garanties; Le code client ne doit pas inclure directement ces fichiers, ni utiliser des symboles définis dans ces emplacements.
Sur les plates-formes autres que Linux, vous devrez construire vous-même Libquotient avant l'utilisation - personne ne l'a emballé jusqu'à présent (les contributions sont les bienvenues!). Vous pouvez également créer la bibliothèque sur Linux si vous avez besoin d'une version ou d'un instantané plus récent que celui qui arrive dans votre distribution.
Le code source est chez GitHub. La vérification d'un certain commit ou tag (plutôt que de télécharger l'archive) avec des sous-modules est fortement recommandé. Si vous souhaitez pirater la bibliothèque dans le cadre d'un autre projet (par exemple, vous travaillez sur Quaternion mais que vous devez apporter des modifications au code de la bibliothèque), il est logique de faire une vérification récursive de ce projet (dans ce cas, Quaternion) et de mettre à jour le sous-module de la bibliothèque (également récursivement) dans la branche appropriée. Soyez conscient des restrictions de compatibilité des API: par exemple, chaque version du quaternion peut nécessiter la branche spécifique du libquotient ( 0.8.x , 0.9.x etc.).
Les balises composées uniquement de chiffres et de fullstops (par exemple, 0.7.0 ) correspondent aux versions libérées; Tags se terminant par -betaN ou -rcN marque les pré-sorties respectives. Si / lorsque l'emballage pré-relance, il est conseillé de remplacer le leader - par ~ (Tilde).
Libquotient est un projet classique basé sur CMake; En supposant que les dépendances sont en place, les commandes suivantes émises dans le répertoire racine des sources de projet:
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all Vous obtiendra une bibliothèque compilée dans build (assurez-vous qu'il existe avant de courir). Tout IDE C ++ qui fonctionne avec CMake devrait être en mesure de faire de même avec un effort de configuration minimal.
Les versions statiques sont testées sur toutes les plateformes prises en charge. Les bibliothèques dynamiques sont la configuratiion recommandée sur Linux; Probablement réalisable sur les macOS; et non testé sur Windows (vous êtes les bienvenus pour essayer de faire rapport sur les résultats).
Avant de procéder, revérifiez que vous avez installé des bibliothèques de développement pour toutes les conditions préalables ci-dessus. CMake s'arrêtera et vous dira si quelque chose manque.
La première invocation CMake ci-dessus configure la version. Vous pouvez transmettre des variables Cmake (telles que -DCMAKE_PREFIX_PATH="path1;path2;..." et -DCMAKE_INSTALL_PREFIX=path ) à cette invocation si nécessaire. CMake Documentation (Choisissez la version CMake en haut de la page que vous utilisez) décrit les variables standard à venir avec CMake. En plus d'eux, Quotient comprend:
Quotient_INSTALL_TESTS=<ON/OFF> , ON par défaut - installer quotest avec les fichiers de bibliothèque lorsque install de la cible est invoquée. quotest est un petit programme de ligne de commande qui (en supposant des paramètres corrects, voir quotest --help ) qui essaie de se connecter à une pièce donnée en tant qu'utilisateur donné et d'effectuer des opérations de matrice de base, telles que l'envoi de messages et de petits fichiers, la rédaction, la définition de balises de salle, etc.MATRIX_SPEC_PATH et GTAD_PATH - Ces deux variables sont utilisées pour pointer CMake au répertoire avec le référentiel Matrix-Doc contenant des fichiers API et pour un binaire GTAD. Ces deux sont utilisés pour générer des fichiers C ++ à partir de Matrix Client-Server API Description Fabriquée en notation OpenAPI. Ce n'est pas nécessaire si vous avez juste besoin de construire la bibliothèque; Si vous êtes vraiment dans le piratage, veuillez lire les sections respectives dans contribution.md et code_generation.md.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , OFF par défaut (notez que le quotient est dans les <top-level include prefix>/Quotient/ ici, contrairement #include <Quotient/header.h> options ci-dessus) - lorsque cette option est définie sur ON , CMake Skips ajoutant #include <header.h> Par défaut, cela est défini sur la compatibilité vers l' OFF ; Finalement, cette valeur par défaut peut / changera, il est donc recommandé d'ajouter au moins occasionnellement -DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1 à une invocation CMake (ou de définir la variable dans votre IDE) et de vous assurer que votre code a des chemins préfixés.Vous pouvez installer la bibliothèque avec CMake:
cmake --build . --target install Cela installera également les fichiers de configuration du package Cmake; Une fois cela fait, vous devriez pouvoir utiliser quotest/CMakeLists.txt pour compiler Quotest avec la bibliothèque installée . Comme mentionné ci-dessus, l'installation du binaire quotest avec le reste de la bibliothèque peut être ignorée en définissant Quotient_INSTALL_TESTS à OFF .
Si cmake échoue avec
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.
Ensuite, vous devez définir la variable droite -DCMAKE_PREFIX_PATH , voir ci-dessus.
Si cmake échoue avec un message similaire à:
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
Ensuite, vous avez probablement à la fois Qt 5 et Qt 6 sur votre système, et votre code utilise une version majeure différente de QT que Quotient. Assurez-vous de configurer la version afin que la même version de QT majeure soit utilisée à la fois par LibQuoient et votre code.
Libquotient utilise les catégories de journalisation de QT pour faciliter la commutation de certains types de journalisation. En cas de problèmes à l'exécution (bogues, plantages), vous pouvez augmenter la journalisation si vous ajoutez ce qui suit à la variable d'environnement QT_LOGGING_RULES :
quotient.<category>.<level>=<flag>
où
<category> est l'une des: main , jobs , jobs.sync profiler jobs.thumbnail , events , events.state (couvrant à la fois les données "habituelles" de Quotient/logging_categories_p.h salle et network compte), les events.members , events.messages , events.ephemeral e2ee database ;<level> est l'un des debug , info et warning ;<flag> est true ou false . Vous pouvez utiliser * (astérisque) comme un joker pour n'importe quelle partie entre deux points, et le point-virgule est utilisé pour un séparateur. Ces derniers instructions remplacent les anciens, donc si vous souhaitez activer tous les journaux de débogage, sauf jobs vous pouvez définir QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"
Vous pouvez également définir QT_MESSAGE_PATTERN pour rendre les journaux légèrement plus informatifs (voir https://doc.qt.io/qt-6/qtlogging.html#qsetMessagePattern pour la description du format). Pour donner un exemple, voici ce que l'un des développeurs de la bibliothèque utilise pour 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}`
(Les %{if} sont simplement encodant le niveau de journalisation dans sa lettre initiale).
En cas de problèmes avec l'état de la salle et la mise en cache, il peut être utile de passer au format de cache de CBOR binaire à JSON en texte clair. Pour ce faire, définissez la touche libQuotient/cache_type dans le fichier / registre de configuration de votre client à json (vous devrez peut-être créer le groupe LibQotient car c'est la seule clé reconnue jusqu'à présent). Cela rendra la sauvegarde et le chargement du cache qui fonctionnent légèrement plus lentement, mais le cache sera dans des fichiers JSON de texte (très longs et sans indentation; préparez un bon spectateur JSON ou un éditeur de texte avec des capacités de formatage JSON).
