libQuotient
0.9.1
El proyecto del cociente tiene como objetivo producir un SDK basado en QT para desarrollar aplicaciones para Matrix. Libquotient es una biblioteca que permite aplicaciones de clientes. Es la columna vertebral de Quaternion, Neochat y otros proyectos.
Puede encontrar desarrolladores de cocientes en la sala Matrix: #Quotient: matrix.org.
Puede presentar problemas en el rastreador de problemas del proyecto. Si encuentra lo que parece un problema de seguridad, utilice las instrucciones en Security.md.
Dependiendo de su plataforma, la biblioteca se puede obtener de un sistema de administración de paquetes. Lanzamientos recientes de Fedora, Debian y OpenSuse ya lo tienen. Alternativamente, puede construir la biblioteca a partir de la fuente y agruparla con su aplicación, como se describe a continuación.
Para usar libquotient (es decir, construir o ejecutar aplicaciones con él), necesitará:
Para crear aplicaciones con libquotient, también necesitará:
Los requisitos para construir libquotient en sí son básicamente los mismos, excepto que debe instalar bibliotecas de desarrollo para las dependencias enumeradas anteriormente.
Simplemente instale los requisitos previos con su administrador de paquetes preferido. Si su base de paquete QT tiene un grano fino, es posible que desee ejecutar CMake y mirar los mensajes de error. La biblioteca está completamente fuera de pantalla; Sin embargo, aparte de Qtcore y Qtnetwork, también depende de Qtgui para manejar miniaturas Avatar, sin ningún dibujo en pantalla.
brew install qt qtkeychain libolm openssl@3 debería obtener las versiones más recientes de las bibliotecas de tiempo de ejecución.
Es posible que deba agregar $(brew --prefix qt) , $(brew --prefix qtkeychain) etc. a CMAKE_PREFIX_PATH (ver más abajo) para que CMake sepa de las ubicaciones de la biblioteca.
Instalar QT y OpenSSL utilizando el instalador oficial del proyecto QT; Asegúrese de marcar también la casilla CMake en la lista de componentes para instalar a menos que ya lo tenga. Esto le brindará tanto las bibliotecas de tiempo de ejecución como los archivos de desarrollo, que también son adecuados para construir libquotient en sí. Si vas de esta manera, tendrás que construir QtKeyChain del código fuente.
Alternativamente, puede usar VCPKG para instalar QT, OpenSSL y QtKeyChain. En ese caso, no está obteniendo QT Creator, que es un IDE muy agradable para tratar con proyectos basados en QT; Pero si ya usa VScode o Clion, puede preferir esta ruta. También puede mezclar y combinar, instalar QT Creator desde el instalador oficial y el resto desde VCPKG. Mezclar QT del instalador oficial con el llavero QT de VCPKG puede o no funcionar, dependiendo de la versión QT utilizada para construir el llavero QT.
Si se construye desde la línea de comando : los comandos en más secciones implican que cmake está en su PATH , de lo contrario tiene que preparar esos comandos con rutas reales. Es una buena idea ejecutar el script qtenv2.bat que se puede encontrar en C:Qt<Qt version><toolchain>bin (suponiendo que haya instalado Qt a C:Qt ). Este script agrega las rutas necesarias a PATH . Es posible que no desee ejecutar ese script en el inicio del sistema, pero es muy útil configurar el entorno antes de construir.
Si usa un IDE C ++ : debería poder configurar la ruta Cmake y las opciones adicionales ( CMAKE_PREFIX_PATH , en particular) en su configuración. Se recomienda no agregar la ruta para Qt (o cualquier otra biblioteca) a PATH explícitamente; Use CMAKE_PREFIX_PATH en su lugar y deje PATH sin cambios. Si su IDE es QT Creator, no debe necesitar lidiar con los caminos QT, simplemente elija el kit correcto y vaya directamente al edificio.
También necesitarás libolm. Tendrá que construirlo usted mismo: no hay binario para Windows que pueda descargar desde VCPKG o en otro lugar, a partir de este escrito. El código fuente está disponible en https://gitlab.matrix.org/matrix-org/olm; Puede usar la misma cadena de herramientas (CMake+MSVC, EG) que para el resto del cociente.
Si recién está comenzando un proyecto usando libquotient desde cero, puede copiar quotest/CMakeLists.txt a su proyecto y cambiar quotest al nombre de su proyecto. Si ya tiene un cmakelists.txt existente, debe insertar una línea find_package(Quotient REQUIRED) en un lugar apropiado en él (use find_package(Quotient) si LibQuotient no es una dependencia difícil para usted) y luego agregue Quotient a su línea target_link_libraries() .
El enlace dinámico solo se prueba en Linux en este momento y es la forma recomendada de vincular con libquotient en esta plataforma. El enlace estático es el valor predeterminado en Windows/MacOS; Siéntase libre de experimentar con la vinculación dinámica y proporcionar comentarios con sus resultados.
Se puede encontrar una descripción (muy básica) en la página wiki respectiva. La documentación de Doxygen para la biblioteca se puede encontrar en https://quotient-im.github.io/libquotient/. Más adelante, observar el código fuente para Cotest, la aplicación de prueba que viene con libquotient, puede ayudarlo con los casos de uso más comunes, como enviar mensajes, cargar archivos, configurar el estado de la habitación, etc.
Para ver ejemplos y patrones de uso más extenso, no dude en visitar (y copiar, con una atribución apropiada) el Código fuente de Cuaternion (el cliente de referencia para libquotient) o Neochat.
Desde el cociente 0.7.2, los símbolos en todos los archivos de encabezado de libquotient , excepto los archivos que terminan con _p.h y el espacio de nombres _impl se consideran públicos y cubiertos por las garantías de estabilidad API/ABI. Específicamente, la API y ABI son compatibles con versiones anteriores dentro de cada versión menor (0.7.X versiones) con cada próxima versión menor (0.8, por ejemplo) que rompen la compatibilidad. Una vez que llegamos a 1.0, esta regla se aplicará a la versión principal, alineándose con las reglas de versiones semánticas. *_p.h Los archivos y el espacio de nombres _impl no están cubiertos por estas garantías; El código del cliente no debe incluir directamente estos archivos, ni usar símbolos definidos en estas ubicaciones.
En plataformas distintas de Linux, tendrá que construir libquotient usted mismo antes del uso, ¡nadie lo empaquetó hasta ahora (¡Contribuciones bienvenidas!). También es posible que desee construir la biblioteca en Linux si necesita una versión o instantánea más nueva que la que viene en su distribución.
El código fuente está en GitHub. Se recomienda verificar una cierta confirmación o etiqueta (en lugar de descargar el archivo) junto con submódulos. Si desea piratear la biblioteca como parte de otro proyecto (por ejemplo, está trabajando en Quaternion pero necesita hacer algunos cambios en el código de la biblioteca), tiene sentido hacer una verificación recursiva de ese proyecto (en este caso, Cuaternion) y actualizar el submódulo de la biblioteca (también recursivamente) dentro de la rama apropiada. Tenga en cuenta las restricciones de compatibilidad de API: por ejemplo, cada versión de Cuaternion puede requerir la rama específica de Libquotient ( 0.8.x , 0.9.x , etc.).
Las etiquetas que consisten únicamente en dígitos y pistas completas (por ejemplo, 0.7.0 ) corresponden a versiones liberadas; Las etiquetas que terminan con -betaN o -rcN marcan los respectivos pre -lanzamientos. Si/cuando se empaqueta previos, se recomienda reemplazar el líder - con ~ (tilde).
Libquotient es un proyecto clásico basado en Cmake; Suponiendo que las dependencias estén en su lugar, los siguientes comandos emitidos en el directorio raíz de las fuentes del proyecto:
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all Le dará una biblioteca compilada en build (asegúrese de que exista antes de ejecutar). Cualquier IDE de C ++ que funcione con CMake debería poder hacer lo mismo con un esfuerzo de configuración mínimo.
Las construcciones estáticas se prueban en todas las plataformas compatibles. Las bibliotecas dinámicas son la configuración recomendada en Linux; probablemente viable en macOS; y no probado en Windows (puede intentar informar sobre los resultados).
Antes de continuar, verifique que haya instalado bibliotecas de desarrollo para todos los requisitos previos anteriores. Cmake se detendrá y le dirá si algo falta.
La primera invocación de CMake anterior configura la compilación. Puede pasar variables Cmake (como -DCMAKE_PREFIX_PATH="path1;path2;..." y -DCMAKE_INSTALL_PREFIX=path ) a esa invocación si es necesario. La documentación de CMake (elija la versión Cmake en la parte superior de la página que usa) describe las variables estándar que vienen con CMake. Además de ellos, el cociente entiende:
Quotient_INSTALL_TESTS=<ON/OFF> , ON de forma predeterminada - Instale quotest junto con los archivos de la biblioteca cuando se invoca el destino install . quotest es un pequeño programa de línea de comandos que (suponiendo parámetros correctos, ver quotest --help ) que intenta conectarse a una habitación determinada como un usuario determinado y realizar algunas operaciones básicas de matriz, como enviar mensajes y archivos pequeños, redacciones, etiquetas de configuración, etc. Esto es útil para verificar la cordura de la instalación de su biblioteca.MATRIX_SPEC_PATH y GTAD_PATH : estas dos variables se utilizan para apuntar CMake al directorio con el repositorio de matriz -doc que contiene archivos API y a un binario GTAD. Estos dos se utilizan para generar archivos C ++ a partir de la descripción de la API del servidor de clientes de matriz hecha en la notación de OpenApi. Esto no es necesario si solo necesita construir la biblioteca; Si realmente le gusta piratearlo, lea las secciones respectivas en contribuyentes. MD y code_generation.md.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , OFF de forma predeterminada (tenga en cuenta que el cociente está en Caps aquí, a diferencia de las opciones anteriores): cuando esta opción está ON , CMake omita la adición de <top-level include prefix>/Quotient/ para incluir rutas, lo que obliga al código del cliente a usar #include <Quotient/header.h> en lugar de prefabricado #include <header.h> . Por defecto, esto se establece en OFF para la compatibilidad con versiones anteriores; Eventualmente, este valor predeterminado puede/cambiará, por lo que se recomienda agregar al menos ocasionalmente -DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1 a una invocación CMake (o establecer la variable en su IDE) y asegurarse de que su código tenga rutas prefijadas.Puede instalar la biblioteca con cmake:
cmake --build . --target install Esto también instalará archivos de configuración del paquete Cmake; Una vez hecho esto, debería poder usar quotest/CMakeLists.txt para compilar el cotest con la biblioteca instalada . Como se mencionó anteriormente, la instalación del binario quotest junto con el resto de la biblioteca se puede omitir configurando Quotient_INSTALL_TESTS en OFF .
Si cmake falla con
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.
Luego debe establecer la variable right -DCMAKE_PREFIX_PATH , ver arriba.
Si cmake falla con un mensaje similar a:
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
Entonces es probable que tenga QT 5 y QT 6 en su sistema, y su código utiliza una versión principal diferente de Qt que el cociente. Asegúrese de configurar la compilación para que la misma versión de QT sea utilizada tanto por LibQuotient como por su código.
Libquotient utiliza las categorías de registro de QT para facilitar el cambio de ciertos tipos de registro. En el caso de los problemas en tiempo de ejecución (errores, bloqueos), puede aumentar el registro si agrega lo siguiente a la variable de entorno QT_LOGGING_RULES :
quotient.<category>.<level>=<flag>
dónde
<category> es uno de: main , jobs , jobs.sync , jobs.thumbnail , events , events.state (que cubre tanto el estado de la habitación "habitual"), events.members , events.messages , events.ephemeral , database , network , e2ee y profiler y el perfil siempre puede encontrar la lista completa en Quotient/logging_categories_p.h ;h;<level> es uno de debug , info y warning ;<flag> es true o false . Puede usar * (asterisco) como comodín para cualquier parte entre dos puntos, y se usa semicolon para un separador. Las últimas declaraciones anulan las antiguas, por lo que si desea encender todos los registros de depuración, excepto jobs puede establecer QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"
También es posible que desee establecer QT_MESSAGE_PATTERN para hacer registros un poco más informativos (consulte https://doc.qt.io/qt-6/qtlogging.html#qsetmessagepattern para la descripción del formato). Para dar un ejemplo, esto es lo que uno de los desarrolladores de la biblioteca usa para 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}`
(El %{if} s solo está codificando el nivel de registro en su letra inicial).
En caso de problemas con el estado de la habitación y el almacenamiento en caché, puede ser útil cambiar el formato de caché de CBOR binario a JSON de texto sin formato. Para hacer eso, establezca la tecla libQuotient/cache_type en el archivo/registro de configuración de su cliente a json (es posible que necesite crear el grupo libquotient, ya que es la única clave reconocida hasta ahora). Esto hará que el ahorro de caché y la carga funcionen un poco más lento, pero el caché estará en archivos JSON de texto (muy largo y sin sangría; prepare un buen espectador JSON o editor de texto con capacidades de formato JSON).
