Alterator/module/structure
Материал из ALT Linux Wiki
Ilis (обсуждение | вклад) (→Расположение файлов и каталогов) |
Ilis (обсуждение | вклад) |
||
Строка 1: | Строка 1: | ||
- | [[ | + | [[Категория:Sisyphus]] |
=== Структура модуля === | === Структура модуля === | ||
Строка 29: | Строка 29: | ||
==== Регистрация в центре управления ==== | ==== Регистрация в центре управления ==== | ||
- | Центр | + | Центр управления — это прежде всего способ объединить разрозненные модули alterator. |
Каждый модуль содержит некоторое описание, на основании которого вычисляется его имя и местоположение внутри | Каждый модуль содержит некоторое описание, на основании которого вычисляется его имя и местоположение внутри | ||
двухуровневого меню. Это описание имеет традиционный формат desktop-файла и располагается в каталоге '''applications'''. | двухуровневого меню. Это описание имеет традиционный формат desktop-файла и располагается в каталоге '''applications'''. | ||
Строка 37: | Строка 37: | ||
В файле описания группы модулей используются следующие параметры: | В файле описания группы модулей используются следующие параметры: | ||
- | * '''Name''' | + | * '''Name''' — имя группы. Также возможна запись локализованных имён в параметрах Name[locale], где locale — имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8. |
- | * '''Icon''' | + | * '''Icon''' — картинка для группы, пока не используется |
- | * '''Type''' | + | * '''Type''' — всегда равно directory |
- | * '''X-Alterator-Category''' | + | * '''X-Alterator-Category''' — имя категории, которую представляет данная группа. |
- | * '''X-Alterator-Weight''' | + | * '''X-Alterator-Weight''' — вес группы. В меню группы сортируются согласно их весу. |
Пример описания группы: | Пример описания группы: | ||
Строка 55: | Строка 55: | ||
В файле описания модуля используются следующие параметры: | В файле описания модуля используются следующие параметры: | ||
- | * '''Name''' | + | * '''Name''' — имя модуля. Также возможна запись локализованных имён в параметрах Name[locale], где locale — имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8. |
- | * '''Icon''' | + | * '''Icon''' — картинка для модуля, пока не используется |
- | * '''Categories''' | + | * '''Categories''' — категории, с которыми связан данный модуль (пока допустимо перечислять только одну категорию) |
- | * '''Type''' | + | * '''Type''' — всегда равно application |
- | * '''Terminal''' | + | * '''Terminal''' — всегда равно false. |
- | * '''X-Alterator-URI''' | + | * '''X-Alterator-URI''' — местоположение модуля (трактовка несколько отличается в acc и в fbi) |
- | * '''X-Alterator-Help''' | + | * '''X-Alterator-Help''' — название темы справки. Справка пишется в формате html и размещается по адресу ''/usr/share/alterator/help/locale/name.html'', где locale — '''полное''' имя локали, а name — имя, указанное в данном параметре. |
- | * '''X-Alterator-Weight''' | + | * '''X-Alterator-Weight''' — вес модуля. Внутри группы, элементы сортируются согласно их весу. |
Пример описания модуля: | Пример описания модуля: | ||
Строка 78: | Строка 78: | ||
X-Alterator-Help=control</source> | X-Alterator-Help=control</source> | ||
- | '''Замечание про разные интерфейсы''' | + | '''Замечание про разные интерфейсы''' |
- | Система меню и справки едина и для GUI и HTML интерфейса, однако до сих пор ещё встречаются модули, которые работают только в одном типе интерфейса. Для того чтобы они не появлялись в меню того центра управления, где они не работают, существует параметр '''X-Alterator-UI''', позволяющий ограничить доступные интерфейсы. Допустимые значения данного параметра | + | |
+ | Система меню и справки едина и для GUI и HTML интерфейса, однако до сих пор ещё встречаются модули, которые работают только в одном типе интерфейса. Для того чтобы они не появлялись в меню того центра управления, где они не работают, существует параметр '''X-Alterator-UI''', позволяющий ограничить доступные интерфейсы. Допустимые значения данного параметра «html» и «qt» . В будущем, при окончательном переходе с устаревшей системы с template-*, данный параметр потеряет смысл, поскольку оценку возможностей модуля можно будет производить автоматически. | ||
==== Сборка модуля ==== | ==== Сборка модуля ==== | ||
- | Для всех модулей alterator, предоставлена стандартная сборочная система в виде стандартного набора правил make. | + | Для всех модулей alterator, предоставлена стандартная сборочная система в виде стандартного набора правил make. |
Вот как выглядит типичный makefile для модуля: | Вот как выглядит типичный makefile для модуля: | ||
<pre> | <pre> | ||
Строка 93: | Строка 94: | ||
'''Стандартные правила''': | '''Стандартные правила''': | ||
- | * install- | + | * install-module — установка модуля в систему |
- | * check- | + | * check-module — создание виртуальной среды и запуск тестов |
- | * generate- | + | * generate-module — автоматическое создание отдельных компонент модуля |
Сборочная система модульная и расширяема по следующим направлениям: | Сборочная система модульная и расширяема по следующим направлениям: | ||
'''Автоматизация работы над модулем''' | '''Автоматизация работы над модулем''' | ||
- | Наиболее часто повторяющиеся действия могут быть оформлены как скрипт и размещены в каталоге ''/usr/share/alterator/build/generators''. После этого скрипт с именем | + | Наиболее часто повторяющиеся действия могут быть оформлены как скрипт и размещены в каталоге ''/usr/share/alterator/build/generators''. После этого скрипт с именем <name> может быть вызван посредством команды: <pre>make generate-<name></pre> |
Доступные генераторы: | Доступные генераторы: | ||
{| class="standard" | {| class="standard" | ||
- | !backend-pl | + | !align="left"|backend-pl |
- | |простейший | + | |простейший бэкенд на perl |
|- | |- | ||
- | !backend-sh | + | !align="left"|backend-sh |
- | |простейший | + | |простейший бэкенд на shell |
|- | |- | ||
- | !desktop-file | + | !align="left"|desktop-file |
|простейший desktop-файл с описанием модуля alterator | |простейший desktop-файл с описанием модуля alterator | ||
|- | |- | ||
- | !ui-html | + | !align="left"|ui-html |
|простейший интерфейс для html | |простейший интерфейс для html | ||
|- | |- | ||
- | !ui-qt | + | !align="left"|ui-qt |
|простейший интерфейс для qt | |простейший интерфейс для qt | ||
|- | |- | ||
- | !|module | + | !align="left"|module |
|генератор, запускающий несколько генераторов одновременно, список генераторов задаётся в makefile в переменной GENERATE_LIST | |генератор, запускающий несколько генераторов одновременно, список генераторов задаётся в makefile в переменной GENERATE_LIST | ||
- | |||
|} | |} | ||
Большинство генераторов учитывают значение переменной NAME. | Большинство генераторов учитывают значение переменной NAME. | ||
Строка 129: | Строка 129: | ||
make generate-ui-qt | make generate-ui-qt | ||
</pre> | </pre> | ||
- | |||
Пример запуска серии генераторов: | Пример запуска серии генераторов: | ||
Строка 135: | Строка 134: | ||
make GENERATE_LIST="ui-qt ui-html" generate-module | make GENERATE_LIST="ui-qt ui-html" generate-module | ||
</pre> | </pre> | ||
- | Значение по умолчанию переменной | + | Значение по умолчанию переменной GENERATE_LIST — 'desktop-file ui-qt ui-html backend-sh', поэтому: |
<pre> | <pre> | ||
make generate-module | make generate-module | ||
</pre> | </pre> | ||
- | Создаст стандартный модуль с | + | Создаст стандартный модуль с бэкендом на shell с qt и html интерфейсами. |
'''Вытаскивание строк для формирования словаря переводов''' | '''Вытаскивание строк для формирования словаря переводов''' | ||
- | + | ||
+ | Для разных языков разметки и для разных языков программирования требуется разный способ «вытаскивания» строк для создания шаблона переводов (pot-файл). Если вы написали бэкенд на языке не имеющим официальной поддержки в alterator, то можете оформить алгоритм вытаскивания переводов в виде скрипта и разместить в каталоге ''/usr/share/alterator/build/xgettext''. Скрипт будет автоматически выполнен при выполнении команды make update-po | ||
Поддерживаемые форматы: | Поддерживаемые форматы: | ||
{| class="standard" | {| class="standard" | ||
- | !desktop | + | !align="left"|desktop |
|desktop-файлы с описанием модуля и directory-файлы с описанием групп модулей | |desktop-файлы с описанием модуля и directory-файлы с описанием групп модулей | ||
|- | |- | ||
- | !html | + | !align="left"|html |
|файлы с описанием html интерфейса модуля | |файлы с описанием html интерфейса модуля | ||
|- | |- | ||
- | !perl | + | !align="left"|perl |
- | | | + | |бэкенды на perl |
|- | |- | ||
- | !shell | + | !align="left"|shell |
- | | | + | |бэкенды на shell |
- | + | ||
- | + | ||
- | + | ||
|- | |- | ||
+ | !align="left"|scm | ||
+ | |нативные бэкенды и файлы с описанием графического интерфейса модуля | ||
|} | |} | ||
'''Генерация словарей''' | '''Генерация словарей''' | ||
- | + | ||
+ | При установке модуля автоматически генерируются словари в формате mo-файлов, а также добавляются переводы в desktop-файлы и directory-файлы. Если вам требуется что-то ещё — оформляйте как скрипт и размещайте в каталоге <tt>/usr/share/alterator/build/msgfmt</tt> |
Версия 10:16, 18 ноября 2008
Содержание |
Структура модуля
Название модуля
Все модули называются в стиле alterator-<имя>. Предпочтительно в качестве <имя> использовать название конкретного сервиса, а не решаемую задачу . Например, alterator-postfix лучше чем alterator-mail, потому что может существовать ещё модуль alterator-sendmail.
Расположение файлов и каталогов
Стандартный модуль alterator может содержать следующие каталоги (их может инициализировать скрипт из пакета alterator-sdk):
- help — документация
- backend2 — нативные бэкенды
- backend3 — внешние бэкенды
- ui — описания интерфейсов (qt)
- templates — описания интерфейсов (html)
- applications — desktop-файлы с описанием модуля (для отображения в меню центра управления)
- desktop-directories — directory-файлы с описанием групп модулей (для отображения в меню центра управления)
- design — дополнительные к стандартным файлы с изображениями, стилями, скриптами.
Каталоги с бэкендами не имеют никакой вложенной иерархии: бэкенд, адресуемый как /foo должен находиться в файле backend3/foo, если это внешний бэкенд, и backend2/foo, если это нативный бэкенд.
Файлы описания интерфейсов раскладываются следующим образом:
- html-описание, адресуемое как /foo/bar, должно находиться в файле templates/foo/bar/index.html
- 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
Регистрация в центре управления
Центр управления — это прежде всего способ объединить разрозненные модули 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