libQuotient
0.9.1
Коэффициент проекта направлена на создание SDK на основе QT для разработки приложений для матрицы. Libquotient - это библиотека, которая позволяет клиентским приложениям. Это основание кватерниона, неохата и других проектов.
Вы можете найти активных разработчиков в комнате Матрицы: #quotient: matrix.org.
Вы можете подать проблемы на The Project Tracker. Если вы найдете то, что выглядит как проблема безопасности, используйте инструкции в Security.md.
В зависимости от вашей платформы, библиотеку можно получить из системы управления пакетами. Недавние выпуски Fedora, Debian и OpenSuse уже имеют его. В качестве альтернативы, вы можете построить библиотеку из источника и объединить ее с помощью вашего приложения, как описано ниже.
Чтобы использовать Libquotient (то есть создать или запустить приложения с ним), вам понадобится:
Для создания приложений с помощью Libquotient вам также понадобится:
Требования к созданию сама либкотента в основном одинаковы, за исключением того, что вы должны установить библиотеки разработки для зависимостей, перечисленных выше.
Просто установите предпосылки, используя ваш предпочтительный диспетчер пакетов. Если ваша база пакета QT является мелкозернистой, вы можете запустить Cmake и посмотреть на сообщения об ошибках. Библиотека полностью за кадром; Однако, помимо QTCore и QTnetwork, это также зависит от QTGUI, чтобы обрабатывать аватарские миниатюры, без какого-либо экрана.
brew install qt qtkeychain libolm openssl@3 должен получить вам самые последние версии библиотек времени выполнения.
Возможно, вам придется добавить $(brew --prefix qt) , $(brew --prefix qtkeychain) и т. Д. В CMAKE_PREFIX_PATH (см. Ниже), чтобы CMAKE знал о местах библиотеки.
Установите QT и OpenSSL, используя официальный установщик проекта QT; Убедитесь, что также отметите поле Cmake в списке компонентов для установки, если у вас его уже нет. Это даст вам как библиотеки времени выполнения, так и файлы разработки, которые также подходят для создания самого Libquotient. Если вы пойдете таким образом, вам придется создать QTKeyChain из исходного кода.
В качестве альтернативы, вы можете использовать VCPKG для установки QT, OpenSSL и QtKeyChain. В этом случае вы не получаете QT Creator, который является очень хорошей идеей для работы с проектами на основе QT; Но если вы уже используете VSCODE или Clion, вы можете предпочесть этот маршрут. Вы также можете смешать и сочетать, установить QT Creator из официального установщика, а остальные из VCPKG. Смешивание QT из официального установщика с QT -ключом из VCPKG может работать или не работать, в зависимости от версии QT, используемой для построения QT -чайного матча.
Если вы строите из командной строки : команды в дальнейших разделах подразумевают, что cmake находится на вашем PATH , в противном случае вы должны предположить эти команды с помощью реальных путей. Это хорошая идея, чтобы запустить сценарий qtenv2.bat , который можно найти в C:Qt<Qt version><toolchain>bin (при условии, что вы установили qt в C:Qt ). Этот скрипт добавляет необходимые пути к PATH . Возможно, вы не захотите запускать этот скрипт на запуск системы, но очень удобно настроить окружающую среду перед строительством.
Если вы используете C ++ IDE : вы сможете настроить путь Cmake и дополнительные параметры (в частности, CMAKE_PREFIX_PATH ) в его настройках. Рекомендуется не добавлять путь для QT (или любой другой библиотеки) к PATH явно; Вместо этого используйте CMAKE_PREFIX_PATH и оставьте PATH без изменений. Если ваша IDE является создателем QT, вам вообще не нужно иметь дело с QT Paths, просто выберите правильный комплект и отправляйтесь прямо к зданию.
Вам также понадобится 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) , если либекотентный не является жесткой зависимостью для вас), а затем добавьте Quotient вашей линии target_link_libraries() .
Динамическое связывание в настоящее время тестируется только на Linux и является рекомендуемым способом связи с Libquotient на этой платформе. Статическое связывание - это по умолчанию в Windows/MacOS; Не стесняйтесь экспериментировать с динамическим связыванием и обеспечить обратную связь с вашими результатами.
Обзор (очень простой) можно найти на соответствующей странице вики. Доксеносную документацию для библиотеки можно найти по адресу https://quotient-im.github.io/libquotient/. Далее, рассмотрение исходного кода для Quotest - тестового приложения, которое поставляется с Libquotient - может помочь вам с наиболее распространенными вариантами использования, такими как отправка сообщений, загрузка файлов, установка состояния комнаты и т. Д.
Для примеров и моделей более обширного использования не стесняйтесь проверять (и копировать, с соответствующей атрибуцией) исходный код кватерниона (контрольный клиент для Libquotient) или Neochat.
Поскольку коэффициент 0.7.2, символы во всех файлах заголовков Libquotient , за исключением файлов, заканчивающихся _p.h и пространства имен _impl считаются публичными и охватываются гарантиями стабильности API/ABI. В частности, API и ABI совместимы в каждой незначительной версии (0,7.x выпуска) с каждой следующей второстепенной версией (0,8, например), нарушающей совместимость. Как только мы достигнем 1.0, это правило будет применяться к основной версии, соответствующей правилам семантических версий. *_p.h файлы и пространство имен _impl не покрываются этими гарантиями; Клиентский код не должен напрямую включать эти файлы и использовать символы, определенные в этих местах.
На платформах, отличных от Linux, вам придется создать либеотенцию до использования - до сих пор никто не упаковал (взносы приветствуются!). Вы также можете построить библиотеку на Linux, если вам нужна более новая версия или снимок, чем в вашем дистрибутивах.
Исходный код находится в GitHub. Настоятельно рекомендуется проверить определенный коммит или тег (а не загружать архив) вместе с подмодулями. Если вы хотите взломать библиотеку как часть другого проекта (например, вы работаете над Quaternion, но вам нужно внести некоторые изменения в код библиотеки), имеет смысл провести рекурсивную проверку этого проекта (в данном случае, Quaternion) и обновлять подставку библиотеки (также рекурсивно) в соответствующей филиале. Будьте внимательны к ограничениям совместимости API: например, каждая версия Quaternion может потребовать специфической ветви Libquotient ( 0.8.x , 0.9.x и т. Д.).
Теги, состоящие исключительно из цифр и полномочий (например, 0.7.0 ), соответствуют выпущенным версиям; Теги, заканчивающиеся -betaN или -rcN отмечают соответствующие предварительные излучения. Если/при упаковке предварительных отменений рекомендуется заменить ведущий - ~ (Тильде).
Libquotient-это классический проект на основе Cmake; Предполагая, что зависимости существуют, следующие команды, выпущенные в корневом каталоге источников проекта:
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all Принесет вам скомпилированную библиотеку в build (убедитесь, что она существует перед запуском). Любой IDE C ++, который работает с Cmake, должен иметь возможность сделать то же самое с минимальными усилиями по конфигурации.
Статические сборки тестируются на всех поддерживаемых платформах. Динамические библиотеки - это рекомендуемая конфигурация на Linux; Вероятно, работоспособность на macOS; и непроверенный в Windows (вы можете попытаться сообщить о результатах).
Прежде чем продолжить, дважды проверьте, что вы установили библиотеки разработчиков для всех предварительных условий выше. Cmake остановится и скажет вам, что чего -то не хватает.
Первый вызов Cmake выше настраивает сборку. Вы можете передать переменные cmake (например, -DCMAKE_PREFIX_PATH="path1;path2;..." и -DCMAKE_INSTALL_PREFIX=path ) к этому вызова, если это необходимо. Документация CMAKE (выберите версию CMAKE в верхней части страницы, которую вы используете) описывает стандартные переменные, поставляемые с CMAKE. Вдобавок к ним, COTIENT понимает:
Quotient_INSTALL_TESTS=<ON/OFF> , по ON - Установите quotest вместе с файлами библиотеки при install Target Target. quotest -это небольшая программа командной строки, которая (при условии правильных параметров см. quotest --help ), которая пытается подключиться к данной комнате в качестве данного пользователя и выполнить некоторые основные операции матрицы, такие как отправка сообщений и небольших файлов, редакция, настройка тегов комнаты и т. Д.MATRIX_SPEC_PATH и GTAD_PATH - эти две переменные используются для указания Cmake на каталог с репозиторием Matrix -DOC, содержащим файлы API, и в двоичный файл GTAD. Эти два используются для генерации файлов C ++ из Matrix Client-Server API описания, сделанного в нотации OpenAPI. Это не нужно, если вам просто нужно построить библиотеку; Если вы действительно хотите взломать это, пожалуйста, прочитайте соответствующие разделы в ancom.md и code_generation.md.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , OFF по умолчанию (обратите внимание на то, что коэффициент здесь находится в CAPS, в отличие от вариантов выше) - Когда эта опция ON , Cmake Specips Добавление <top-level include prefix>/Quotient/ для включения пути, тем самым заставляя код клиента, чтобы использовать #include <Quotient/header.h> #include <header.h> исторического согласия. По умолчанию это OFF для обратной совместимости; В конечном итоге это может измениться по умолчанию, поэтому рекомендуется, по крайней мере, иногда добавлять -DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1 к вызову Cmake (или установите переменную в вашем IDE) и убедитесь, что ваш код имеет префиксированные пути.Вы можете установить библиотеку с Cmake:
cmake --build . --target install Это также установит файлы конфигурации пакета Cmake; Как только это будет сделано, вы сможете использовать quotest/CMakeLists.txt для компиляции котирования с установленной библиотекой. Как упомянуто выше, установка двоичного quotest вместе с остальной частью библиотеки может быть пропущена, установив Quotient_INSTALL_TESTS для OFF .
Если 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, чем коэффициент. Убедитесь, что вы настроили сборку так, чтобы одна и та же основная версия QT использовалась как Libquotient, так и вашим кодом.
Libquotient использует категории журнала QT для облегчения переключения определенных типов журнала. В случае неприятностей во время выполнения (ошибки, сбои) вы можете увеличить ведение журнала, если добавите следующее в переменную среды QT_LOGGING_RULES :
quotient.<category>.<level>=<flag>
где
<category> events.messages events.members events.ephemeral network : main e2ee jobs , jobs.sync profiler jobs.thumbnail , events Quotient/logging_categories_p.h events.state database<level> - это один из debug , info и warning ;<flag> является либо true , либо false . Вы можете использовать * (звездочку) в качестве подстановочного знака для любой части между двумя точками, а полуколон используется для сепаратора. Последние утверждения переопределяют прежние, поэтому, если вы хотите включить все журналы отладки, кроме jobs вы можете установить QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"
Вы также можете захотеть установить 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).
