Plugins del shell¶
El escritorio de OmarOS se ejecuta como un solo proceso Quickshell de larga vida llamado omaros-shell, y casi todo lo que ves en pantalla es un plugin dentro de él. La barra es un plugin. También lo son los paneles que se despliegan desde ella, las superposiciones de pantalla completa como el selector de emojis y el gestor del portapapeles, el propio menú de OmarOS, la pantalla de bloqueo, el diálogo de polkit y los servicios sin interfaz que vigilan tu batería y calientan tu pantalla por la noche.
Eso no es solo un detalle de implementación. Significa que puedes apagar partes del escritorio, intercambiarlas o escribir las tuyas sin tocar una línea del código fuente de OmarOS.
Los plugins oficiales vienen con OmarOS y viven en $OMAROS_PATH/shell/plugins/. Todo lo que agregues tú —tus propios experimentos, o algo que encontraste en GitHub— vive en ~/.config/omaros/plugins/. Ambos se descubren de la misma forma al iniciar, pero los integrados reciben interfaces de shell de confianza mientras que los plugins de terceros reciben una interfaz limitada y acotada a su propio servicio y ciclo de vida. Los clones de los integrados conservan solo la configuración específica de la fuente y las llamadas de interfaz necesarias para el comportamiento original.
Ver lo que tienes¶
Eso imprime cada plugin descubierto con su id, si está habilitado, si es oficial o de terceros, sus tipos y su nombre para mostrar. Agrega --json si lo vas a pasar a otra cosa.
Los ids de plugin tienen espacio de nombres. Todos los integrados empiezan con omaros. —omaros.clock, omaros.network, omaros.notifications— y ese espacio de nombres está reservado, así que un plugin de terceros nunca puede reclamarlo.
Activarlos y desactivarlos¶
O usa el menú: Configurar > Plugins tiene Activar, Desactivar, Agregar, Clonar y Quitar, cada uno con un selector que solo ofrece los plugins que tienen sentido para esa acción.
El estado habilitado se guarda en ~/.config/omaros/shell.json, y la regla difiere ligeramente para los dos tipos de plugin. Un plugin de terceros está habilitado exactamente cuando su id aparece en algún lugar de ese archivo: como una entrada de distribución de la barra, como una entrada en plugins[], o como bar.id. Los plugins oficiales que no son widgets de la barra son al revés: están activados por defecto y solo se apagan si se listan en disabledPlugins[].
Un plugin de barra completa no tiene estado apagado en absoluto. Siempre hay exactamente una barra, así que la reemplazas habilitando otra. La colocación de widgets de la barra se cubre en la barra superior.
Agregar un plugin desde git¶
Un plugin de terceros es simplemente un repositorio git con un manifest.json en su raíz.
Antes de hacer nada, te dice claramente que los plugins se ejecutan como código arbitrario y sin sandbox dentro de tu proceso de shell de larga vida, te muestra la URL y te pide que confirmes. Tómalo en serio. La interfaz de plugins de terceros no expone directamente los servicios de autenticación, y una barra de reemplazo recibe solo capacidades limitadas para la interfaz configurada que no es de autenticación. Los plugins visuales aun así comparten la escena QML del shell y pueden recorrer los objetos padre ordinarios, mientras que todo el código de plugins se ejecuta con todo lo que tu cuenta de usuario puede alcanzar. El estado de autenticación se protege por separado manteniendo esos servicios fuera del grafo de objetos host alcanzable. Solo agrega repositorios que estés dispuesto a ejecutar, y léelos antes de habilitarlos.
Una barra de reemplazo puede renderizar los widgets instalados, pero los widgets de terceros respaldados por un servicio pueden tener funcionalidad reducida ahí porque a la barra no se le permite solicitar el objeto de servicio activo de otro plugin. Vuelve a la omaros.bar integrada si tal widget necesita su servicio compañero.
Después clona el repositorio en un directorio temporal, valida el manifiesto, rechaza la instalación si otro plugin ya reclama ese id, y lo mueve a ~/.config/omaros/plugins/<id>/. Sin --enable te pregunta si quieres que esté activado ahora, y puedes decir que no e ir a leer el código primero. Nunca ejecuta nada del plugin, nunca ejecuta un hook de instalación y nunca pide sudo: clona archivos, revisa el manifiesto y cambia un bit por IPC.
Actualizar es un pull de avance rápido de esa misma copia:
Sin id, actualiza cada plugin gestionado por git que tengas. Te muestra el diff antes de aplicarlo, se niega a actualizar si tienes cambios locales que no puede superar con avance rápido, y revierte si la nueva revisión no pasa la validación.
La eliminación primero deshabilita el plugin, y luego lo borra si es una copia git (el repositorio sigue en el origen) o lo desenlaza si es un enlace simbólico. Una carpeta de plugin hecha a mano sin repositorio git se mueve a una copia de seguridad con marca de tiempo dentro del directorio de plugins en lugar de borrarse sin más.
Clonar un integrado para modificarlo¶
Esta es mi parte favorita. Si quieres cambiar cómo se comporta un widget integrado, no edites los archivos bajo $OMAROS_PATH: esos pertenecen al paquete y la próxima actualización los sobrescribirá. Clónalo en su lugar:
Eso copia todo el plugin a ~/.config/omaros/plugins/omar.clock (tu nombre de usuario, no el mío), lo renombra a "My Clock", lo habilita y cambia el shell del integrado a tu copia, conservando la posición y los ajustes de un widget de barra existente. Agrega --edit para abrir el directorio nuevo en tu $EDITOR de inmediato, que es lo que hace por ti el Configurar > Plugins > Clone Plugin del menú.
El prefijo de nombre de usuario hace que el id de tu clon sea tuyo, así que compartirlo no choca con el de nadie más. Las llamadas hechas al id integrado original se enrutan a tu clon, así que nada que se refiera a omaros.clock necesita actualizarse. Y si haces un desastre, omaros plugin remove omar.clock vuelve a poner el integrado.
Guardar un archivo en cualquier lugar bajo ~/.config/omaros/plugins/ recarga el código del plugin automáticamente, así que puedes dejar el editor abierto y ver cómo llegan tus cambios.
Escribir los tuyos¶
Un plugin es un directorio con un manifest.json y algo de QML. El manifiesto declara schemaVersion: 1, un id, name, version, uno o más kinds, y un objeto entryPoints que apunta al archivo QML de cada tipo:
| Kind | What it is |
|---|---|
bar-widget |
Un componente que la barra activa puede poner en una sección |
panel |
Una ventana flotante persistente o invocada |
overlay |
Una superposición de pantalla completa |
menu |
Una superficie de menú invocada |
service |
Un singleton sin interfaz y sin UI |
bar |
Una barra completa que reemplaza a la integrada |
Un plugin puede declarar varios tipos a la vez: el plugin de medios es a la vez un service y un bar-widget. Los widgets de barra reciben un bloque barWidget extra con un nombre para mostrar, una categoría, un defaultSection opcional y allowMultiple, que dice si tiene sentido tener más de uno en la barra. La mayoría de los widgets lo pone en false; los espaciadores e indicadores lo ponen en true.
Antes de publicar nada, revísalo:
Eso ejecuta las mismas comprobaciones que hace el shell al cargar: la versión del esquema, los campos obligatorios, un id que no esté reservado, puntos de entrada que sean rutas relativas seguras y que realmente existan, un punto de entrada para cada tipo que reclamaste, y ningún enlace simbólico en ningún lugar dentro de la carpeta.
Para el desarrollo de plugins, consulta la referencia del shell y el catálogo de plugins oficiales.
Compartir los tuyos con el mundo¶
Una vez que hayas hecho algo que te guste, ponlo en un repositorio git público. Ese es todo el mecanismo de distribución: cualquiera puede entonces ejecutar omaros plugin add contra tu URL y tenerlo funcionando en segundos.