افزونه‌های شل

دسکتاپ OmarOS به‌صورت یک فرایند Quickshell بلندعمر واحد به نام omaros-shell اجرا می‌شود، و تقریباً هر آنچه روی صفحه می‌بینید یک افزونه داخل آن است. نوار یک افزونه است. پنل‌هایی که از آن پایین می‌آیند، پوشش‌های تمام‌صفحه مانند انتخاب‌گر ایموجی و مدیر کلیپ‌بورد، خود منوی OmarOS، صفحه قفل، گفتگوی polkit، و خدمات بدون سر که باتری شما را تماشا می‌کنند و صفحه شما را در شب گرم می‌کنند هم همین‌طور هستند.

این فقط یک جزئیات پیاده‌سازی نیست. یعنی می‌توانید بخش‌هایی از دسکتاپ را خاموش کنید، آن‌ها را عوض کنید، یا مال خود را بدون دست زدن به یک خط از منبع OmarOS بنویسید.

افزونه‌های شخص اول با OmarOS ارائه می‌شوند و در $OMAROS_PATH/shell/plugins/ زندگی می‌کنند. هر چیزی که خودتان اضافه کنید — آزمایش‌های خودتان، یا چیزی که روی GitHub پیدا کردید — در ~/.config/omaros/plugins/ زندگی می‌کند. هر دو در شروع به همان روش کشف می‌شوند، اما افزونه‌های داخلی رابط‌های شل مورد اعتماد دریافت می‌کنند در حالی که افزونه‌های شخص ثالث یک رابط محدود محدود به خدمت و چرخه عمر خودشان دریافت می‌کنند. کلون‌های افزونه‌های داخلی فقط پیکربندی خاص منبع و فراخوانی‌های UI لازم برای رفتار اصلی را نگه می‌دارند.

دیدن آنچه دارید

omaros plugin list

این هر افزونه کشف‌شده را با شناسه آن، اینکه فعال هست یا نه، اینکه شخص اول است یا شخص ثالث، انواع آن، و نام نمایشی آن چاپ می‌کند. --json را اضافه کنید اگر آن را به چیز دیگری تغذیه می‌کنید.

شناسه‌های افزونه فضای نام دارند. افزونه‌های داخلی همه با omaros. شروع می‌شوند — omaros.clock، omaros.network، omaros.notifications — و آن فضای نام رزرو شده است، پس یک افزونه شخص ثالث هرگز نمی‌تواند آن را ادعا کند.

روشن و خاموش کردن آن‌ها

omaros plugin enable omaros.tailscale
omaros plugin disable omaros.weather

یا از منو استفاده کنید: تنظیمات > Plugins، Enable، Disable، Add، Clone و Remove دارد، هر یک با یک انتخاب‌گر که فقط افزونه‌هایی را پیشنهاد می‌دهد که برای آن اقدام معنا دارند.

وضعیت فعال در ~/.config/omaros/shell.json ذخیره می‌شود، و قانون برای دو نوع افزونه کمی متفاوت است. یک افزونه شخص ثالث دقیقاً وقتی فعال است که شناسه آن جایی در آن فایل ظاهر شود — به‌صورت یک ورودی چیدمان نوار، به‌صورت یک ورودی در plugins[]، یا به‌صورت bar.id. افزونه‌های شخص اول که ویجت نوار نیستند برعکس هستند: به‌طور پیش‌فرض روشن هستند و فقط با فهرست شدن در disabledPlugins[] خاموش می‌شوند.

یک افزونه نوار کامل اصلاً وضعیت خاموش ندارد. همیشه دقیقاً یک نوار وجود دارد، پس آن را با فعال کردن یکی دیگر جایگزین می‌کنید. جای‌گذاری ویجت نوار در نوار بالا پوشش داده شده است.

افزودن یک افزونه از git

یک افزونه شخص ثالث فقط یک مخزن git با یک manifest.json در ریشه آن است.

