libQuotient
0.9.1
โครงการความฉลาดมีวัตถุประสงค์เพื่อผลิต SDK ที่ใช้ QT เพื่อพัฒนาแอพพลิเคชั่นสำหรับเมทริกซ์ Libquotient เป็นไลบรารีที่เปิดใช้งานแอปพลิเคชันไคลเอนต์ มันเป็นกระดูกสันหลังของ Quaternion, Neochat และโครงการอื่น ๆ
คุณสามารถค้นหานักพัฒนาที่ฉลาดในห้องเมทริกซ์: #quotient: matrix.org
คุณสามารถยื่นปัญหาได้ที่ตัวติดตามปัญหาโครงการ หากคุณพบสิ่งที่ดูเหมือนปัญหาด้านความปลอดภัยโปรดใช้คำแนะนำใน Security.md
ขึ้นอยู่กับแพลตฟอร์มของคุณห้องสมุดสามารถรับได้จากระบบการจัดการแพ็คเกจ รุ่นล่าสุดของ Fedora, Debian และ OpenSuse มีอยู่แล้ว หรือคุณสามารถสร้างไลบรารีจากแหล่งที่มาและมัดด้วยแอปพลิเคชันของคุณตามที่อธิบายไว้ด้านล่าง
หากต้องการใช้ libquotient (เช่นสร้างหรือเรียกใช้แอปพลิเคชันด้วย) คุณจะต้อง:
ในการสร้างแอปพลิเคชันด้วย libquotient คุณจะต้อง:
ข้อกำหนดในการสร้าง libquotient นั้นเหมือนกันยกเว้นว่าคุณควรติดตั้งไลบรารีการพัฒนาสำหรับการอ้างอิงที่ระบุไว้ข้างต้น
เพียงติดตั้งข้อกำหนดเบื้องต้นโดยใช้แพ็คเกจ Manager ที่คุณต้องการ หากฐานแพ็คเกจ 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 Project ตรวจสอบให้แน่ใจว่าทำเครื่องหมายในกล่อง cmake ในรายการส่วนประกอบที่จะติดตั้งเว้นแต่คุณจะมีอยู่แล้ว สิ่งนี้จะช่วยให้คุณได้ทั้งห้องสมุดรันไทม์และไฟล์การพัฒนาซึ่งเหมาะที่จะสร้าง libquotient เอง หากคุณไปด้วยวิธีนี้คุณจะต้องสร้าง qtkeychain จากซอร์สโค้ด
หรือคุณสามารถใช้ VCPKG เพื่อติดตั้ง QT, OpenSSL และ QtKeychain ในกรณีนี้คุณไม่ได้รับผู้สร้าง QT ซึ่งเป็น IDE ที่ดีมากในการจัดการกับโครงการที่ใช้ QT แต่ถ้าคุณใช้ vscode หรือ clion อยู่แล้วคุณอาจชอบเส้นทางนี้ นอกจากนี้คุณยังสามารถผสมและจับคู่ติดตั้งผู้สร้าง QT จากตัวติดตั้งอย่างเป็นทางการและส่วนที่เหลือจาก VCPKG การผสม QT จากตัวติดตั้งอย่างเป็นทางการกับ QT Keychain จาก VCPKG อาจใช้งานได้หรือไม่อาจใช้งานได้ทั้งนี้ขึ้นอยู่กับรุ่น QT ที่ใช้ในการสร้าง Keychain 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 เลยเพียงเลือกชุดที่เหมาะสมและตรงไปที่อาคาร
คุณจะต้องมี libolm คุณจะต้องสร้างมันเอง - ไม่มีไบนารีสำหรับ Windows ที่คุณสามารถดาวน์โหลดได้จาก VCPKG หรือที่อื่น ๆ เช่นเดียวกับการเขียนนี้ ซอร์สโค้ดสามารถใช้ได้ที่ https://gitlab.matrix.org/matrix-org/olm; คุณสามารถใช้ Toolchain เดียวกัน (CMAKE+MSVC, EG) สำหรับส่วนที่เหลือของความฉลาด
หากคุณเพิ่งเริ่มโครงการโดยใช้ libquotient ตั้งแต่เริ่มต้นคุณสามารถคัดลอก quotest/CMakeLists.txt ไปยังโครงการของคุณและเปลี่ยน quotest เป็นชื่อโครงการของคุณ หากคุณมี cmakelists.txt ที่มีอยู่แล้วคุณจะต้องแทรกบรรทัด find_package(Quotient REQUIRED) ไปยังสถาน Quotient target_link_libraries() เหมาะสมในนั้น (ใช้ find_package(Quotient) หาก libquotient ไม่ใช่การพึ่งพาคุณยากสำหรับคุณ
การเชื่อมโยงแบบไดนามิกจะถูกทดสอบเฉพาะใน Linux ในขณะนี้และเป็นวิธีที่แนะนำในการเชื่อมโยงกับ libquotient บนแพลตฟอร์มนี้ การเชื่อมโยงแบบคงที่เป็นค่าเริ่มต้นบน Windows/MacOS; อย่าลังเลที่จะทดสอบด้วยการเชื่อมโยงแบบไดนามิกและให้ข้อเสนอแนะกับผลลัพธ์ของคุณ
ภาพรวม (พื้นฐานมาก) สามารถพบได้ที่หน้าวิกิที่เกี่ยวข้อง เอกสาร Doxygen สำหรับห้องสมุดสามารถดูได้ที่ https://quotient-im.github.io/libquotient/ นอกจากนี้การดูซอร์สโค้ดสำหรับ Quotest - แอปพลิเคชันทดสอบที่มาพร้อมกับ libquotient - อาจช่วยคุณในกรณีการใช้งานทั่วไปเช่นการส่งข้อความการอัปโหลดไฟล์การตั้งค่าสถานะห้อง ฯลฯ
ตัวอย่างและรูปแบบการใช้งานที่กว้างขวางมากขึ้นโปรดตรวจสอบ (และคัดลอกด้วยการระบุแหล่งที่มาที่เหมาะสม) ซอร์สโค้ดของ Quaternion (ไคลเอนต์อ้างอิงสำหรับ 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 หากคุณต้องการเวอร์ชันใหม่หรือสแน็ปช็อตมากกว่าที่มาใน distro ของคุณ
ซอร์สโค้ดอยู่ที่ GitHub ตรวจสอบการกระทำหรือแท็กบางอย่าง (แทนที่จะดาวน์โหลดไฟล์เก็บถาวร) พร้อมกับ submodules แนะนำอย่างยิ่ง หากคุณต้องการแฮ็คในห้องสมุดเป็นส่วนหนึ่งของโครงการอื่น (เช่นคุณกำลังทำงานกับ Quaternion แต่จำเป็นต้องทำการเปลี่ยนแปลงบางอย่างในรหัสห้องสมุด) มันสมเหตุสมผลที่จะทำการตรวจสอบซ้ำจากโครงการนั้น (ในกรณีนี้ Quaternion) และอัปเดต Submodule ห้องสมุด ระวังข้อ จำกัด ความเข้ากันได้ของ API: เช่น Quaternion แต่ละรุ่นอาจต้องใช้สาขาเฉพาะของ libquotient ( 0.8.x , 0.9.x ฯลฯ )
แท็กประกอบด้วยตัวเลขและ FullStops เพียงอย่างเดียว (เช่น 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 (ตรวจสอบให้แน่ใจว่ามีอยู่ก่อนที่จะทำงาน) C ++ IDE ใด ๆ ที่ทำงานร่วมกับ CMAKE ควรทำเช่นเดียวกันกับความพยายามในการกำหนดค่าน้อยที่สุด
การสร้างแบบคงที่ได้รับการทดสอบบนแพลตฟอร์มที่รองรับทั้งหมด ไลบรารีแบบไดนามิกคือการกำหนดค่าที่แนะนำบน Linux; มีแนวโน้มที่จะทำงานบน macOS; และยังไม่ได้ทดสอบบน Windows (คุณยินดีที่จะลองและรายงานผลลัพธ์)
ก่อนดำเนินการตรวจสอบอีกครั้งว่าคุณได้ติดตั้งไลบรารีการพัฒนาสำหรับข้อกำหนดเบื้องต้นทั้งหมดข้างต้น Cmake จะหยุดและบอกคุณว่ามีอะไรขาดหายไป
การเรียกใช้ CMake ครั้งแรกด้านบนกำหนดค่าการสร้าง คุณสามารถผ่านตัวแปร cmake (เช่น -DCMAKE_PREFIX_PATH="path1;path2;..." และ -DCMAKE_INSTALL_PREFIX=path ) ไปยังการเรียกใช้นั้นหากจำเป็น เอกสาร CMAKE (เลือกรุ่น CMAKE ที่ด้านบนของหน้าเว็บที่คุณใช้) อธิบายตัวแปรมาตรฐานที่มาพร้อมกับ CMAKE ด้านบนของพวกเขาความฉลาดเข้าใจ:
Quotient_INSTALL_TESTS=<ON/OFF> , ON โดยค่าเริ่มต้น - ติดตั้ง quotest พร้อมกับไฟล์ไลบรารีเมื่อ install ตั้งเป้าหมายถูกเรียกใช้ quotest เป็นโปรแกรมบรรทัดคำสั่งขนาดเล็กที่ (สมมติว่าพารามิเตอร์ที่ถูกต้องโปรดดู quotest --help ) ที่พยายามเชื่อมต่อกับห้องที่กำหนดในฐานะผู้ใช้ที่กำหนดและดำเนินการเมทริกซ์พื้นฐานบางอย่างเช่นการส่งข้อความและไฟล์ขนาดเล็ก redactionMATRIX_SPEC_PATH และ GTAD_PATH - ตัวแปรทั้งสองนี้ใช้เพื่อชี้ CMAKE ไปยังไดเรกทอรีด้วยที่เก็บเมทริกซ์ - DOC ที่มีไฟล์ API และ Binary GTAD ทั้งสองนี้ใช้เพื่อสร้างไฟล์ C ++ จาก Matrix Client-Server API คำอธิบายที่ทำในสัญกรณ์ OpenAPI สิ่งนี้ไม่จำเป็นหากคุณเพียงแค่ต้องการสร้างห้องสมุด หากคุณกำลังแฮ็คมันจริงๆโปรดอ่านส่วนที่เกี่ยวข้องในการสนับสนุน. md และ code_generation.mdQUOTIENT_FORCE_NAMESPACED_INCLUDES=<ON/OFF> , OFF โดยค่าเริ่มต้น (โปรดทราบว่าความฉลาดทางอยู่ในตัวเลือกที่นี่ไม่เหมือนตัวเลือกข้างต้น) - เมื่อตัวเลือกนี้ถูกตั้งค่าเป็น ON cmake ข้ามการเพิ่ม <ระดับบนสุด #include <header.h> คำนำ #include <Quotient/header.h> <top-level include prefix>/Quotient/ โดยค่าเริ่มต้นนี้ถูกตั้งค่าเป็น OFF สำหรับความเข้ากันได้ย้อนหลัง ในที่สุดค่าเริ่มต้นอาจเปลี่ยนแปลง/จะเปลี่ยนไปดังนั้นจึงแนะนำให้เพิ่มอย่างน้อยบางครั้ง -DQUOTIENT_FORCE_NAMESPACED_INCLUDES=1 ไปยังการเรียกใช้ cmake (หรือตั้งค่าตัวแปรใน IDE ของคุณ) และตรวจสอบให้แน่ใจว่ารหัสของคุณมีเส้นทางที่นำหน้าคุณสามารถติดตั้งไลบรารีด้วย cmake:
cmake --build . --target install สิ่งนี้จะติดตั้งไฟล์ config แพ็คเกจ cmake; เมื่อทำสิ่งนี้เสร็จแล้วคุณควรจะสามารถใช้ quotest/CMakeLists.txt เพื่อรวบรวม Quotest ด้วยไลบรารี ที่ติดตั้ง ดังที่ได้กล่าวไว้ข้างต้นการติดตั้ง Binary 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> เป็นหนึ่งใน: 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 คุณสามารถใช้ * (Asterisk) เป็นสัญลักษณ์ไวด์การ์ดสำหรับส่วนใดส่วนหนึ่งระหว่างจุดสองจุดและเซมิโคลอนใช้สำหรับตัวคั่น คำแถลงหลังแทนที่เดิมดังนั้นหากคุณต้องการเปิดบันทึกการดีบักทั้งหมดยกเว้น 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}`
(Scary %{if} s เพิ่งเข้ารหัสระดับการบันทึกลงในตัวอักษรเริ่มต้น)
ในกรณีที่มีปัญหาเกี่ยวกับสถานะห้องและการแคชอาจเป็นประโยชน์ในการสลับรูปแบบแคชจากไบนารี CBOR เป็น Plaintext JSON ในการทำเช่นนั้นให้ตั้งค่าคีย์ libQuotient/cache_type ในไฟล์การกำหนดค่า/รีจิสทรีของไคลเอนต์ของคุณไปยัง json (คุณอาจต้องสร้างกลุ่ม libquotient เนื่องจากเป็นคีย์ที่ได้รับการยอมรับเพียงอย่างเดียว) สิ่งนี้จะทำให้การประหยัดแคชและการโหลดทำงานช้าลงเล็กน้อย แต่แคชจะอยู่ในไฟล์ข้อความ JSON (ยาวมากและไม่มีการเยื้อง; เตรียมตัวแสดง JSON หรือตัวแก้ไขข้อความที่ดีพร้อมความสามารถในการจัดรูปแบบ JSON)
