libQuotient
0.9.1
몫 프로젝트는 매트릭스에 대한 애플리케이션을 개발하기 위해 QT 기반 SDK를 생성하는 것을 목표로합니다. Libquotient는 클라이언트 애플리케이션을 가능하게하는 라이브러리입니다. Quaternion, Neochat 및 기타 프로젝트의 중추입니다.
매트릭스 룸에서 Quotient Developers를 찾을 수 있습니다 : #quotient : matrix.org.
프로젝트 문제 추적기에서 문제를 제출할 수 있습니다. 보안 문제처럼 보이는 것이 발견되면 Security.md에서 지침을 사용하십시오.
플랫폼에 따라 라이브러리는 패키지 관리 시스템에서 얻을 수 있습니다. 최근 Fedora, Debian 및 OpenSuse의 릴리스에는 이미 그것을 가지고 있습니다. 또는 아래에 설명 된대로 소스에서 라이브러리를 빌드하여 응용 프로그램과 함께 묶을 수 있습니다.
libquotient (즉, 응용 프로그램 빌드 또는 실행 응용 프로그램)를 사용하려면 다음을 필요로합니다.
Libquotient로 응용 프로그램을 구축하려면 다음과 같은 필요도 있습니다.
Libquotient 자체를 구축하기위한 요구 사항은 기본적으로 위에 나열된 종속성에 대한 개발 라이브러리를 설치해야한다는 점을 제외하고는 기본적으로 동일합니다.
선호하는 패키지 관리자를 사용하여 전제 조건을 설치하기 만하면됩니다. QT 패키지 기반이 세분화 된 경우 CMAKE를 실행하고 오류 메시지를 볼 수 있습니다. 라이브러리는 전적으로 화면을 벗어납니다. 그러나 QTCore 및 QTNetwork 외에도 화면 도면없이 아바타 썸네일을 처리하기 위해 QTGUI에도 의존합니다.
brew install qt qtkeychain libolm openssl@3 가장 최근의 런타임 라이브러리 버전을 얻을 수 있습니다.
CMAKE_PREFIX_PATH 라이브러리 위치를 알리기 위해 $(brew --prefix qt) , $(brew --prefix qtkeychain) 등을 추가해야 할 수도 있습니다.
QT 프로젝트 공식 설치 프로그램을 사용하여 QT 및 OpenSSL을 설치하십시오. CMAKE 상자를 이미 가지고 있지 않는 한 CMAKE 상자를 설치할 구성 요소 목록에서 체크하십시오. 이렇게하면 런타임 라이브러리와 개발 파일이 모두 제공되며 Libquotient 자체를 구축하는데도 적합합니다. 이런 식으로 가면 소스 코드에서 qtkeychain을 빌드해야합니다.
또는 VCPKG를 사용하여 QT, OpenSSL 및 QtkeyChain을 설치할 수 있습니다. 이 경우 QT 기반 프로젝트를 다루는 데 매우 좋은 IDE 인 QT Creator를 얻지 못합니다. 그러나 이미 VSCODE 또는 CLION을 사용하는 경우이 경로를 선호 할 수 있습니다. 공식 설치 프로그램과 VCPKG에서 QT 제작자를 설치하여 혼합 및 일치시킬 수도 있습니다. QT Keychain을 구축하는 데 사용되는 QT 버전에 따라 VCPKG의 QT Keychain과 공식 설치 프로그램의 QT를 믹스하는 것은 작동하거나 작동하지 않을 수도 있습니다.
명령 줄에서 빌드하는 경우 : 추가 섹션의 명령은 cmake PATH 에 있음을 의미합니다. 그렇지 않으면 해당 명령을 실제 경로로 준비해야합니다. C:Qt<Qt version><toolchain>bin 에서 찾을 수있는 qtenv2.bat 스크립트를 실행하는 것이 좋습니다 (qt를 C:Qt 에 설치했다고 가정). 이 스크립트는 PATH 에 필요한 경로를 추가합니다. 시스템 시작시 해당 스크립트를 실행하고 싶지는 않지만 구축하기 전에 환경을 설정하는 것이 매우 편리합니다.
C ++ IDE를 사용하는 경우 : CMAKE 경로 및 추가 옵션 (특히 CMAKE_PREFIX_PATH )을 설정할 수 있어야합니다. QT (또는 다른 라이브러리)의 경로를 명시 적으로 PATH 에 추가하지 않는 것이 좋습니다. 대신 CMAKE_PREFIX_PATH 사용하고 PATH 변경하지 않도록하십시오. IDE가 QT Creator라면 QT 경로를 전혀 처리 할 필요가 없으며 올바른 키트를 골라 곧바로 건물로 이동하십시오.
Libolm도 필요합니다. 이 글을 작성할 때 VCPKG 나 다른 곳에서 다운로드 할 수있는 Windows 용 바이너리가 없습니다. 소스 코드는 https://gitlab.matrix.org/matrix-org/olm에서 사용할 수 있습니다. 나머지 지수와 동일한 도구 체인 (Cmake+MSVC, EG)을 사용할 수 있습니다.
처음부터 libquotient를 사용하여 프로젝트를 시작하는 경우 Project에 quotest/CMakeLists.txt quotest 에 복사하여 프로젝트 이름으로 변경할 수 있습니다. 기존 cmakelists.txt가 이미있는 경우 libquotient가 어려운 경우에 대한 find_package(Quotient REQUIRED) )를 사용하는 경우 find_package(Quotient) 라인을 삽입 한 다음 target_link_libraries() 줄에 Quotient 추가해야합니다.
동적 링크는 현재 Linux에서만 테스트 되며이 플랫폼에서 Libquotient와 연결하는 권장 방법입니다. 정적 링크는 Windows/MacOS의 기본값입니다. 동적 링크를 실험하고 결과에 대한 피드백을 제공하십시오.
(매우 기본적인) 개요는 해당 Wiki 페이지에서 찾을 수 있습니다. 라이브러리의 Doxygen 문서는 https://quotient-im.github.io/libquotient/에서 찾을 수 있습니다. 또한 Libquotient와 함께 제공되는 Test Application의 소스 코드를 살펴보면 메시지 보내기, 파일 업로드, 룸 상태 설정 등과 같은 가장 일반적인 사용 사례에 도움이 될 수 있습니다.
보다 광범위한 사용법의 예와 패턴은 쿼터니온의 소스 코드 (libquotient에 대한 참조 클라이언트) 또는 Neochat을 자유롭게 확인하고 적절한 귀속으로 확인하십시오.
Quantient 0.7.2이므로 _p.h 및 네임 스페이스 _impl 로 끝나는 파일을 제외한 Libquotient의 모든 헤더 파일의 기호는 공개로 간주되며 API/ABI 안정성 보증으로 덮여 있습니다. 구체적으로, API와 ABI는 모든 마이너 버전 (0.7.x 릴리스) 내에서 호환되며, 각각의 다음 마이너 버전 (0.8, 예를 들어)은 호환성을 깨뜨립니다. 우리가 1.0에 도달하면이 규칙은 의미 론적 버전 관리 규칙에 맞는 주요 버전에 적용됩니다. *_p.h 파일 및 네임 스페이스 _impl 이러한 보증으로 덮여 있지 않습니다. 클라이언트 코드에는 이러한 파일을 직접 포함 시키 거나이 위치에 정의 된 기호를 사용해서는 안됩니다.
Linux 이외의 플랫폼에서는 사용하기 전에 Libquotient 자신을 구축해야합니다. 배포판에 나오는 것보다 최신 버전이나 스냅 샷이 필요한 경우 Linux에서 라이브러리를 구축 할 수도 있습니다.
소스 코드는 Github에 있습니다. 서브 모듈과 함께 특정 커밋 또는 태그 (아카이브를 다운로드하지 않고)를 확인하는 것이 좋습니다. 다른 프로젝트의 일환으로 도서관을 해킹하려면 (예 : Quaternion에서 작업하고 있지만 라이브러리 코드를 변경해야 함) 해당 프로젝트 (이 경우 쿼터니온)에서 재귀 적 체크 아웃을하고 해당 지점 내에서 라이브러리 하위 모듈 (재귀 적으로)을 업데이트하는 것이 합리적입니다. API 호환성 제한 사항을 염두에 두십시오. 예를 들어, 각 버전의 쿼터 니온에는 Libquotient의 특정 지점 ( 0.8.x , 0.9.x 등)이 필요할 수 있습니다.
숫자와 풀 스톱 (예 : 0.7.0 )로만 구성된 태그는 릴리스 버전에 해당합니다. -betaN 또는 -rcN 마크로 끝나는 태그 각각의 사전 릴리스. PRE -RELEASES를 포장 할 때, 선행 - ~ (tilde)로 대체하는 것이 좋습니다.
Libquotient는 고전적인 CMAKE 기반 프로젝트입니다. 종속성이 제자리에 있다고 가정하면 프로젝트 소스의 루트 디렉토리에 다음 명령이 발행됩니다.
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all build 에서 컴파일 된 라이브러리를 얻을 수 있습니다 (실행하기 전에 존재하는지 확인). CMake와 함께 작동하는 C ++ IDE는 최소한의 구성 노력으로 동일한 작업을 수행 할 수 있어야합니다.
정적 빌드는 모든 지원되는 플랫폼에서 테스트됩니다. 동적 라이브러리는 Linux에서 권장되는 configuratiion입니다. MACOS에서 실행 가능할 것입니다. Windows에서 테스트되지 않았습니다 (결과에 대해보고하고보고 할 수 있습니다).
진행하기 전에 위의 모든 전제 조건에 대한 개발 라이브러리를 설치했음을 두 번 확인하십시오. Cmake는 멈추고 뭔가 빠진지 알려줍니다.
위의 첫 번째 CMAKE 호출은 빌드를 구성합니다. CMAKE 변수 (예 : -DCMAKE_PREFIX_PATH="path1;path2;..." 및 -DCMAKE_INSTALL_PREFIX=path )를 필요에 따라 해당 호출로 전달할 수 있습니다. CMAKE 문서 (사용하는 페이지 상단에서 CMAKE 버전 선택)는 CMAKE와 함께 오는 표준 변수를 설명합니다. 그 외에도 Quotient는 다음을 이해합니다.
Quotient_INSTALL_TESTS=<ON/OFF> , ON 으로 - install 대상이 호출 될 때 라이브러리 파일과 함께 quotest 설치하십시오. quotest 주어진 객실에 주어진 객실에 연결하려고 시도하고 메시지 보내기 및 작은 파일 보내기, 레드 션, 설정실 quotest --help 등과 같은 일부 기본 매트릭스 작업을 수행하는 작은 명령 줄 프로그램입니다.MATRIX_SPEC_PATH 및 GTAD_PATH 이 두 변수는 API 파일을 포함하는 행렬 DOC 리포지토리와 GTAD 바이너리를 사용하여 디렉토리를 가리키는 데 사용됩니다. 이 두 가지는 OpenAPI 표기법으로 작성된 Matrix Client-Server API 설명에서 C ++ 파일을 생성하는 데 사용됩니다. 도서관을 구축 해야하는 경우에는 필요하지 않습니다. 실제로 해킹을하고 있다면 Contributing.md 및 Code_Generation.md의 각 섹션을 읽으십시오.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , 기본적으로 OFF (위의 옵션과 달리 Quotient는 여기에 캡에 있습니다) -이 옵션이 ON 있을 때 CMAKE는 <oplevel include <include <quotient.h> 대신 #include <Quotient/header.h> <top-level include prefix>/Quotient/ #include <header.h> /quotient/를 추가합니다. 기본적으로 이것은 거꾸로 호환성을 위해 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를 사용합니다. Libquotient와 코드 모두에서 동일한 주요 QT 버전을 사용하도록 빌드를 구성해야합니다.
Libquotient는 QT의 로깅 범주를 사용하여 특정 유형의 로깅을보다 쉽게 전환 할 수 있습니다. 런타임 (버그, 충돌)시 문제가 발생하면 QT_LOGGING_RULES 환경 변수에 다음을 추가하면 로깅을 늘릴 수 있습니다.
quotient.<category>.<level>=<flag>
어디
<category> 중 하나는 다음 중 하나입니다. main , jobs , jobs.sync , jobs.thumbnail , events , events.state ( "일반적인"객실 상태 및 계정 데이터를 모두 다루기), events.members , events.messages , 이벤트, events.ephemeral , database , network , e2ee 및 profiler 당신은 항상 Quotient/logging_categories_p.h 에서 전체 목록을 찾을 수 있습니다.<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 뷰어 또는 텍스트 편집기를 준비).