omaros plugin add https://github.com/acme/omaros-weather.git --enable

پیش از انجام هر کاری، به‌طور واضح به شما می‌گوید که افزونه‌ها به‌صورت کد دلخواه و بدون سندباکس داخل فرایند شل بلندعمر شما اجرا می‌شوند، URL را به شما نشان می‌دهد، و از شما درخواست تأیید می‌کند. این را جدی بگیرید. رابط افزونه شخص ثالث مستقیم خدمات احراز هویت را در معرض نمی‌گذارد، و یک نوار جایگزین فقط قابلیت‌های محدودی برای UI غیر احراز هویت پیکربندی‌شده دریافت می‌کند. افزونه‌های بصری هنوز صحنه QML شل را به اشتراک می‌گذارند و می‌توانند اشیای والد عادی را بپیمایند، در حالی که همه کد افزونه با هر آنچه حساب کاربری شما می‌تواند برسد اجرا می‌شود. وضعیت احراز هویت جداگانه با نگه داشتن آن خدمات خارج از گراف شیء میزبان قابل دسترسی محافظت می‌شود. فقط مخازنی را اضافه کنید که مایل به اجرا هستید، و پیش از فعال کردن آن‌ها را بخوانید.

یک نوار جایگزین می‌تواند ویجت‌های نصب‌شده را رندر کند، اما ویجت‌های شخص ثالث پشتیبانی‌شده توسط خدمت ممکن است در آنجا عملکرد کمتری داشته باشند چون نوار مجاز نیست شیء خدمت زنده یک افزونه دیگر را درخواست کند. اگر چنین ویجتی به خدمت همراه خود نیاز دارد، به omaros.bar داخلی برگردید.

آنگاه مخزن را در یک پوشه مرحله‌بندی کلون می‌کند، مانیفست را اعتبارسنجی می‌کند، اگر افزونه دیگری از قبل آن شناسه را ادعا کند نصب را رد می‌کند، و آن را به ~/.config/omaros/plugins/<id>/ منتقل می‌کند. بدون --enable می‌پرسد آیا می‌خواهید اکنون روشن باشد، و می‌توانید نه بگویید و اول کد را بخوانید. هرگز چیزی از افزونه اجرا نمی‌کند، هرگز قلاب نصب اجرا نمی‌کند، و هرگز sudo نمی‌خواهد — فایل‌ها را کلون می‌کند، مانیفست را بررسی می‌کند، و یک بیت را از طریق IPC برمی‌گرداند.

به‌روزرسانی یک کشش سریع به جلو از همان چک‌اوت است:

omaros plugin update acme.weather
omaros plugin update

بدون شناسه، هر افزونه مدیریت‌شده توسط git که دارید را به‌روز می‌کند. پیش از اعمال آن diff را به شما نشان می‌دهد، اگر تغییرات محلی‌ای داشته باشید که نمی‌تواند از آن‌ها سریع به جلو برود از به‌روزرسانی خودداری می‌کند، و اگر بازبینی جدید در اعتبارسنجی شکست بخورد بازمی‌گرداند.

omaros plugin remove acme.weather

حذف اول افزونه را غیرفعال می‌کند، آنگاه اگر یک چک‌اوت git باشد آن را حذف می‌کند (مخزن هنوز در بالادست است) یا اگر یک پیوند نمادین باشد آن را جدا می‌کند. یک پوشه افزونه دست‌ساز بدون مخزن git به یک پشتیبان دارای مهر زمان داخل پوشه افزونه‌ها منتقل می‌شود به جای اینکه کاملاً حذف شود.

کلون کردن یک افزونه داخلی برای تغییر آن

این بخش مورد علاقه من است. اگر می‌خواهید نحوه رفتار یک ویجت داخلی را تغییر دهید، فایل‌های زیر $OMAROS_PATH را ویرایش نکنید — آن‌ها متعلق به بسته هستند و به‌روزرسانی بعدی آن‌ها را بازنویسی می‌کند. به جای آن آن را کلون کنید:

