Plug-ins do shell

A área de trabalho do OmarOS é executada como um único processo Quickshell de vida longa chamado omaros-shell, e quase tudo o que você vê na tela é um plug-in dentro dele. A barra é um plug-in. Também são os painéis que descem dela, as sobreposições em tela cheia como o seletor de emoji e o gerenciador de área de transferência, o próprio menu do OmarOS, a tela de bloqueio, a caixa de diálogo do polkit e os serviços sem interface que observam sua bateria e aquecem sua tela à noite.

Isso não é apenas um detalhe de implementação. Isso significa que você pode desligar partes da área de trabalho, trocá-las ou escrever as suas próprias sem tocar em uma linha do código-fonte do OmarOS.

Os plug-ins originais vêm com o OmarOS e ficam em $OMAROS_PATH/shell/plugins/. Qualquer coisa que você adicione você mesmo — seus próprios experimentos, ou algo que você encontrou no GitHub — fica em ~/.config/omaros/plugins/. Os dois são descobertos da mesma maneira na inicialização, mas os integrados recebem interfaces de shell confiáveis, enquanto plug-ins de terceiros recebem uma interface limitada, restrita ao seu próprio serviço e ciclo de vida. Clones dos integrados mantêm apenas a configuração específica da fonte e as chamadas de interface necessárias para o comportamento original.

Vendo o que você tem

omaros plugin list

Isso imprime todos os plug-ins descobertos, com seu id, se está ativado, se é original ou de terceiros, seus tipos e seu nome de exibição. Adicione --json se você for alimentá-lo em outra coisa.

Os ids dos plug-ins têm namespaces. Os integrados todos começam com omaros. — omaros.clock, omaros.network, omaros.notifications — e esse namespace é reservado, então um plug-in de terceiros nunca poderá reivindicá-lo.

Ligando-os e desligando-os

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

Ou use o menu: Setup > Plugins tem Ativar, Desativar, Adicionar, Clonar e Remover, cada um com um seletor que só oferece os plug-ins que fazem sentido para aquela ação.

O estado ativado é armazenado em ~/.config/omaros/shell.json, e a regra difere ligeiramente para os dois tipos de plug-in. Um plug-in de terceiros é ativado exatamente quando seu id aparece em algum lugar desse arquivo — como uma entrada do layout da barra, como uma entrada em plugins[], ou como bar.id. Plug-ins originais que não são widgets da barra são o contrário: eles estão ligados por padrão e só desligam ao serem listados em disabledPlugins[].

Um plug-in de barra completa não tem nenhum estado desligado. Sempre há exatamente uma barra, então você a substitui ativando outra. A colocação de widgets na barra é coberta em a barra superior.

Adicionando um plug-in do git

Um plug-in de terceiros é apenas um repositório git com um manifest.json na sua raiz.

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

Antes de fazer qualquer coisa, ele lhe diz simplesmente que plug-ins são executados como código arbitrário, sem sandbox, dentro do seu processo de shell de vida longa, mostra a URL e pede sua confirmação. Leve isso a sério. A interface de plug-ins de terceiros não expõe serviços de autenticação diretamente, e uma barra substituta recebe apenas capacidades limitadas para a interface configurada sem autenticação. Plug-ins visuais ainda compartilham a cena QML do shell e podem percorrer objetos pais comuns, enquanto todo o código de plug-in é executado com tudo o que sua conta de usuário pode alcançar. O estado de autenticação é protegido separadamente, mantendo esses serviços fora do grafo de objetos alcançável do host. Só adicione repositórios que você esteja disposto a executar, e leia-os antes de ativá-los.

Uma barra substituta pode renderizar widgets instalados, mas widgets de terceiros respaldados por serviços podem ter funcionalidade reduzida ali, porque a barra não tem permissão para solicitar o objeto de serviço ativo de outro plug-in. Volte para o omaros.bar integrado se esse widget precisar do seu serviço complementar.

