Alterator/module/structure: различия между версиями

Материал из ALT Linux Wiki
Нет описания правки
 
(не показана 1 промежуточная версия этого же участника)
Строка 6: Строка 6:


==== Расположение файлов и каталогов ====
==== Расположение файлов и каталогов ====
Стандартный модуль alterator может содержать следующие каталоги (их может инициализировать скрипт из пакета <tt>alterator-sdk</tt>):
Стандартный модуль alterator может содержать следующие каталоги:
* '''help''' — документация
* '''backend2''' — нативные бэкенды
* '''backend2''' — нативные бэкенды
* '''backend3''' — внешние бэкенды
* '''backend3''' — внешние бэкенды
* '''ui''' — описания интерфейсов (qt)
* '''ui''' — описания интерфейсов
* '''templates''' — описания интерфейсов (html)
* '''applications''' — desktop-файлы с описанием модуля (для отображения в меню центра управления)
* '''applications''' — desktop-файлы с описанием модуля (для отображения в меню центра управления)
* '''desktop-directories''' — directory-файлы с описанием групп модулей (для отображения в меню центра управления)
* '''desktop-directories''' — directory-файлы с описанием групп модулей (для отображения в меню центра управления)
Строка 19: Строка 17:


Файлы описания интерфейсов раскладываются следующим образом:
Файлы описания интерфейсов раскладываются следующим образом:
* html-описание, адресуемое как '''/foo/bar''', должно находиться в файле '''templates/foo/bar/index.html'''
* html-описание, адресуемое как '''/foo/bar''', должно находиться в файле '''ui/foo/bar/index.html'''
* qt-описание, адресуемое как '''/foo/bar''', должно находиться в файле '''ui/foo/bar/index.scm'''
* qt-описание, адресуемое как '''/foo/bar''', должно находиться в файле '''ui/foo/bar/index.scm'''
Документация пишется в формате html и раскладывается в подкаталоги, соответствующие названию локали. Справка, по теме '''«foo»''' для русского языка должна находиться в файле '''help/ru_RU/foo.html''', а для украинского — в файле '''help/uk_UA/foo.html'''


Файлы стилей размещаются в директории '''design''', ссылка в html-интерфейсе на файл стилей '''/design/my.css'''
Файлы стилей размещаются в директории '''design''', ссылка в html-интерфейсе на файл стилей '''/design/my.css'''

Текущая версия от 16:11, 3 февраля 2009

Структура модуля

Название модуля

Все модули называются в стиле alterator-<имя>. Предпочтительно в качестве <имя> использовать название конкретного сервиса, а не решаемую задачу . Например, alterator-postfix лучше чем alterator-mail, потому что может существовать ещё модуль alterator-sendmail.

Расположение файлов и каталогов

Стандартный модуль alterator может содержать следующие каталоги:

  • backend2 — нативные бэкенды
  • backend3 — внешние бэкенды
  • ui — описания интерфейсов
  • applications — desktop-файлы с описанием модуля (для отображения в меню центра управления)
  • desktop-directories — directory-файлы с описанием групп модулей (для отображения в меню центра управления)
  • design — дополнительные к стандартным файлы с изображениями, стилями, скриптами.

Каталоги с бэкендами не имеют никакой вложенной иерархии: бэкенд, адресуемый как /foo должен находиться в файле backend3/foo, если это внешний бэкенд, и backend2/foo, если это нативный бэкенд.

Файлы описания интерфейсов раскладываются следующим образом:

  • html-описание, адресуемое как /foo/bar, должно находиться в файле ui/foo/bar/index.html
  • qt-описание, адресуемое как /foo/bar, должно находиться в файле ui/foo/bar/index.scm

Файлы стилей размещаются в директории design, ссылка в html-интерфейсе на файл стилей /design/my.css

Регистрация в центре управления

Центр управления — это прежде всего способ объединить разрозненные модули alterator. Каждый модуль содержит некоторое описание, на основании которого вычисляется его имя и местоположение внутри двухуровневого меню. Это описание имеет традиционный формат desktop-файла и располагается в каталоге applications. Модули объединяются в группы (первый уровень меню), каждая группа имеет описание в виде directory-файла и располагается в каталоге desktop-directories. Группы связаны с модулями косвенно через так называемые категории.

Описание группы

В файле описания группы модулей используются следующие параметры:

  • Name — имя группы. Также возможна запись локализованных имён в параметрах Name[locale], где locale — имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8.
  • Icon — картинка для группы, пока не используется
  • Type — всегда равно directory
  • X-Alterator-Category — имя категории, которую представляет данная группа.
  • X-Alterator-Weight — вес группы. В меню группы сортируются согласно их весу.

