Некоторые теги используются только внутри блока комментариев, например:
•
:include:
— включить содержимое указанного файла в документацию. При этом будут сформированы подходящие отступы;
•
:titlе:
— задать заголовок документа;
•
:main:
— задать начальную страницу документации.
Дополнительную информацию вы найдете в книге «Programming Ruby» или в любом онлайновом справочном руководстве.
17.2. Установка и подготовка
пакета
У пользователя должно быть ощущение «коробочного продукта». Как пользователи мы готовы подписаться под этим тезисом обеими руками, но как разработчики не любим заниматься вопросами создания пакетов и установки.
К счастью, в Ruby все это не так болезненно, как в некоторых других языках и средах. Вы обязательно должны знать о библиотеке
setup
и системе RubyGems — «родных» для Ruby инструментах создания пакетов и развертывания.
17.2.1. Библиотека setup.rb
Автором библиотеки
setup.rb
является Минеро Аоки (Minero Aoki). Он же разработал библиотеку
install.rb
, которая сейчас используется реже.
Кто-то скажет, что по мере развития системы RubyGems все это становится не актуальным. А кто-то возразит, что у gem-пакетов есть свои проблемы (технические, политические и пр.). А кто-то считает, что «добропорядочный гражданин» должен включать
setup.rb
даже в gem-пакет (упрощая задачу перепакетирования, например для создания Linux-дистрибутива). Решать вам.
Половина дела будет сделана, если вы скопируете все файлы в нужные места. Вы должны организовать свой архив простым и разумным образом (создав каталоги с предопределенными именами).
Предположим, что дистрибутив содержит единственный пакет в архиве (наиболее распространенный случай). Тогда дерево каталогов организуется примерно так (причем файл
setup.rb
помещается на верхний уровень).
top_level/
setup.rb
metaconfig (необязательно)
lib/
ext/
myext/
bin/
data/
conf/
man/
test/
Пустые каталоги можно опускать. Ниже описано назначение каждого каталога:
•
lib
—программы на Ruby;
•
ext
— расширения Ruby (написанные на С);
•
myext
— имя расширения (на том же уровне могут располагаться и другие расширения); в каталоге каждого расширения должен находиться либо файл
extconf.rb
, либо
MANIFEST
;
•
bin
— команды;
•
data
— файлы данных;
•
conf
— конфигурационные файлы;
•
man
— страницы руководства;
•
test
— автономные тесты и другие тестовые программы.
В общем случае эти файлы никак не обрабатываются, а просто копируются в нужное место. Но для специализированной настройки предусмотрены места подключения
к каждому этапу процесса.
Три основных этапа — это
config
,
setup
и
install
, вызываемые пользователем именно в таком порядке (на последнем шаге могут потребоваться полномочия root или, по крайней мере, выполнение
sudo
).
Для подключения к этапу вы просто помещаете в нужный каталог написанную на Ruby программу с известным именем. Например, если необходимо перед обработкой сделать что-то нестандартное с файлом
lib/foobar
, следует создать файл
lib/foobar/pre-setup.rb
и поместить в него произвольный код.
Имя файла формируется следующим образом: префикс
pre
или
post
, дефис, имя задачи. Определены следующие имена задач:
config
,
setup
,
install
,
test
,
clean
и
dist-clean
.
В библиотеке
setup.rb
есть понятия каталога исходных файлов, или исходного каталога (source directory) и каталога объектных файлов, или объектного каталога (object directory). Как правило, вы должны читать из исходного каталога и записывать в текущий каталог.
Существует «API для подключения» (hook API), упрощающий решение ряда задач. Приведем некоторые определенные в нем методы:
•
get_config_key(key)
— принимает в качестве параметра ключ и возвращает ассоциированное с ним значение (например,
get_config('prefix')
возвращает путь, определенный с помощью конфигурационного параметра
– -prefix
);
•
set_config_key(key, val)
— устанавливает значение конфигурационного параметра;
•
config_key(key)
— то же, что
get_config_key
;
•
curr_srcdir
— текущий исходный каталог;
•
curr_objdir
— текущий объектный каталог;
•
srcfiles(rel_path=".")
— список всех файлов в каталоге с путем
rel_path
(относительно текущего исходного каталога).
На верхнем уровне может находиться файл
metaconfig
. Если он есть, то в нем задаются некоторые глобальные конфигурационные параметры. Для этой цели имеется специальный «metaconfig API» — небольшой набор вспомогательных методов, в частности:
•
add_path_config(confname, default, description)
— определяет конфигурационный параметр, являющийся путем; задаются имя и значение по умолчанию. При вызове с флагом --help эта информация печатается;
•
add_bool_config(confname, default, description)
— аналог
add_path_config
, но описывается булевский параметр.
Дополнительную информацию по этим API можно найти в актуальной онлайновой документации.