libQuotient
0.9.1
Proyek Quotient bertujuan untuk menghasilkan SDK berbasis QT untuk mengembangkan aplikasi untuk matriks. LibQuotient adalah perpustakaan yang memungkinkan aplikasi klien. Ini adalah tulang punggung Kuaternion, Neochat dan proyek lainnya.
Anda dapat menemukan pengembang yang penting di ruang matriks: #Quotient: matrix.org.
Anda dapat mengajukan masalah di pelacak masalah proyek. Jika Anda menemukan apa yang tampak seperti masalah keamanan, silakan gunakan instruksi di Security.md.
Bergantung pada platform Anda, perpustakaan dapat diperoleh dari sistem manajemen paket. Rilis terbaru dari Fedora, Debian dan OpenSUSE sudah memilikinya. Atau, Anda dapat membangun perpustakaan dari sumbernya dan menggabungkannya dengan aplikasi Anda, seperti yang dijelaskan di bawah ini.
Untuk menggunakan libQuotient (yaitu membangun atau menjalankan aplikasi dengan itu), Anda akan membutuhkan:
Untuk membangun aplikasi dengan LibQuotient, Anda juga akan membutuhkan:
Persyaratan untuk membangun libquotient itu pada dasarnya sama kecuali Anda harus menginstal pustaka pengembangan untuk dependensi yang tercantum di atas.
Cukup instal prasyarat menggunakan manajer paket pilihan Anda. Jika basis paket QT Anda berbutir halus, Anda mungkin ingin menjalankan CMake dan melihat pesan kesalahan. Perpustakaan sepenuhnya di luar layar; Namun, selain dari qtcore dan qtnetwork itu juga tergantung pada qtgui untuk menangani thumbnail avatar, tanpa gambar di layar.
brew install qt qtkeychain libolm openssl@3 harus memberi Anda versi terbaru dari pustaka runtime.
Anda mungkin perlu menambahkan $(brew --prefix qt) , $(brew --prefix qtkeychain) dll. Untuk CMAKE_PREFIX_PATH (lihat di bawah) untuk membuat CMake sadar akan lokasi perpustakaan.
Instal QT dan OpenSSL menggunakan penginstal resmi proyek QT; Pastikan untuk juga mencentang kotak CMake dalam daftar komponen untuk menginstal kecuali Anda sudah memilikinya. Ini akan membuat Anda kedua pustaka runtime dan file pengembangan, yang juga cocok untuk membangun libquotient itu sendiri. Jika Anda pergi ke sini, Anda harus membangun QTKeyChain dari kode sumber.
Atau, Anda dapat menggunakan VCPKG untuk menginstal QT, OpenSSL, dan QTKeyChain. Dalam hal ini Anda tidak mendapatkan pencipta QT, yang merupakan IDE yang sangat bagus untuk menangani proyek berbasis QT; Tetapi jika Anda sudah menggunakan vscode atau clion, Anda mungkin lebih suka rute ini. Anda juga dapat mencampur dan mencocokkan, menginstal QT Creator dari pemasang resmi dan sisanya dari VCPKG. Mencampur QT dari penginstal resmi dengan Keychain QT dari VCPKG mungkin atau mungkin tidak berfungsi, tergantung pada versi QT yang digunakan untuk membangun Keychain QT.
Jika Anda membangun dari baris perintah : Perintah di bagian lebih lanjut menyiratkan bahwa cmake ada di PATH Anda, jika tidak, Anda harus menyiapkan perintah tersebut dengan jalur yang sebenarnya. Merupakan ide yang bagus untuk menjalankan skrip qtenv2.bat yang dapat ditemukan di C:Qt<Qt version><toolchain>bin (dengan asumsi Anda menginstal qt ke C:Qt ). Script ini menambahkan jalur yang diperlukan ke PATH . Anda mungkin tidak ingin menjalankan skrip itu pada startup sistem tetapi sangat berguna untuk mengatur lingkungan sebelum membangun.
Jika Anda menggunakan IDE C ++ : Anda harus dapat mengonfigurasi jalur CMake dan opsi tambahan ( CMAKE_PREFIX_PATH , khususnya) dalam pengaturannya. Disarankan untuk tidak menambahkan jalur untuk QT (atau perpustakaan lainnya) ke PATH secara eksplisit; Gunakan CMAKE_PREFIX_PATH sebagai gantinya dan biarkan PATH tidak berubah. Jika IDE Anda adalah pencipta QT, Anda tidak perlu berurusan dengan jalur QT sama sekali, cukup pilih kit yang tepat dan langsung ke gedung.
Anda juga akan membutuhkan Libolm. Anda harus membangunnya sendiri - tidak ada biner untuk Windows yang dapat Anda unduh dari VCPKG atau di tempat lain, saat tulisan ini. Kode sumber tersedia di https://gitlab.matrix.org/matrix-org/olm; Anda dapat menggunakan toolchain yang sama (cmake+msvc, misalnya) untuk sisa hasil bagi.
Jika Anda baru memulai proyek menggunakan LibQuotient dari awal, Anda dapat menyalin quotest/CMakeLists.txt ke proyek Anda dan ubah quotest ke nama proyek Anda. Jika Anda sudah memiliki cmakeLists.txt yang ada, Anda harus memasukkan baris find_package(Quotient REQUIRED) ke tempat yang sesuai di dalamnya (gunakan find_package(Quotient) jika libquTient bukan ketergantungan yang sulit untuk Anda) dan kemudian tambahkan Quotient bagi target_link_libraries() line Anda.
Dinamic Linking hanya diuji di Linux saat ini dan merupakan cara yang disarankan untuk menghubungkan dengan libQuotient di platform ini. Tautan statis adalah default pada Windows/MacOS; Jangan ragu untuk bereksperimen dengan tautan dinamis dan memberikan umpan balik dengan hasil Anda.
Tinjauan (sangat mendasar) dapat ditemukan di halaman wiki masing -masing. Dokumentasi doxygen untuk perpustakaan dapat ditemukan di https://quotient-im.github.io/libquotient/. Lebih lanjut, melihat kode sumber untuk quotest - aplikasi pengujian yang dilengkapi dengan libQuotient - dapat membantu Anda dengan kasus penggunaan yang paling umum seperti mengirim pesan, mengunggah file, pengaturan status ruang dll.
Untuk contoh dan pola penggunaan yang lebih luas, jangan ragu untuk memeriksa (dan menyalin, dengan atribusi yang sesuai) kode sumber kuarter (klien referensi untuk libQuotient) atau neochat.
Karena hasil bagi 0.7.2, simbol di semua file header libquTient kecuali file yang diakhiri dengan _p.h dan namespace _impl dianggap publik dan dicakup oleh jaminan stabilitas API/ABI. Secara khusus, API dan ABI kompatibel ke belakang dalam setiap versi minor (0.7.x rilis) dengan setiap versi minor berikutnya (0.8, misalnya) melanggar kompatibilitas. Setelah kami mencapai 1.0, aturan ini akan berlaku untuk versi utama, sejajar dengan aturan versi semantik. *_p.h file dan namespace _impl tidak tercakup oleh jaminan ini; Kode klien tidak boleh secara langsung memasukkan file -file ini, atau menggunakan simbol yang ditentukan di lokasi ini.
Pada platform selain Linux, Anda harus membangun sendiri sebelum penggunaan - tidak ada yang mengemasnya sejauh ini (kontribusi selamat datang!). Anda mungkin juga ingin membangun perpustakaan di Linux jika Anda memerlukan versi atau snapshot yang lebih baru dari yang datang di distro Anda.
Kode sumber ada di GitHub. Memeriksa komit atau tag tertentu (daripada mengunduh arsip) bersama dengan submodul sangat disarankan. Jika Anda ingin meretas perpustakaan sebagai bagian dari proyek lain (misalnya Anda sedang bekerja pada kuarter tetapi perlu melakukan beberapa perubahan pada kode perpustakaan), masuk akal untuk membuat perekrutan rekursif dari proyek itu (dalam hal ini, kuarter) dan memperbarui submodule perpustakaan (juga secara rekursif) dalam cabang yang sesuai. Berhati -hatilah dengan pembatasan kompatibilitas API: misalnya, setiap versi kuaternion mungkin memerlukan cabang spesifik libQuotient ( 0.8.x , 0.9.x dll.).
Tag yang hanya terdiri dari digit dan fullstops (misalnya, 0.7.0 ) sesuai dengan versi yang dirilis; Tag yang diakhiri dengan pra -rilis -betaN atau -rcN masing -masing. Jika/ketika pengemasan pra -rilis, disarankan untuk mengganti yang terdepan - dengan ~ (Tilde).
LibQuotient adalah proyek berbasis CMAKE klasik; Dengan asumsi dependensi ada, perintah berikut yang dikeluarkan dalam direktori root sumber proyek:
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all Akan memberi Anda perpustakaan yang dikompilasi dalam build (pastikan itu ada sebelum berjalan). Setiap IDE C ++ yang bekerja dengan CMake harus dapat melakukan hal yang sama dengan upaya konfigurasi minimal.
Bangunan statis diuji pada semua platform yang didukung. Pustaka dinamis adalah konfigurasi yang disarankan di Linux; kemungkinan bisa diterjemahkan pada macOS; dan belum teruji di Windows (Anda dipersilakan untuk mencoba dan melaporkan hasilnya).
Sebelum melanjutkan, periksa ulang bahwa Anda telah menginstal pustaka pengembangan untuk semua prasyarat di atas. CMake akan berhenti dan memberi tahu Anda jika ada sesuatu yang hilang.
Doa CMake pertama di atas mengkonfigurasi build. Anda dapat melewati variabel cmake (seperti -DCMAKE_PREFIX_PATH="path1;path2;..." dan -DCMAKE_INSTALL_PREFIX=path ) ke doa itu jika diperlukan. Dokumentasi CMake (pilih versi CMake di bagian atas halaman yang Anda gunakan) menjelaskan variabel standar yang datang dengan CMake. Di atasnya, Quotient memahami:
Quotient_INSTALL_TESTS=<ON/OFF> , ON secara default - instal quotest bersama dengan file perpustakaan saat install target dipanggil. quotest adalah program baris perintah kecil yang (dengan asumsi parameter yang benar, lihat quotest --help ) yang mencoba terhubung ke ruang tertentu sebagai pengguna yang diberikan dan melakukan beberapa operasi matriks dasar, seperti mengirim pesan dan file kecil, redaksi, pengaturan tag ruang dll. Ini berguna untuk memeriksa kewarasan instalasi perpustakaan Anda.MATRIX_SPEC_PATH dan GTAD_PATH - Dua variabel ini digunakan untuk mengarahkan CMake ke direktori dengan repositori matriks -doc yang berisi file API dan ke biner GTAD. Keduanya digunakan untuk menghasilkan file C ++ dari deskripsi API klien-server matriks yang dibuat dalam notasi OpenAPI. Ini tidak diperlukan jika Anda hanya perlu membangun perpustakaan; Jika Anda benar -benar menyukai peretasan di atasnya, silakan baca bagian masing -masing di Contributing.md dan Code_Generation.md.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , OFF secara default (Perhatikan bahwa hasil bagi di caps di sini, tidak seperti opsi di atas) - ketika opsi ini diatur ke ON , CMake melompati kode klien untuk menggunakan < <top-level include prefix>/Quotient/ < #include <Quotient/header.h> #include <header.h> . Secara default ini diatur untuk OFF untuk kompatibilitas mundur; Akhirnya default ini Mei/akan berubah sehingga disarankan untuk setidaknya sesekali menambahkan -DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1 ke doa CMake (atau atur variabel di IDE Anda) dan pastikan kode Anda memiliki jalur yang diawali.Anda dapat menginstal perpustakaan dengan CMake:
cmake --build . --target install Ini juga akan menginstal file konfigurasi paket cmake; Setelah ini selesai, Anda harus dapat menggunakan quotest/CMakeLists.txt untuk menyusun quotest dengan pustaka yang diinstal . Seperti disebutkan di atas, pemasangan biner quotest bersama dengan sisa perpustakaan dapat dilewati dengan mengatur Quotient_INSTALL_TESTS menjadi OFF .
Jika cmake gagal
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.
Maka Anda perlu mengatur variabel kanan -DCMAKE_PREFIX_PATH , lihat di atas.
Jika cmake gagal dengan pesan yang mirip dengan:
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
Maka Anda mungkin memiliki QT 5 dan QT 6 pada sistem Anda, dan kode Anda menggunakan versi utama QT yang berbeda dari Quotient. Pastikan Anda mengkonfigurasi build sehingga versi QT utama yang sama digunakan baik oleh LibQuotient dan kode Anda.
LibQuotient menggunakan kategori logging QT untuk membuat switching jenis logging tertentu lebih mudah. Dalam kasus masalah saat runtime (bug, crash) Anda dapat meningkatkan logging jika Anda menambahkan yang berikut ke variabel lingkungan QT_LOGGING_RULES :
quotient.<category>.<level>=<flag>
Di mana
<category> adalah salah satu dari: main , jobs , jobs.sync network , jobs.thumbnail profiler events , events.state events.messages events.members (mencakup negara database "biasa" dan data akun) Quotient/logging_categories_p.h events.ephemeral e2ee<level> adalah salah satu dari debug , info , dan warning ;<flag> true atau false . Anda dapat menggunakan * (tanda bintang) sebagai wildcard untuk setiap bagian antara dua titik, dan titik koma digunakan untuk pemisah. Pernyataan terakhir mengesampingkan yang sebelumnya, jadi jika Anda ingin mengaktifkan semua log debug kecuali jobs Anda dapat mengatur QT_LOGGING_RULES="quotient.*.debug=true;quotient.jobs.debug=false"
Anda mungkin juga ingin mengatur QT_MESSAGE_PATTERN untuk membuat log sedikit lebih informatif (lihat https://doc.qt.io/qt-6/qtlogging.html#qsetMessagePattern untuk deskripsi format). Untuk memberi contoh, inilah yang digunakan oleh salah satu pengembang perpustakaan untuk 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 hanya mengkode level logging ke dalam huruf awalnya).
Dalam hal masalah dengan keadaan kamar dan caching mungkin berguna untuk mengganti format cache dari Binary CBOR ke Plaintext JSON. Untuk melakukan itu, atur kunci libQuotient/cache_type dalam file konfigurasi/registri klien Anda ke json (Anda mungkin perlu membuat grup libquotient karena ini satu -satunya kunci yang dikenali di dalamnya sejauh ini). Ini akan membuat cache menyimpan dan memuat pekerjaan sedikit lebih lambat tetapi cache akan berada di file teks JSON (sangat panjang dan tanpa lekukan; siapkan penampil JSON yang baik atau editor teks dengan kemampuan pemformatan JSON).