Пример описания группы:

[Desktop Entry]
Type=Directory
Name=Statistics
Name[ru]=Статистика
Icon=system
X-Alterator-Category=X-Alterator-Statistics
X-Alterator-Weight=15
Описание модуля

В файле описания модуля используются следующие параметры:

  • Name — имя модуля. Также возможна запись локализованных имён в параметрах Name[locale], где locale — имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8.
  • Icon — картинка для модуля, пока не используется
  • Categories — категории, с которыми связан данный модуль (пока допустимо перечислять только одну категорию)
  • Type — всегда равно application
  • Terminal — всегда равно false.
  • X-Alterator-URI — местоположение модуля (трактовка несколько отличается в acc и в fbi)
  • X-Alterator-Help — название темы справки. Справка пишется в формате html и размещается по адресу /usr/share/alterator/help/locale/name.html, где locale — полное имя локали, а name — имя, указанное в данном параметре.
  • X-Alterator-Weight — вес модуля. Внутри группы, элементы сортируются согласно их весу.

Пример описания модуля:

[Desktop Entry]
Type=Application
Categories=X-Alterator-System
Icon=control
Terminal=false
Name=System objects
Name[ru]=Системные объекты
Name[uk]=Системні об'єкти
X-Alterator-URI=/control
X-Alterator-Weight=10
X-Alterator-Help=control

Замечание про разные интерфейсы

Система меню и справки едина и для GUI и HTML интерфейса, однако до сих пор ещё встречаются модули, которые работают только в одном типе интерфейса. Для того чтобы они не появлялись в меню того центра управления, где они не работают, существует параметр X-Alterator-UI, позволяющий ограничить доступные интерфейсы. Допустимые значения данного параметра «html» и «qt» . В будущем, при окончательном переходе с устаревшей системы с template-*, данный параметр потеряет смысл, поскольку оценку возможностей модуля можно будет производить автоматически.

Сборка модуля

Для всех модулей alterator, предоставлена стандартная сборочная система в виде стандартного набора правил make. Вот как выглядит типичный makefile для модуля:

NAME=users

all:
install: install-module
include /usr/share/alterator/build/module.mak

Стандартные правила:

  • install-module — установка модуля в систему
  • check-module — создание виртуальной среды и запуск тестов
  • generate-module — автоматическое создание отдельных компонент модуля

Сборочная система модульная и расширяема по следующим направлениям:

Автоматизация работы над модулем

Наиболее часто повторяющиеся действия могут быть оформлены как скрипт и размещены в каталоге /usr/share/alterator/build/generators. После этого скрипт с именем <name> может быть вызван посредством команды:

make generate-<name>

Доступные генераторы:

backend-pl простейший бэкенд на perl
backend-sh простейший бэкенд на shell
desktop-file простейший desktop-файл с описанием модуля alterator
ui-html простейший интерфейс для html
ui-qt простейший интерфейс для qt
module генератор, запускающий несколько генераторов одновременно, список генераторов задаётся в makefile в переменной GENERATE_LIST

Большинство генераторов учитывают значение переменной NAME.

Пример создания простейшего интерфейса qt:

make generate-ui-qt

Пример запуска серии генераторов:

make GENERATE_LIST="ui-qt ui-html" generate-module

Значение по умолчанию переменной GENERATE_LIST — 'desktop-file ui-qt ui-html backend-sh', поэтому:

make generate-module

Создаст стандартный модуль с бэкендом на shell с qt и html интерфейсами.


Вытаскивание строк для формирования словаря переводов

Для разных языков разметки и для разных языков программирования требуется разный способ «вытаскивания» строк для создания шаблона переводов (pot-файл). Если вы написали бэкенд на языке не имеющим официальной поддержки в alterator, то можете оформить алгоритм вытаскивания переводов в виде скрипта и разместить в каталоге /usr/share/alterator/build/xgettext. Скрипт будет автоматически выполнен при выполнении команды make update-po

Поддерживаемые форматы:

desktop desktop-файлы с описанием модуля и directory-файлы с описанием групп модулей
html файлы с описанием html интерфейса модуля
perl бэкенды на perl
shell бэкенды на shell
scm нативные бэкенды и файлы с описанием графического интерфейса модуля

Генерация словарей

При установке модуля автоматически генерируются словари в формате mo-файлов, а также добавляются переводы в desktop-файлы и directory-файлы. Если вам требуется что-то ещё — оформляйте как скрипт и размещайте в каталоге /usr/share/alterator/build/msgfmt