Записки программиста

Добавлять модули на CPAN оказалось до неприличия просто. В этой заметке вы найдете пошаговую инструкцию, как это делается. Но будьте осторожны! У вас может возникнуть непреодолимое желание штамповать модули один за другим, позабыв о сне, здоровом питании и личной гигиене.

Первое, что вам понадобится, это завести учетную запись на PAUSE. Имя я бы рекомендовал вводить латиницей, поскольку оно будет отображаться на search.cpan.org, не все посетители которого понимают кириллицу. Будьте внимательны при выборе ID — изменить его после регистрации будет нельзя. В качестве причины регистрации достаточно ввести «I would like to upload some perl modules». Ваша учетная запись не будет создана без подтверждения одного из майнтейнеров PAUSE, так что после нажатия кнопки «Request account» придется немного подождать.

После создания учетной записи советую сделать три вещи. Во-первых, настроить пересылку с цпан_айди@cpan.org на ваш настоящий e-mail адрес. Во-вторых, указать ящик на cpan.org в качестве public-ящика. Тем самым вы скроете свой настоящий e-mail от спамеров. Наконец, в-третьих, зайти на Gravatar и поставить в соответствие своему адресу на cpan.org какой-нибудь аватар. Он будет отображаться на cpan.org, metacpan.org и прочих сайтах. Если вы уже зарегистрированы на Gravatar, создавать новую учетную запись не потребуется, ибо под одной учетной записью можно заливать аватары для разных ящиков.

Теперь перейдем к созданию модуля. Заведите где-нибудь (настоятельно рекомендую GitHub) новый репозиторий. Создайте заготовку вашего модуля. Можно сделать это вручную, взяв за основу мой модуль VK::MP3, или воспользоваться утилитой h2xs:

Обратите внимание, что использовать пространство имен первого уровня не принято, если только вы не создали что-то действительно грандиозное.

Правим немного файлы README и Changes. В файл MANIFEST указываем имена всех файлов, которые должны войти в пакет. Очень важен файл Makefile.PL. В нем следует указать название модуля, список его зависимостей, имя автора, лицензию, ссылку на Git-репозиторий и тп. За основу можете взять этот Makefile.PL.

Сам модуль (или модули) должен находится в каталоге ./lib. О том, как пишутся perl-модули, я уже как-то рассказывал. В коде модуля обязательно укажите его версию:

Обратите внимание, что версия задается рациональным числом, а не строкой. Таким образом, версия 0.10 — это то же самое, что версия 0.1, и потому она не может идти после версии 0.9. Если не хотите ощутить попаболь, нумеруйте версии своих модулей, начиная с 0.01 или 0.001, а не с 0.1.

Помимо версии, модуль должен содержать документацию в формате POD. Составление такой документации — дело нехитрое и потребует от вас минимальных знаний английского. См документацию к VK::MP3 и то, как она выглядит на metacpan.

Если вас интересует подробное описание формата POD, наберите в консоли «perldoc perlpod». Для предварительного просмотра документации можно воспользоваться командой:

Или, например:

Также понадобятся тесты. Много тестов. Тесты очень важны, особенно когда вы пишите на скриптовых языках вроде Perl или Python. Если не желаете опозориться на весь белый свет, ничего не заливайте на CPAN, пока как следует не овладеете навыком написания тестов и разработки по TDD. Кстати, умение создавать нормальные интерфейсы также не повредит.

Тесты следует складывать в каталог ./t. Помимо кода, вы также можете покрыть тестами документацию в формате POD. На полном серьезе. Найти ошибки в документации поможет модуль Test::Pod, а проверить степень покрытия кода документацией — Test::Pod::Coverage. После того, как вы отправите модуль на CPAN, тесты будут прогоняться самыми разными версиями Perl и под множеством операционных систем, включая такие экзотические, как Solaris и Microsoft Windows. Чем полнее будут ваши тесты, тем раньше вы сможете обнаружить ошибку, проявляющуюся только в специфическом окружении.

Итак, модуль вроде работает, документация написана, тесты готовы. Можно попробовать залить модуль на CPAN. Устанавливаем утилиту cpan-upload-http:

Еще разок прогоняем все тесты:

Затем пробуем вручную установить модуль:

Если все ОК, говорим:

Вскоре вам должно прийти почтовое уведомление о том, что модуль был успешно загружен. Где-то через пять минут его уже можно будет установить с помощью утилиты cpanm. Минут через двадцать модуль появится на metacpan.org, а примерно через час — на search.cpan.org.

Проверьте, что ваш модуль успешно устанавливается, а документация к нему корректно отображается на cpan.org и metacpan.org (не «пополз» ли текст? отображаются ли в левом столбце лицензия и ссылка на репозиторий?). Если какие-то тесты не проходят, выясните причину и устраните ее. Убедитесь, что модуль можно найти по подходящим ключевым словам. Например, VK::MP3 v0.01 можно было найти по запросу «vk.com mp3», но не «vkontakte mp3», что я исправил в версии 0.02, добавив в POD ключевых слов. При обновлении модуля не забудьте увеличить значение $VERSION, добавить запись в файл Changes, а также прогнать все тесты.

Это все, о чем я хотел рассказать. Комментарии с вопросами и дополнениями приветствуются.

Метки: Perl.