Выпуск 14. Апрель 2014

← Атрибуты в Perl | Содержание | Обзор CPAN за март 2014 г. →

Minilla — система подготовки дистрибутивов для CPAN

На сегодняшний день существует множество различных утилит для создания дистрибутивов и публикации их на CPAN. Minilla выделяется в их числе своей простотой и удобством, не превращая простой и рутинный процесс подготовки сборки в карго-культ из нагромождения плагинов и сложных конфигураций.

Введение

Minilla была разработана небезызвестным японским программистом Tokuhiro Matsuno. Названа она была по имени одного из японских монстров (кайдзю) из серии фильмов о Годзилле. Судя по описанию в википедии — это маленькое и дружелюбное к людям создание, что, вероятно, и отражает характеристики данной утилиты. Любопытно, что первоначально проект был назван Minya (одно из прозвищ Minilla), но заметили, что набирать название команды minya на QWERTY-клавиатуре не очень-то удобно (особенно сочетание ny), в итоге пришли к команде minil и имени Minilla.

Основной девиз системы — соглашение вместо конфигурации. Minilla предлагает простой свод правил, с которыми вы можете или согласиться, или найти себе другую систему подготовки дистрибутива:

Проект ведётся в системе контроля версий Git.
Список файлов, попадающих в релиз, совпадает с выводом команды git ls-files.
Файлы модуля, написанные на Perl, помещаются в каталог lib.
Исполняемые файлы (скрипты) помещаются в каталог script.
Модуль имеет статический список зависимостей, которые описываются в cpanfile.
Модуль имеет файл Changes, описывающий изменения.

Если правила приемлемы, то можно продолжать.

В разработке любого CPAN-дистрибутива можно выделить четыре основных этапа:

Создание скелета дистрибутива
Разработка
Тестирование
Релиз дистрибутива на CPAN

Все этапы, кроме разработки, хорошо поддаются автоматизации, поэтому Minilla покрывает их достаточно полно.

Создание нового дистрибутива

Minilla содержит утилиту командной строки minil, с помощью которой осуществляются все операции с дистрибутивом. Для создания нового дистрибутива используется команда:

$ minil new Dist-Name

где Dist-Name — это название создаваемого дистрибутива модуля.

В текущей директории создаётся каталог Dist-Name, в котором образуется следующая структура каталогов и файлов:

$ git ls-files

.gitignore
.travis.yml
Build.PL
Changes
LICENSE
META.json
README.md
cpanfile
lib/Dist/Name.pm
minil.toml
t/00_compile.t

При создании файлов Minilla использует информацию из ~/.gitconfig, в частности, ваше имя и email-адрес для формирования информации об авторе.

Файлы Build.PL и META.json генерируются автоматически и не подразумевают ручной правки, но они всё равно добавляются в индекс вашего проекта для того, чтобы всегда иметь возможность провести сборку и установку модуля непосредственно из git (например, с помощью cpanm). Возможность установки из git — это одно из ключевых декларируемых достоинств Minilla.

Далее необходимо сделать первый коммит (все файлы уже добавлены в индекс):

$ git commit -m "initial commit"

Подготовка релиза

После написания модуля и тестов подходит момент, когда необходимо сделать релиз. Minilla предполагает, что у вас настроен внешний репозиторий, в который отправляются все изменения. Это может быть github или какой-либо частный git-репозиторий:

# Добавляем внешний репозиторий origin, в который будут отправляться релизы
$ git remote add origin https://github.com/user/Dist-Name.git

После чего можно перейти к созданию релиза. Редактируется запись в файле Changes, в которой описываются сделанные в релизе изменения, под меткой {{$NEXT}} (если вы забудете это сделать, то при релизе minil вежливо попросит вас об этом и откроет ваш любимый $EDITOR):

{{$NEXT}}

    - my new awesome module

Выполняется команда:

 $ minil release

После чего происходит сборка дистрибутива и запрашивается версия нового релиза. Номер версии и текущее время релиза автоматически добавляются в файл Changes под меткой. Обновляется значение переменной $VERSION в главном модуле и в файле META.json. Создаётся новый коммит, который помечается неаннотированным тегом с номером очередной версии релиза в git. Происходит запуск релизных тестов, и, в случае успеха, формируется архив дистрибутива, а текущая ветка master отправляется во внешний репозиторий origin.

В конце процедуры свежий дистрибутив отправляется на CPAN. Для отправки используется модуль CPAN::Uploader, который ожидает обнаружить данные для аутентификации на PAUSE в файле ~/.pause:

user EXAMPLE
password your-secret-password

Чтобы не отправлять дистрибутив на CPAN, можно установить переменную окружения FAKE_RELEASE=1:

$ FAKE_RELEASE=1 minil release

Конфигурация

Несмотря на жёсткие правила игры, Minilla всё же допускает возможность конфигурации некоторых аспектов дистрибутива. Для этих целей служит файл minil.toml в корне проекта. Файл имеет формат TOML (гибрид INI и JSON). По названиям опций можно заметить влияние Module::Install, например:

readme_from = "lib/My/Foo.pod"

readme_from позволяет задать файл, из которого будет генерироваться README.md (по умолчанию, это главный модуль).

Следующий пример конфигурации позволяет не загружать дистрибутивы на CPAN при создании релиза:

[release]
do_not_upload_to_cpan=true

Полный список опций конфигурации доступен в документации Minilla. Но подразумевается, что необходимость конфигурации — это редкое исключение из правил.

Миграция

Minilla содержит базовую поддержку миграции существующего проекта, для чего необходимо выполнить команду в корне этого проекта:

$ minil migrate

Minilla сделает простой анализ и инициирует git-репозиторий (если до этого не использовался git), попытается сформировать файл META.json для того, чтобы сгенерировать из него корректный cpanfile. Создаст файлы Changes и LICENSE (если их не было), адаптирует Changes в формат, принятый в Minilla. Будут удалены некоторые уже бесполезные файлы, такие как MANIFEST*, Makefile.PL, README, dist.ini и некоторые другие. В случае наличия dist.ini попытается выполнить миграцию конфигурации в файл minil.toml.

Заключение

Minilla показывает нам подход, в котором процедура релиза — это быстрый и несложный процесс, который не должен быть отягощён часами подготовки всех служебных файлов, обновления списков файлов и версий — одна команда, и готово, без лишних телодвижений и ничего не пропущено. Формат репозитория удобен для совместной работы, поскольку правила просты и жёстко зафиксированы, не требуется время для изучения особенностей сборки. Модуль готов к установке прямо из git, что также удобно как для совместной разработки, так и для быстрого тестирования новых версий.

Кстати, пользователи Dist::Zilla, которым понравились идеи Minilla, но которые не хотят пока отказываться от привычного инструмента, могут установить родственную систему Milla, которая следует всем правилам Minilla, но работает поверх dzil.

■ Владимир Леттиев