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

Материал из ALT Linux Wiki
 
(не показано 12 промежуточных версий 3 участников)
Строка 1: Строка 1:
[[Category:Sisyphus]]
<onlyinclude>
{{MovedFromFreesourceInfo|AltLinux/Sisyphus/Alterator/module/setup}}
 
=== Структура модуля ===
=== Структура модуля ===


Строка 8: Строка 6:


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


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


Файлы описания интерфейсов раскладываются следующим образом:  
Файлы описания интерфейсов раскладываются следующим образом:
* 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'''
Строка 30: Строка 24:
==== Регистрация в центре управления ====
==== Регистрация в центре управления ====


Центр управления - это прежде всего способ объединить разрозненные модули alterator.  
Центр управления — это прежде всего способ объединить разрозненные модули alterator.
Каждый модуль содержит некоторое описание, на основании которого вычисляется его имя и местоположение внутри
Каждый модуль содержит некоторое описание, на основании которого вычисляется его имя и местоположение внутри
двухуровневого меню. Это описание имеет традиционный формат desktop-файла и располагается в каталоге '''applications'''.
двухуровневого меню. Это описание имеет традиционный формат desktop-файла и располагается в каталоге '''applications'''.
Строка 38: Строка 32:


В файле описания группы модулей используются следующие параметры:
В файле описания группы модулей используются следующие параметры:
* '''Name''' - имя группы. Также возможна запись локализованных имён в параметрах Name[locale], где locale - имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8.
* '''Name''' — имя группы. Также возможна запись локализованных имён в параметрах Name[locale], где locale — имя локали (например ru). Для локализованных имён должна использоваться кодировка UTF-8.
* '''Icon''' - картинка для группы, пока не используется
* '''Icon''' — картинка для группы, пока не используется
* '''Type''' - всегда равно directory
* '''Type''' — всегда равно directory
* '''X-Alterator-Category''' - имя категории, которую представляет данная группа.
* '''X-Alterator-Category''' — имя категории, которую представляет данная группа.
* '''X-Alterator-Weight''' - вес группы. В меню группы сортируются согласно их весу.
* '''X-Alterator-Weight''' — вес группы. В меню группы сортируются согласно их весу.
   
   
Пример описания группы:
Пример описания группы:
<pre>[Desktop Entry]
<source lang="ini">[Desktop Entry]
Type=Directory
Type=Directory
Name=Statistics
Name=Statistics
Строка 51: Строка 45:
Icon=system
Icon=system
X-Alterator-Category=X-Alterator-Statistics
X-Alterator-Category=X-Alterator-Statistics
X-Alterator-Weight=15</pre>
X-Alterator-Weight=15</source>


===== Описание модуля =====
===== Описание модуля =====


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


<pre>[Desktop Entry]
<source lang="ini">[Desktop Entry]
Type=Application
Type=Application
Categories=X-Alterator-System
Categories=X-Alterator-System
Строка 77: Строка 71:
X-Alterator-URI=/control
X-Alterator-URI=/control
X-Alterator-Weight=10
X-Alterator-Weight=10
X-Alterator-Help=control</pre>
X-Alterator-Help=control</source>


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


==== Сборка модуля ====
==== Сборка модуля ====
Для всех модулей alterator, предоставлена стандартная сборочная система в виде стандартного набора правил make.  
Для всех модулей alterator, предоставлена стандартная сборочная система в виде стандартного набора правил make.
Вот как выглядит типичный makefile для модуля:
Вот как выглядит типичный makefile для модуля:
<pre>
<pre>
Строка 92: Строка 87:
include /usr/share/alterator/build/module.mak
include /usr/share/alterator/build/module.mak
</pre>
</pre>
'''Стандартные правила''':
* install-module — установка модуля в систему
* check-module — создание виртуальной среды и запуск тестов
* generate-module — автоматическое создание отдельных компонент модуля


Сборочная система модульная и расширяема по следующим направлениям:
Сборочная система модульная и расширяема по следующим направлениям:
<br/>'''автоматизация работы над модулем'''
 
<br/>Наиболее часто повторяющиеся действия могут быть оформлены как скрипт и размещены в каталоге ''/usr/share/alterator/build/generators''. После этого скрипт с именем &lt;name&gt; может быть вызван посредством команды: <pre>make generate-<name></pre>
'''Автоматизация работы над модулем'''
Наиболее часто повторяющиеся действия могут быть оформлены как скрипт и размещены в каталоге ''/usr/share/alterator/build/generators''. После этого скрипт с именем <name> может быть вызван посредством команды: <pre>make generate-<name></pre>


Доступные генераторы:
Доступные генераторы:
{| border="1" cellspacing="0"
{| class="standard"
!backend-pl
!align="left"|backend-pl
|простейший бакенд на perl
|простейший бэкенд на perl
|-
|-
!backend-sh
!align="left"|backend-sh
|простейший бакенд на shell
|простейший бэкенд на shell
|-
|-
!desktop-file
!align="left"|desktop-file
|простейший desktop-файл с описанием модуля alterator
|простейший desktop-файл с описанием модуля alterator
|-
|-
!ui-html
!align="left"|ui-html
|простейший интерфейс для html
|-
!align="left"|ui-qt
|простейший интерфейс для qt
|простейший интерфейс для qt
|-
|-
!ui-qt
!align="left"|module
|простейший интерфейс для html
|-
!|module
|генератор, запускающий несколько генераторов одновременно, список генераторов задаётся в makefile в переменной GENERATE_LIST
|генератор, запускающий несколько генераторов одновременно, список генераторов задаётся в makefile в переменной GENERATE_LIST
|-
|}
|}
Большинство генераторов учитывают значение переменной NAME.


Пример создания простейшего интерфейса qt:
Пример создания простейшего интерфейса qt:
Строка 128: Строка 129:
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>
make generate-module
</pre>
Создаст стандартный модуль с бэкендом на shell с qt и html интерфейсами.


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


Поддерживаемые форматы:
Поддерживаемые форматы:
{| border="1" cellspacing="0"
{| class="standard"
!desktop
!align="left"|desktop
|desktop-файлы с описанием модуля и directory-файлы с описанием групп модулей
|desktop-файлы с описанием модуля и directory-файлы с описанием групп модулей
|-
|-
!html
!align="left"|html
|файлы с описанием html интерфейса модуля
|файлы с описанием html интерфейса модуля
|-
|-
!perl
!align="left"|perl
|бакенды на perl
|бэкенды на perl
|-
|-
!shell
!align="left"|shell
|бакенды на shell
|бэкенды на shell
|-
!scm
|нативные бакенды и файлы с описанием графического интерфейса модуля
|-
|-
!align="left"|scm
|нативные бэкенды и файлы с описанием графического интерфейса модуля
|}
|}


'''генерация словарей'''
'''Генерация словарей'''
<br/>При установке модуля автоматически генерируются словари в формате mo-файлов, а также добавляются переводы в desktop-файлы и directory-файлы. Если вам требуется что-то ещё - оформляйте как скрипт и размещайте в каталоге ''/usr/share/alterator/build/msgfmt''
 
При установке модуля автоматически генерируются словари в формате mo-файлов, а также добавляются переводы в desktop-файлы и directory-файлы. Если вам требуется что-то ещё — оформляйте как скрипт и размещайте в каталоге <tt>/usr/share/alterator/build/msgfmt</tt>
</onlyinclude>
 
 
{{Alterator modules-nav}}

Текущая версия от 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