셸 플러그인

OmarOS 데스크톱은 omaros-shell이라는 단일 장기 실행 Quickshell 프로세스로 실행되며, 화면에서 보는 거의 모든 것은 그 안의 플러그인입니다. 막대도 플러그인입니다. 막대에서 내려오는 패널, 이모지 선택기와 클립보드 관리자 같은 전체 화면 오버레이, 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

또는 메뉴를 사용하세요: _설정 > 플러그인_에는 Enable, Disable, Add, Clone, Remove가 있으며, 각각에 해당 작업에 의미 있는 플러그인만 제공하는 선택기가 있습니다.

활성화 상태는 ~/.config/omaros/shell.json에 저장되며, 규칙은 두 종류의 플러그인에서 약간 다릅니다. 서드파티 플러그인은 그 id가 해당 파일 어딘가에 나타날 때 정확히 활성화됩니다 — 막대 레이아웃 항목으로, plugins[]의 항목으로, 또는 bar.id로요. 막대 위젯이 아닌 자체 플러그인은 그 반대입니다. 기본적으로 켜져 있으며, disabledPlugins[]에 나열되어야만 꺼집니다.

완전한 막대 플러그인에는 꺼짐 상태가 전혀 없습니다. 항상 정확히 하나의 막대가 있으므로, 다른 막대를 활성화해 교체합니다. 막대 위젯 배치는 상단 막대에서 다룹니다.

git에서 플러그인 추가하기

서드파티 플러그인은 루트에 manifest.json이 있는 git repo일 뿐입니다.

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

무언가를 하기 전에, 플러그인이 장기 실행 셸 프로세스 안에서 임의의 샌드박스 처리되지 않은 코드로 실행된다는 점을 분명히 알려주고, URL을 보여주고, 확인을 요청합니다. 진지하게 받아들이세요. 서드파티 플러그인 인터페이스는 인증 서비스를 직접 노출하지 않으며, 교체용 막대는 구성된 인증이 아닌 UI에 대해서만 제한된 기능을 받습니다. 시각적 플러그인은 여전히 셸의 QML 장면을 공유하고 일반적인 부모 객체를 탐색할 수 있으며, 모든 플러그인 코드는 사용자 계정이 닿을 수 있는 모든 권한으로 실행됩니다. 인증 상태는 해당 서비스를 닿을 수 있는 호스트 객체 그래프 밖에 둠으로써 별도로 보호됩니다. 실행할 의향이 있는 repo만 추가하고, 활성화하기 전에 읽어보세요.

교체용 막대는 설치된 위젯을 렌더링할 수 있지만, 막대가 다른 플러그인의 실시간 서비스 객체를 요청할 수 없으므로 서비스 기반 서드파티 위젯은 거기서 기능이 제한될 수 있습니다. 그런 위젯이 동반 서비스를 필요로 한다면 내장 omaros.bar로 돌아가세요.

그런 다음 repo를 준비 디렉터리로 복제하고, manifest를 검증하고, 다른 플러그인이 이미 그 id를 차지하고 있으면 설치를 거부하고, ~/.config/omaros/plugins/<id>/로 이동합니다. --enable 없이 실행하면 지금 켜고 싶은지 묻습니다. 아니오라고 답하고 먼저 코드를 읽을 수 있습니다. 플러그인에서 어떤 것도 실행하지 않고, 설치 훅도 실행하지 않으며, sudo를 요청하지도 않습니다 — 파일을 복제하고, manifest를 검사하고, IPC를 통해 비트를 뒤집습니다.

업데이트는 같은 체크아웃의 fast-forward pull입니다:

omaros plugin update acme.weather
omaros plugin update

id 없이 실행하면 보유한 모든 git 관리 플러그인을 업데이트합니다. 적용하기 전에 diff를 보여주고, fast-forward를 할 수 없는 로컬 변경 사항이 있으면 업데이트를 거부하며, 새 리비전이 검증에 실패하면 롤백합니다.

omaros plugin remove acme.weather