omaros plugin clone omaros.clock

این کل افزونه را در ~/.config/omaros/plugins/omar.clock (نام کاربری شما، نه مال من) کپی می‌کند، آن را به «My Clock» تغییر نام می‌دهد، آن را فعال می‌کند، و شل را از داخلی به نسخه شما جابه‌جا می‌کند — در حالی که موقعیت و تنظیمات یک ویجت نوار موجود را نگه می‌دارد. --edit را اضافه کنید تا پوشه جدید را بلافاصله در $EDITOR خود باز کنید، که همان کاری است که تنظیمات > Plugins > Clone Plugin منو برای شما انجام می‌دهد.

پیشوند نام کاربری شناسه کلون شما را مال شما نگه می‌دارد، پس اشتراک‌گذاری آن با مال هیچ‌کس دیگری برخورد نمی‌کند. فراخوانی‌های انجام‌شده به شناسه داخلی اصلی به کلون شما هدایت می‌شوند، پس هیچ چیزی که به omaros.clock ارجاع داده نیازی به به‌روزرسانی ندارد. و اگر آن را به‌هم بریزید، omaros plugin remove omar.clock داخلی را برمی‌گرداند.

ذخیره یک فایل در هر جایی زیر ~/.config/omaros/plugins/ کد افزونه را به‌طور خودکار دوباره بار می‌کند، پس می‌توانید ویرایشگر را باز بگذارید و فرود تغییرات خود را تماشا کنید.

نوشتن افزونه خودتان

یک افزونه یک پوشه با یک manifest.json و کمی QML است. مانیفست schemaVersion: 1، یک id، name، version، یک یا چند kinds، و یک شیء entryPoints که به فایل QML برای هر نوع اشاره می‌کند اعلام می‌کند:

Kind	What it is
bar-widget	کامپوننتی که نوار فعال می‌تواند در یک بخش بیندازد
panel	یک پنجره شناور پایدار یا احضارشده
overlay	یک پوشش تمام‌صفحه
menu	یک سطح منوی احضارشده
service	یک سینگلتون بدون سر بدون UI
bar	یک نوار کامل که جایگزین داخلی می‌شود

یک افزونه می‌تواند چند نوع را هم‌زمان اعلام کند — افزونه رسانه هم یک service و هم یک bar-widget است. ویجت‌های نوار یک بلوک barWidget اضافی با یک نام نمایشی، یک دسته، یک defaultSection اختیاری، و allowMultiple می‌گیرند، که می‌گوید آیا داشتن بیش از یکی روی نوار معنا دارد یا نه. بیشتر ویجت‌ها آن را روی false تنظیم می‌کنند؛ فاصله‌گذارها و نشانگرها آن را روی true تنظیم می‌کنند.

پیش از انتشار هر چیزی، آن را بررسی کنید:

omaros plugin validate ./my-plugin

این همان بررسی‌هایی را اجرا می‌کند که شل در زمان بارگذاری انجام می‌دهد: نسخه طرحواره، فیلدهای الزامی، یک شناسه که رزرو نشده باشد، نقاط ورودی که مسیرهای نسبی امن هستند و واقعاً وجود دارند، یک نقطه ورودی برای هر نوعی که ادعا کردید، و هیچ پیوند نمادین در هیچ جایی داخل پوشه.

برای توسعه افزونه، مرجع شل و کاتالوگ افزونه‌های شخص اول را ببینید.

اشتراک‌گذاری افزونه خود با جهان

وقتی چیزی ساختید که دوست دارید، آن را در یک مخزن git عمومی بگذارید. این کل سازوکار توزیع است — هر کسی آنگاه می‌تواند omaros plugin add را در برابر URL شما اجرا کند و در چند ثانیه آن را در حال اجرا داشته باشد.