Плагины оболочки

Рабочий стол OmarOS работает как один долгоживущий процесс Quickshell под названием omaros-shell, и почти всё, что вы видите на экране, является плагином внутри него. Панель — это плагин. Как и панели, выпадающие из неё, полноэкранные наложения вроде средства выбора эмодзи и менеджера буфера обмена, само меню OmarOS, экран блокировки, диалог polkit и безголовые службы, которые следят за вашей батареей и согревают экран ночью.

Это не просто деталь реализации. Это означает, что вы можете отключать части рабочего стола, заменять их или писать свои собственные, не трогая ни строчки исходного кода OmarOS.

Плагины первого уровня поставляются с OmarOS и живут в $OMAROS_PATH/shell/plugins/. Всё, что вы добавляете сами, — ваши собственные эксперименты или что-то найденное на GitHub, — живёт в ~/.config/omaros/plugins/. Оба обнаруживаются одинаковым способом при запуске, но встроенные получают доверенные интерфейсы оболочки, а сторонние плагины получают ограниченный интерфейс, ограниченный их собственной службой и жизненным циклом. Клоны встроенных сохраняют только конфигурацию, специфичную для источника, и вызовы UI, нужные для оригинального поведения.

Просмотр того, что у вас есть

omaros plugin list

Это выводит каждый обнаруженный плагин с его id, включён ли он, является ли он плагином первого уровня или сторонним, его видами и отображаемым именем. Добавьте --json, если вы передаёте это чему-то ещё.

Id плагинов имеют пространство имён. Все встроенные начинаются с 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, и правило слегка различается для двух видов плагинов. Сторонний плагин включён ровно тогда, когда его id появляется где-то в этом файле — как запись раскладки панели, как запись в plugins[] или как bar.id. С плагинами первого уровня, которые не являются виджетами панели, всё наоборот: они включены по умолчанию и выключаются только внесением в disabledPlugins[].

У полноценного плагина панели нет состояния «выключено» вообще. Панель всегда ровно одна, поэтому вы заменяете её, включив другую. Размещение виджетов панели описано в разделе верхняя панель.

Добавление плагина из git

Сторонний плагин — это просто репозиторий git с файлом manifest.json в корне.

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

Прежде чем что-либо сделать, он прямо говорит вам, что плагины работают как произвольный код без песочницы внутри вашего долгоживущего процесса оболочки, показывает URL и просит подтвердить. Отнеситесь к этому серьёзно. Интерфейс сторонних плагинов напрямую не предоставляет службы аутентификации, а заменяющая панель получает только ограниченные возможности для настроенного UI без аутентификации. Визуальные плагины по-прежнему разделяют QML-сцену оболочки и могут обходить обычные родительские объекты, а весь код плагинов работает со всем, до чего может дотянуться ваша учётная запись пользователя. Состояние аутентификации защищено отдельно за счёт удержания этих служб вне достижимого графа объектов хоста. Добавляйте только репозитории, которые вы готовы запускать, и читайте их, прежде чем включать.

Заменяющая панель может отображать установленные виджеты, но сторонние виджеты со службой могут иметь там ограниченную функциональность, поскольку панели не разрешено запрашивать живой объект службы другого плагина. Вернитесь к встроенной omaros.bar, если такому виджету нужна его сопутствующая служба.

Затем он клонирует репозиторий в промежуточный каталог, проверяет манифест, отказывает в установке, если другой плагин уже заявил этот id, и перемещает его в ~/.config/omaros/plugins/<id>/. Без --enable он спросит, хотите ли вы включить его сейчас, и можно сказать «нет» и сначала пойти почитать код. Он никогда не запускает ничего из плагина, никогда не выполняет установочный хук и никогда не просит sudo — он клонирует файлы, проверяет манифест и переключает бит по IPC.

Обновление — это fast-forward pull того же самого клона:

omaros plugin update acme.weather
omaros plugin update

Без id он обновляет каждый управляемый через git плагин, который у вас есть. Он показывает вам diff перед применением, отказывается обновлять, если у вас есть локальные изменения, через которые он не может выполнить fast-forward, и откатывается, если новая ревизия не проходит проверку.

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.

Префикс имени пользователя сохраняет id вашего клона вашим, поэтому его передача другим не столкнётся ни с чьим ещё. Вызовы, сделанные к оригинальному встроенному id, перенаправляются на ваш клон, так что ничто, что ссылалось на 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	Безголовый singleton без UI
bar	Полноценная панель, заменяющая встроенную

Плагин может объявлять несколько видов сразу — плагин media является одновременно и service, и bar-widget. Виджеты панели получают дополнительный блок barWidget с отображаемым именем, категорией, необязательным defaultSection и allowMultiple, который говорит, имеет ли смысл иметь на панели больше одного. Большинство виджетов задают его как false; разделители и индикаторы задают его как true.

Прежде чем что-либо публиковать, проверьте это:

omaros plugin validate ./my-plugin

Это запускает те же проверки, которые оболочка выполняет во время загрузки: версию схемы, обязательные поля, id, который не зарезервирован, точки входа, являющиеся безопасными относительными путями и действительно существующие, точку входа для каждого заявленного вами вида и отсутствие символических ссылок где-либо внутри папки.

О разработке плагинов см. справочник по оболочке и каталог плагинов первого уровня.

Делитесь своими со всем миром

Как только вы сделали что-то, что вам нравится, поместите это в публичный репозиторий git. Это весь механизм распространения — после этого любой может выполнить omaros plugin add против вашего URL и получить работающий плагин за секунды.