libQuotient
0.9.1
يهدف مشروع الحاصل إلى إنتاج SDK المستند إلى QT لتطوير تطبيقات للمصفوفة. Libquotient هي مكتبة تتيح تطبيقات العميل. هذا هو العمود الفقري للرباع والنيوشات وغيرها من المشاريع.
يمكنك العثور على مطورين حاصلين في غرفة المصفوفة: #quotient: matrix.org.
يمكنك تقديم مشكلات في تعقب مشكلات المشروع. إذا وجدت ما يبدو وكأنه مشكلة أمان ، فيرجى استخدام التعليمات في Security.md.
اعتمادًا على النظام الأساسي الخاص بك ، يمكن الحصول على المكتبة من نظام إدارة الحزم. الإصدارات الأخيرة من فيدورا ، ديبيان و Opensuse لديها بالفعل. بدلاً من ذلك ، يمكنك إنشاء المكتبة من المصدر وحملها بتطبيقك ، كما هو موضح أدناه.
لاستخدام libquotient (أي بناء أو تشغيل التطبيقات معها) ، ستحتاج:
لبناء التطبيقات مع 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 ، وهو IDE لطيف للغاية للتعامل مع المشاريع المستندة إلى QT ؛ ولكن إذا استخدمت بالفعل VSCODE أو CLION ، فقد تفضل هذا المسار. يمكنك أيضًا خلط ومطابقة وتثبيت KT Creator من المثبت الرسمي والباقي من VCPKG. قد يعمل أو لا يعمل خلط QT من التثبيت الرسمي مع سلسلة مفاتيح QT من VCPKG ، اعتمادًا على إصدار QT المستخدم لإنشاء سلسلة مفاتيح QT.
إذا قمت ببناء من سطر الأوامر : تشير الأوامر في أقسام أخرى إلى أن cmake في PATH ، وإلا يجب عليك إعداد تلك الأوامر ذات المسارات الفعلية. من الجيد تشغيل البرنامج النصي qtenv2.bat الذي يمكن العثور عليه في C:Qt<Qt version><toolchain>bin (على افتراض أنك قمت بتثبيت Qt إلى C:Qt ). يضيف هذا البرنامج النصي المسارات اللازمة إلى PATH . قد لا ترغب في تشغيل هذا البرنامج النصي على بدء تشغيل النظام ، لكن من السهل جدًا إعداد البيئة قبل البناء.
إذا كنت تستخدم IDE C ++ : فيجب أن تكون قادرًا على تكوين مسار CMake وخيارات إضافية ( CMAKE_PREFIX_PATH ، على وجه الخصوص) في إعداداته. يوصى بعدم إضافة مسار QT (أو أي مكتبة أخرى) إلى PATH بشكل صريح ؛ استخدم CMAKE_PREFIX_PATH بدلاً من ذلك واترك PATH دون تغيير. إذا كان IDE الخاص بك هو خالق QT ، فلن تحتاج إلى التعامل مع مسارات QT على الإطلاق ، فقط اختر المجموعة الصحيحة وانتقل مباشرة إلى المبنى.
ستحتاج أيضًا إلى libolm. سيكون عليك أن تبنيها بنفسك - لا يوجد ثنائي لنظام التشغيل Windows يمكنك تنزيله من VCPKG أو في أي مكان آخر ، حتى كتابة هذه السطور. رمز المصدر متاح على https://gitlab.matrix.org/matrix-org/olm ؛ يمكنك استخدام نفس مجموعة الأدوات (CMake+MSVC ، على سبيل المثال) كما لبقية الحاصل.
إذا كنت تبدأ للتو مشروعًا باستخدام libquotient من نقطة الصفر ، فيمكنك نسخ quotest/CMakeLists.txt إلى مشروعك وتغيير اسم quotest . إذا كان لديك بالفعل cmakelists.txt موجود ، فأنت بحاجة إلى إدراج خط find_package(Quotient REQUIRED) إلى مكان مناسب فيه (استخدم find_package(Quotient) إذا لم يكن libquotient تبعية صلبة بالنسبة لك) ثم إضافة Quotient إلى خط target_link_libraries() .
يتم اختبار الارتباط الديناميكي فقط على Linux في الوقت الحالي وهو الطريقة الموصى بها للربط مع libquotient على هذا النظام الأساسي. الربط الثابت هو الافتراضي على Windows/MacOS ؛ لا تتردد في تجربة الارتباط الديناميكي وتقديم ملاحظات مع نتائجك.
يمكن العثور على نظرة عامة (أساسية جدًا) في صفحة Wiki المعنية. يمكن العثور على وثائق doxygen للمكتبة على https://quotient-im.github.io/libquotient/. علاوة على ذلك ، قد يساعدك النظر في الكود المصدري لـ QUESSEST - تطبيق الاختبار الذي يأتي مع 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 ، سيتعين عليك بناء libquotient بنفسك قبل الاستخدام - لم يحزم أحد حتى الآن (الترحيب بالمساهمات!). قد ترغب أيضًا في إنشاء المكتبة على Linux إذا كنت بحاجة إلى إصدار أحدث أو لقطة من تلك القادمة في التوزيع الخاص بك.
رمز المصدر في جيثب. يوصى بشدة بالتحقق من التزام أو علامة معينة (بدلاً من تنزيل الأرشيف) جنبًا إلى جنب مع العارض الفرعي. إذا كنت ترغب في اختراق المكتبة كجزء من مشروع آخر (على سبيل المثال ، فأنت تعمل على الرباعة ولكنك تحتاج إلى إجراء بعض التغييرات على رمز المكتبة) ، فمن المنطقي إجراء فحص عودي من هذا المشروع (في هذه الحالة ، الرباعة) وتحديث وحدة المكتبة الفرعية (بشكل متكرر أيضًا) ضمن الفرع المناسب. أن تضع في اعتبارها قيود توافق API: على سبيل المثال ، قد يتطلب كل إصدار من الرباعة الفرع المحدد من libquotient ( 0.8.x ، 0.9.x إلخ).
تتوافق العلامات التي تتكون فقط من الأرقام والأحواض المملوءة (على سبيل المثال ، 0.7.0 ) مع الإصدارات التي تم إصدارها ؛ العلامات التي تنتهي مع -betaN أو -rcN Mark قبل الإفراج. إذا/عند التعبئة والتغليف المسبق ، يُنصح باستبدال الرائدة - بـ ~ (tilde).
Libquotient هو مشروع كلاسيكي قائم على Cmake ؛ على افتراض أن التبعيات موجودة ، فإن الأوامر التالية الصادرة في الدليل الجذر لمصادر المشروع:
cmake -B build -S . # [-D<cmake-variable>=<value>...], see below
cmake --build build --target all سوف تحصل على مكتبة مجمعة في build (تأكد من وجودها قبل الجري). يجب أن يكون أي IDE C ++ الذي يعمل مع CMake قادرًا على فعل الشيء نفسه مع الحد الأدنى من جهد التكوين.
يتم اختبار البنيات الثابتة على جميع المنصات المدعومة. المكتبات الديناميكية هي التكوين الموصى بها على Linux ؛ من المحتمل أن يكون عمليًا على MacOS ؛ ولم يتم اختباره على النوافذ (مرحبًا بك في محاولة الإبلاغ عن النتائج).
قبل المتابعة ، تحقق من أنك قمت بتثبيت مكتبات تطوير لجميع المتطلبات المسبقة أعلاه. سيتوقف Cmake ويخبرك إذا كان هناك شيء مفقود.
أول احتجاج CMAKE أعلاه يكوين البناء. يمكنك تمرير متغيرات cmake (مثل -DCMAKE_PREFIX_PATH="path1;path2;..." و -DCMAKE_INSTALL_PREFIX=path ) إلى هذا الاحتجاج إذا لزم الأمر. توضح وثائق CMake (اختر إصدار CMake في الجزء العلوي من الصفحة التي تستخدمها) المتغيرات القياسية القادمة مع CMake. علاوة على ذلك ، يفهم Quitient:
Quotient_INSTALL_TESTS=<ON/OFF> ، ON افتراضي - قم بتثبيت quotest مع ملفات المكتبة عند install يتم استدعاء الهدف. quotest عبارة عن برنامج صغير لخط الأوامر (على افتراض المعلمات الصحيحة ، انظر quotest --help ) الذي يحاول الاتصال بغرفة معينة كمستخدم معين وتنفيذ بعض عمليات المصفوفة الأساسية ، مثل إرسال الرسائل والملفات الصغيرة ، REMACTION ، علامات إعداد الغرفة وما إلى ذلك. هذا مفيد للتحقق من عقل تثبيت المكتبات الخاص بك.MATRIX_SPEC_PATH و GTAD_PATH - يتم استخدام هذين المتغيرين لتوجيه cmake إلى الدليل مع مستودع MATRIX -DOC الذي يحتوي على ملفات API و GTAD ثنائي. يتم استخدام هذين لإنشاء ملفات C ++ من وصف واجهة برمجة تطبيقات Client-Client-Client-Server المصنوعة في تدوين OpenAPI. ليس هناك حاجة إلى ذلك إذا كنت بحاجة فقط إلى بناء المكتبة ؛ إذا كنت حقًا في اختراقه ، فيرجى قراءة الأقسام المعنية في المساهمة. md و code_generation.md.QUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> ، OFF افتراضيًا (لاحظ أن الحاصل على قبعات هنا ، على عكس الخيارات أعلاه) - عندما يتم تعيين هذا الخيار على ON ، يتخطى cmake إضافة <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 BINARY مع بقية المكتبة عن طريق إعداد 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 عن Quotient. تأكد من تكوين الإنشاء بحيث يتم استخدام نفس إصدار QT الرئيسي بواسطة Libquotient والرمز الخاص بك.
يستخدم Libquotient فئات تسجيل QT لجعل تبديل أنواع معينة من التسجيل أسهل. في حالة وجود مشاكل في وقت التشغيل (الأخطاء ، الحوادث) ، يمكنك زيادة التسجيل إذا قمت بإضافة ما يلي إلى متغير بيئة QT_LOGGING_RULES :
quotient.<category>.<level>=<flag>
أين
<category> events.ephemeral network database : main ، jobs Quotient/logging_categories_p.h jobs.sync e2ee jobs.thumbnail profiler events events.messages events.state events.members<level> هو واحد من debug info warning ؛<flag> إما true أو false . يمكنك استخدام * (العلامة النجمية) كبطاقة برية لأي جزء بين نقطتين ، ويستخدم Semicolon لفاصل. تتجاوز العبارات الأخيرة منها سابقًا ، لذلك إذا كنت ترغب في تشغيل جميع سجلات الأخطاء باستثناء 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}`
(charcary %{if} s هي مجرد ترميز مستوى التسجيل في خطابها الأولي).
في حالة وجود مشكلات مع حالة الغرفة والتخزين المؤقت ، قد يكون من المفيد تبديل تنسيق ذاكرة التخزين المؤقت من CBOR الثنائي إلى JSON PlainText. للقيام بذلك ، قم بتعيين مفتاح libQuotient/cache_type في ملف/سجل تكوين عميلك إلى json (قد تحتاج إلى إنشاء مجموعة libquotient لأنها المفتاح الوحيد المعترف به حتى الآن). سيؤدي ذلك إلى جعل ذاكرة التخزين المؤقت لتوفير وتحميل العمل أبطأ قليلاً ، لكن ذاكرة التخزين المؤقت ستكون في ملفات نصية JSON (طويلة جدًا وبدون مسافة بادئة ؛ قم بإعداد عارض JSON جيد أو محرر نصوص مع إمكانات تنسيق JSON).
