libQuotient
0.9.1
O projeto quociente tem como objetivo produzir um SDK baseado em QT para desenvolver aplicativos para Matrix. O Libquotient é uma biblioteca que permite aplicativos do cliente. É a espinha dorsal da quaternion, Neochat e outros projetos.
Você pode encontrar desenvolvedores quotientes na sala Matrix: #quotient: matrix.org.
Você pode arquivar problemas no rastreador de problemas do projeto. Se você encontrar o que parece ser um problema de segurança, use instruções em segurança.md.
Dependendo da sua plataforma, a biblioteca pode ser obtida em um sistema de gerenciamento de pacotes. Lançamentos recentes de Fedora, Debian e OpenSuse já o têm. Como alternativa, você pode construir a biblioteca a partir da fonte e agrupá -la com seu aplicativo, conforme descrito abaixo.
Para usar o Libquotient (ou seja, construir ou executar aplicativos), você precisará:
Para criar aplicativos com a libquotient, você também precisará:
Os requisitos para construir a própria libquetient são basicamente os mesmos, exceto que você deve instalar bibliotecas de desenvolvimento para as dependências listadas acima.
Basta instalar os pré -requisitos usando o seu gerenciador de pacotes preferido. Se a sua base de pacote QT estiver com grão fino, você poderá executar o cmake e examinar as mensagens de erro. A biblioteca é totalmente fora da tela; No entanto, além do QTCore e da QtNetwork, também depende do Qtgui para lidar com miniaturas de avatar, sem nenhum desenho na tela.
brew install qt qtkeychain libolm openssl@3 Deve obter as versões mais recentes das bibliotecas de tempo de execução.
Você pode precisar adicionar $(brew --prefix qt) , $(brew --prefix qtkeychain) etc. para CMAKE_PREFIX_PATH (veja abaixo) para conscientizar o cmake dos locais da biblioteca.
Instalar QT e OpenSSL usando o instalador oficial do Projeto QT; Certifique -se de marcar também a caixa CMake na lista de componentes para instalar, a menos que você já o tenha. Isso levará a você as bibliotecas de tempo de execução e os arquivos de desenvolvimento, que também são adequados para criar o próprio Libquotient. Se você for assim, terá que criar o QTKEYCHAIN a partir do código -fonte.
Como alternativa, você pode usar o VCPKG para instalar QT, OpenSSL e QTKEYCHAIN. Nesse caso, você não está recebendo o QT Creator, que é um IDE muito bom para lidar com projetos baseados em QT; Mas se você já usa o VSCode ou o Clion, pode preferir essa rota. Você também pode misturar e combinar, instalando o QT Creator no instalador oficial e o restante do VCPKG. Mistura o QT do instalador oficial com o qt Keychain do VCPKG pode ou não funcionar, dependendo da versão QT usada para criar o qt Keychain.
Se você construir a partir da linha de comando : os comandos em outras seções implicam que cmake está no seu PATH , caso contrário, você precisará prender esses comandos com caminhos reais. É uma boa ideia executar o script qtenv2.bat que pode ser encontrado em C:Qt<Qt version><toolchain>bin (assumindo que você instalou Qt para C:Qt ). Este script adiciona os caminhos necessários ao PATH . Você pode não querer executar esse script na inicialização do sistema, mas é muito útil configurar o ambiente antes de criar.
Se você usar um IDE C ++ : poderá configurar o caminho do CMake e as opções extras ( CMAKE_PREFIX_PATH , em particular) em suas configurações. Recomenda -se não adicionar o caminho para QT (ou qualquer outra biblioteca) para PATH explicitamente; Use CMAKE_PREFIX_PATH e deixe PATH inalterado. Se o seu IDE é o QT Creator, você não precisará lidar com os caminhos QT, basta escolher o kit certo e ir direto para a construção.
Você também precisará de libolmo. Você terá que construí -lo sozinho - não há binário para o Windows que você possa baixar do VCPKG ou em outro lugar, até o momento em que este artigo foi escrito. O código-fonte está disponível em https://gitlab.matrix.org/matrix-org/olm; Você pode usar a mesma cadeia de ferramentas (cmake+msvc, por exemplo) quanto para o restante do quociente.
Se você está apenas iniciando um projeto usando o libquotient do zero, pode copiar quotest/CMakeLists.txt para o seu projeto e alterar quotest para o nome do seu projeto. Se você já possui um cmakelists.txt existente, precisa inserir uma linha find_package(Quotient REQUIRED) em um lugar apropriado nele (use find_package(Quotient) se libquotient não for uma rigidez para você) e adicione Quotient à sua linha target_link_libraries() .
A ligação dinâmica é testada apenas no Linux no momento e é a maneira recomendada de vincular a Libquotient nesta plataforma. A ligação estática é o padrão no Windows/MacOS; Sinta -se à vontade para experimentar a ligação dinâmica e fornecer feedback com seus resultados.
Uma visão geral (muito básica) pode ser encontrada na respectiva página do Wiki. A documentação doxygen para a biblioteca pode ser encontrada em https://quotient-im.github.io/libquotient/. Mais adiante, analisar o código -fonte do Questest - o aplicativo de teste que vem com a libquotient - pode ajudá -lo com casos de uso mais comuns, como enviar mensagens, fazer upload de arquivos, definir o estado da sala etc.
Para exemplos e padrões de uso mais extenso, sinta -se à vontade para conferir (e copiar, com atribuição apropriada) o código -fonte de quaternion (o cliente de referência para libquotient) ou neochat.
Como o quociente 0.7.2, os símbolos em todos os arquivos de cabeçalho do libquotient , exceto os arquivos que terminam com _p.h e namespace _impl são considerados públicos e cobertos pelas garantias de estabilidade da API/ABI. Especificamente, a API e a ABI são compatíveis com versões anteriores em todas as versões menores (0.7.x libera) com todas as próximas versões menores (0,8, por exemplo) quebrando a compatibilidade. Quando chegarmos a 1.0, essa regra se aplicará à versão principal, alinhando -se às regras de versão semântica. *_p.h Arquivos e namespace _impl não são cobertos por essas garantias; O código do cliente não deve incluir diretamente esses arquivos, nem usar símbolos definidos nesses locais.
Nas plataformas que não sejam o Linux, você terá que construir o Lobquotient antes do uso - ninguém o empacotou até agora (as contribuições são bem -vindas!). Você também pode criar a biblioteca no Linux se precisar de uma versão ou instantâneo mais recente do que a que vem em sua distro.
O código -fonte está no GitHub. Verificar uma certa confirmação ou tag (em vez de baixar o arquivo) junto com os submódulos é fortemente recomendado. Se você deseja invadir a biblioteca como parte de outro projeto (por exemplo, você está trabalhando no Quaternion, mas precisa fazer algumas alterações no código da biblioteca), faz sentido fazer uma verificação recursiva desse projeto (neste caso, quaternion) e atualizar o submódulo da biblioteca (também recursivamente) dentro do ramo apropriado. Esteja atento às restrições de compatibilidade da API: por exemplo, cada versão do quaternion pode exigir o ramo específico do libquotient ( 0.8.x , 0.9.x etc.).
Tags consistindo apenas de dígitos e chiqueiros (por exemplo, 0.7.0 ) correspondem às versões liberadas; Tags terminando com -betaN ou -rcN MARCA respectivas pré -lançamentos. Se/Quando a embalagem pré -libera, é aconselhável substituir a liderança - por ~ (tilde).
Libquotient é um projeto clássico baseado em cmake; Supondo que as dependências estejam em vigor, os seguintes comandos emitidos no diretório raiz das fontes do projeto:
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all Vai obter uma biblioteca compilada no build (verifique se ela existe antes de executar). Qualquer IDE de C ++ que funcione com o CMake deve ser capaz de fazer o mesmo com o mínimo de esforço de configuração.
As construções estáticas são testadas em todas as plataformas suportadas. Bibliotecas dinâmicas são a configuração recomendada no Linux; Provavelmente viável no macOS; e não testado no Windows (você pode tentar relatar os resultados).
Antes de prosseguir, verifique se você instalou bibliotecas de desenvolvimento para todos os pré-requisitos acima. Cmake vai parar e dizer se algo está faltando.
A primeira invocação de cmake acima configura a construção. Você pode passar variáveis cmake (como -DCMAKE_PREFIX_PATH="path1;path2;..." e -DCMAKE_INSTALL_PREFIX=path ) para essa chamada, se necessário. A documentação do CMake (escolha a versão CMake na parte superior da página que você usa) descreve as variáveis padrão que vêm com o CMake. Em cima deles, o quociente entende:
Quotient_INSTALL_TESTS=<ON/OFF> , ON por padrão - Instale quotest junto com os arquivos da biblioteca quando install do destino é invocada. quotest é um pequeno programa de linha de comando que (assumindo parâmetros corretos, consulte quotest --help ) que tenta se conectar a uma determinada sala como um determinado usuário e executar algumas operações básicas de matriz, como enviar mensagens e arquivos pequenos, redação, tags de sala de estar etc. Isso é útil para verificar a sanidade da sua instalação da biblioteca.MATRIX_SPEC_PATH e GTAD_PATH - Essas duas variáveis são usadas para apontar o CMake para o diretório com o repositório da matriz -Doc contendo arquivos API e para um binário GTAD. Esses dois são usados para gerar arquivos C ++ a partir da API da Matrix Client-Server API, feita na notação OpenAPI. Isso não é necessário se você precisar apenas construir a biblioteca; Se você gosta muito de invadir, leia as respectivas seções em contribuindo.md e code_generation.md.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , OFF por padrão (observe que o quociente está em tampas aqui, diferentemente das opções acima) - quando esta opção estiver ON , o Cmake pula o número de clientes a serem usados #Include <top-level include prefix>/Quotient/ #include <Quotient/header.h> #include <header.h> . Por padrão, isso está definido para OFF para compatibilidade com versões anteriores; Eventualmente, esse padrão pode/será alterado para que seja recomendado pelo menos ocasionalmente adicionar -DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1 a uma invocação cmake (ou defina a variável no seu IDE) e verifique se seu código tem caminhos prefixados.Você pode instalar a biblioteca com cmake:
cmake --build . --target install Isso também instalará arquivos de configuração do pacote cmake; Uma vez feito isso, você poderá usar quotest/CMakeLists.txt para compilar citações com a biblioteca instalada . Como mencionado acima, a instalação do binário quotest , juntamente com o restante da biblioteca, pode ser ignorada configurando Quotient_INSTALL_TESTS para OFF .
Se cmake falhar com
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.
Então você precisa definir a variável -DCMAKE_PREFIX_PATH , consulte acima.
Se cmake falhar com uma mensagem semelhante 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
Então você provavelmente possui qt 5 e qt 6 no seu sistema, e seu código usa uma versão principal diferente do QT do que o quociente. Certifique -se de configurar a compilação para que a mesma versão principal do QT seja usada pelo Libquotient e seu código.
O Libquotient usa as categorias de registro do QT para facilitar a troca de certos tipos de registro. Em caso de problemas no tempo de execução (bugs, falhas), você pode aumentar o registro se adicionar o seguinte à variável de ambiente QT_LOGGING_RULES :
quotient.<category>.<level>=<flag>
onde
<category> é um dos: main , jobs , jobs.sync , jobs.thumbnail , events , events.state (cobrindo os dados do estado da sala e da sala "usuais"), events.members , events.messages , events.ephemeral , database , network , e2ee e profiler - você sempre pode encontrar a lista completa em Quotient/logging_categories_p.h .<level> é de debug , info e warning ;<flag> é true ou false . Você pode usar * (asterisco) como curinga para qualquer parte entre dois pontos, e o semicolon é usado para um separador. As últimas declarações substituem as anteriores, por isso, se você quiser ligar todos os registros de depuração, exceto jobs poderá definir QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"
Você também pode definir QT_MESSAGE_PATTERN para tornar os logs um pouco mais informativos (consulte https://doc.qt.io/qt-6/qtlogging.html#qSetMessagePattern para a descrição do formato). Para dar um exemplo, eis o que um dos desenvolvedores da 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}`
(O %{if} s está apenas codificando o nível de log em sua letra inicial).
Em caso de problemas com o estado da sala e o armazenamento em cache, pode ser útil alternar o formato de cache do binário CBOR para o texto sem formatação. Para fazer isso, defina a tecla libQuotient/cache_type no arquivo/registro de configuração do seu cliente como json (pode ser necessário criar o grupo libquotiente, pois é a única chave reconhecida nela até agora). Isso fará com que a economia e o carregamento de cache funcione um pouco mais lenta, mas o cache estará nos arquivos JSON de texto (muito longo e sem recuo; prepare um bom visualizador JSON ou editor de texto com recursos de formatação JSON).