제거하면 먼저 플러그인을 비활성화한 뒤, git 체크아웃이면 삭제하거나(repo는 여전히 원격에 있습니다) 심볼릭 링크이면 링크를 해제합니다. git repo가 없는 수제 플러그인 폴더는 바로 삭제되는 대신 플러그인 디렉터리 안에 있는 타임스탬프가 찍힌 백업으로 이동합니다.

내장 플러그인을 복제해 수정하기

제가 가장 좋아하는 부분입니다. 내장 위젯이 동작하는 방식을 바꾸고 싶다면, $OMAROS_PATH 아래의 파일을 편집하지 마세요 — 그 파일들은 패키지에 속하며 다음 업데이트 때 덮어씌워집니다. 대신 복제하세요:

omaros plugin clone omaros.clock

그러면 전체 플러그인이 ~/.config/omaros/plugins/omar.clock으로 복사되고(제 사용자 이름이 아니라 당신의 사용자 이름입니다), "My Clock"으로 이름이 바뀌고, 활성화되고, 셸이 내장 플러그인에서 당신의 사본으로 전환됩니다 — 기존 막대 위젯의 위치와 설정은 그대로 유지됩니다. --edit를 추가하면 새 디렉터리가 $EDITOR로 바로 열립니다. 메뉴의 _설정 > 플러그인 > 플러그인 복제_가 하는 일이기도 합니다.

사용자 이름 접두사는 복제본의 id를 당신의 것으로 유지하므로, 공유해도 다른 사람의 것과 충돌하지 않습니다. 원래 내장 id로 이루어진 호출은 복제본으로 라우팅되므로, omaros.clock을 참조하던 것은 업데이트할 필요가 없습니다. 그리고 엉망으로 만들었다면, omaros plugin remove omar.clock이 내장 플러그인을 되돌려 놓습니다.

~/.config/omaros/plugins/ 아래 어디에서든 파일을 저장하면 플러그인 코드가 자동으로 다시 로드되므로, 편집기를 열어둔 채 변경 사항이 적용되는 것을 볼 수 있습니다.

직접 작성하기

플러그인은 manifest.json과 약간의 QML이 있는 디렉터리입니다. manifest는 schemaVersion: 1, id, name, version, 하나 이상의 kinds, 그리고 각 kind에 대한 QML 파일을 가리키는 entryPoints 객체를 선언합니다:

Kind	What it is
bar-widget	활성 막대가 섹션에 넣을 수 있는 구성 요소
panel	영구적이거나 소환되는 떠 있는 창
overlay	전체 화면 오버레이
menu	소환되는 메뉴 표면
service	UI가 없는 헤드리스 싱글턴
bar	내장 막대를 교체하는 완전한 막대

플러그인은 한 번에 여러 kind를 선언할 수 있습니다 — 미디어 플러그인은 service이기도 하고 bar-widget이기도 합니다. 막대 위젯은 표시 이름, 범주, 선택적 defaultSection, 그리고 막대에 두 개 이상 있어도 되는지 말해주는 allowMultiple이 있는 추가 barWidget 블록을 받습니다. 대부분의 위젯은 false로 설정합니다. 스페이서와 표시기는 true로 설정합니다.

무언가를 게시하기 전에 검사하세요:

omaros plugin validate ./my-plugin

그러면 셸이 로드할 때 수행하는 것과 같은 검사를 실행합니다. 스키마 버전, 필수 필드, 예약되지 않은 id, 안전하고 실제로 존재하는 상대 경로인 엔트리 포인트, 주장한 모든 kind에 대한 엔트리 포인트, 폴더 안에 심볼릭 링크가 없는지 검사합니다.

플러그인 개발에 대해서는 셸 참조와 자체 플러그인 카탈로그를 참고하세요.

당신의 플러그인을 세상과 공유하기

마음에 드는 것을 만들었다면, 공개 git repo에 넣으세요. 그게 전체 배포 메커니즘입니다 — 그러면 누구나 당신의 URL에 omaros plugin add를 실행해 몇 초 만에 실행할 수 있습니다.