Depois ele clona o repositório para um diretório de preparação, valida o manifesto, recusa a instalação se outro plug-in já reivindicar aquele id e o move para ~/.config/omaros/plugins/<id>/. Sem --enable, ele pergunta se você quer que ele esteja ligado agora, e você pode dizer não e ir ler o código primeiro. Ele nunca executa nada do plug-in, nunca executa um gancho de instalação e nunca pede sudo — ele clona arquivos, verifica o manifesto e inverte um bit via IPC.

A atualização é um pull com fast-forward desse mesmo checkout:

omaros plugin update acme.weather
omaros plugin update

Sem nenhum id, ele atualiza todos os plug-ins gerenciados pelo git que você tem. Ele mostra o diff antes de aplicá-lo, recusa a atualização se você tiver alterações locais pelas quais não consiga fazer fast-forward e faz rollback se a nova revisão falhar na validação.

omaros plugin remove acme.weather

A remoção desativa o plug-in primeiro e depois o exclui se for um checkout git (o repositório ainda está no upstream) ou o desvincula se for um link simbólico. Uma pasta de plug-in feita à mão sem nenhum repositório git é movida para um backup com marca de tempo dentro do diretório de plug-ins em vez de ser excluída diretamente.

Clonando um integrado para modificá-lo

Esta é minha parte favorita. Se você quiser alterar como um widget integrado se comporta, não edite os arquivos em $OMAROS_PATH — eles pertencem ao pacote e a próxima atualização os sobrescreverá. Clone-o:

omaros plugin clone omaros.clock

Isso copia todo o plug-in para ~/.config/omaros/plugins/omar.clock (seu nome de usuário, não o meu), renomeia-o para "My Clock", ativa-o e muda o shell do integrado para a sua cópia — mantendo a posição e as configurações de um widget de barra existente. Adicione --edit para abrir o novo diretório no seu $EDITOR imediatamente, que é o que o Setup > Plugins > Clone Plugin do menu faz por você.

O prefixo de nome de usuário mantém o id do seu clone seu, então compartilhá-lo não colide com o de mais ninguém. As chamadas feitas para o id integrado original são roteadas para o seu clone, então nada que se referia a omaros.clock precisa ser atualizado. E se você fizer uma bagunça, omaros plugin remove omar.clock coloca o integrado de volta.

Salvar um arquivo em qualquer lugar sob ~/.config/omaros/plugins/ recarrega o código do plug-in automaticamente, então você pode deixar o editor aberto e ver suas alterações acontecerem.

Escrevendo o seu próprio

Um plug-in é um diretório com um manifest.json e algum QML. O manifesto declara schemaVersion: 1, um id, name, version, um ou mais kinds, e um objeto entryPoints apontando para o arquivo QML de cada tipo:

Tipo	O que é
bar-widget	Um componente que a barra ativa pode colocar em uma seção
panel	Uma janela flutuante persistente ou invocada
overlay	Uma sobreposição em tela cheia
menu	Uma superfície de menu invocada
service	Um singleton sem interface e sem UI
bar	Uma barra completa que substitui a integrada

Um plug-in pode declarar vários tipos ao mesmo tempo — o plug-in de mídia é ao mesmo tempo um service e um bar-widget. Widgets de barra ganham um bloco barWidget extra com um nome de exibição, uma categoria, um defaultSection opcional e allowMultiple, que diz se faz sentido ter mais de um na barra. A maioria dos widgets define isso como false; espaçadores e indicadores definem como true.

Antes de publicar qualquer coisa, verifique-a:

omaros plugin validate ./my-plugin

Isso executa as mesmas verificações que o shell faz no momento do carregamento: a versão do esquema, os campos obrigatórios, um id que não é reservado, pontos de entrada que são caminhos relativos seguros e que realmente existem, um ponto de entrada para cada tipo que você declarou, e nenhum link simbólico em nenhum lugar dentro da pasta.

Para o desenvolvimento de plug-ins, consulte a referência do shell e o catálogo de plug-ins originais.

Compartilhando o seu com o mundo

Depois que você fizer algo de que goste, coloque-o em um repositório git público. Esse é todo o mecanismo de distribuição — qualquer pessoa pode então executar omaros plugin add com sua URL e tê-lo em execução em segundos.