perlnewmod

СОДЕРЖАНИЕ

• ИМЯ
• ОПИСАНИЕ
  • Предупреждение
  • Что следует сделать модулем?
  • Пошаговая инструкция: Подготовка
  • Пошаговая инструкция: Создание модуля
  • Пошаговая инструкция: Распространение модуля
• АВТОР
• СМОТРИТЕ ТАКЖЕ

ИМЯ

perlnewmod - подготовка нового модуля для распространения

ОПИСАНИЕ

В данном документе приведены рекомендации по написанию модулей Perl, их подготовке к распространению и публикации на CPAN.

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

Основной способ сделать это — создание Perl-модулей. Если вы не знаете, что это такое, остальная часть документа будет для вас бесполезна. Вы также пропустите много полезного кода; ознакомьтесь с perlmod, perlmodlib и perlmodinstall перед возвращением сюда.

Если вы столкнулись с задачей, для которой нет доступного модуля, и вам пришлось написать код самостоятельно, рассмотрите возможность создания модуля и загрузки его на CPAN для пользы других.

Также ознакомьтесь с perlmodstyle для лучших практик создания модуля.

Предупреждение

Здесь мы будем в основном рассматривать модули только на Perl, а не XS-модули. XS-модули служат совершенно другой цели, и вам следует учитывать другие моменты перед их распространением — популярность библиотеки, которую вы используете, переносимость на другие операционные системы и так далее. Однако рекомендации по подготовке Perl-части модуля и его упаковке и распространению применимы как к XS-модулям, так и к модулям на чистом Perl.

Что следует сделать модулем?

Вы должны создать модуль для любого кода, который, по вашему мнению, может быть полезен другим. Всё, что может заполнить пробел в общей библиотеке и которое другой программист сможет напрямую использовать в своей программе, подходит для модуля. Любая часть вашего кода, которую можно выделить, извлечь и подключить к другому коду, является подходящим кандидатом.

Давайте рассмотрим пример. Предположим, вы считываете данные из локального формата в массив хэшей Perl, преобразуете его в дерево, обходите дерево и направляете каждый узел на сервер Acme Transmogrifier.

У многих есть Acme Transmogrifier, и вам пришлось написать код для протокола с нуля — вы практически наверняка захотите сделать это модулем. Уровень абстракции зависит от вас: вы можете создать модули уровня протокола, аналогичные Net::SMTP, которые затем взаимодействуют с модулями более высокого уровня, аналогичными Mail::Send. Выбор за вами, но вам нужно создать модуль для этого серверного протокола.

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

Надеюсь, теперь у вас есть несколько идей о том, что следует модулизировать. Давайте посмотрим, как это делается.

Пошаговая инструкция: Подготовка

Перед началом работы нам нужно выполнить несколько предварительных действий.

Обзор

Изучите несколько модулей, чтобы понять, как они написаны. Я бы посоветовал начать с Text::Tabs, так как он находится в стандартной библиотеке и довольно прост, а затем перейти к чему-то более сложному, например, File::Copy. Для объектно-ориентированного кода WWW::Mechanize или Email::* модули предоставляют хорошие примеры.

Это должно дать вам общее представление о структуре и написании модулей.

Проверка на новизну

На CPAN много модулей, и легко пропустить похожий на тот, который вы планируете создать. Тщательно изучите http://metacpan.org и убедитесь, что вы не изобретаете велосипед!

Обсуждение потребности

Вам может понравиться ваш модуль. Вы можете полагать, что он необходим всем. Но на самом деле, может не быть реальной потребности. Если вы сомневаетесь в востребованности вашего модуля, обратитесь в список рассылки module-authors@perl.org (отправьте письмо на module-authors-subscribe@perl.org для подписки; подробнее см. https://lists.perl.org/list/module-authors.html и архив).

Выбор имени

Модули Perl на CPAN имеют иерархию имён, с которой вы должны соответствовать. См. perlmodlib для получения более подробной информации о работе этой системы, а также просмотрите CPAN и список модулей, чтобы понять правила. Как минимум, помните: имена модулей должны быть с заглавными буквами (This::Thing), соответствовать категории и кратко описывать их назначение.

Ещё раз проверьте

Пока вы этим занимаетесь, убедитесь, что вы не пропустили похожий модуль.

После того, как вы определились с именем и уверены, что ваш модуль нужен и не существует, можно приступать к программированию.

Пошаговая инструкция: Создание модуля

Начните с module-starter или h2xs

Утилита module-starter распространяется как часть пакета CPAN Module::Starter. Она создаёт каталог с заготовками всех необходимых файлов для нового модуля в соответствии с последними "лучшими практиками" разработки модулей и вызывается из командной строки следующим образом:

module-starter --module=Foo::Bar \
   --author="Your Name" --email=yourname@cpan.org

Если вы не хотите устанавливать пакет Module::Starter с CPAN, h2xs — более старая утилита, изначально предназначенная для разработки XS-модулей, которая поставляется вместе с дистрибутивом Perl.

Типичное вызов h2xs для чисто Perl-модуля:

h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar 

Вариант -A опускает код Autoloader, -X опускает XS-элементы, --skip-exporter опускает код Exporter, --use-new-tests настраивает современную среду тестирования, а -n указывает имя модуля.

Используйте strict и warnings

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

Используйте Carp

Модуль Carp позволяет отображать сообщения об ошибках с точки зрения вызывающей функции; это даёт вам возможность указать на проблему у вызывающей стороны, а не вашего модуля. Например, если вы напишете:

warn "No hostname given";

пользователь увидит что-то вроде этого:

No hostname given at
/usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123.

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

No hostname given at bad_code, line 10.

Вы делаете это, используя Carp и заменяя ваши warn на carp. Если вам нужно die, используйте croak вместо этого. Однако оставьте warn и die для ваших проверок — там действительно виноват ваш модуль.

Используйте Exporter — разумно!

Exporter предоставляет стандартный способ экспорта символов и подпрограмм из вашего модуля в пространство имён вызывающей функции. Например, use Net::Acme qw(&frob) импортирует подпрограмму frob.

Переменная пакета @EXPORT определит, какие символы будут экспортированы, когда вызывающая сторона просто называет use Net::Acme — вам почти никогда не нужно добавлять туда что-либо. @EXPORT_OK, с другой стороны, определяет, какие символы вы хотите экспортировать. Если вы хотите экспортировать множество символов, воспользуйтесь %EXPORT_TAGS и определите стандартный набор экспорта — см. Exporter для получения дополнительной информации.

Используйте простую документацию

Работа не окончена, пока не завершена документация, и вам нужно будет потратить время на документирование вашего модуля. module-starter или h2xs предоставят заготовку для заполнения; если вы не уверены в формате, ознакомьтесь с perlpod для введения. Предоставьте хорошее описание того, как ваш модуль используется в коде, описание и затем примечания о синтаксисе и функциональности отдельных подпрограмм или методов. Используйте Perl-комментарии для примечаний разработчика и POD для примечаний конечного пользователя.

Напишите тесты

Рекомендуется создавать тесты для вашего модуля, чтобы убедиться, что он работает как задумывалось на различных платформах, которые поддерживает Perl; если вы загружаете модуль на CPAN, множество тестеров построят ваш модуль и отправят вам результаты тестов. Опять же, module-starter и h2xs предоставляют фреймворк для тестирования, который вы можете расширить — вы должны сделать больше, чем просто проверить, что ваш модуль компилируется. Test::Simple и Test::More — хорошее место для начала написания набора тестов.

Напишите файл README

Если вы загружаете на CPAN, автоматизированные программы извлекут файл README и поместят его в ваш каталог CPAN. Он также появится в основных каталогах по модулю и по категории, если вы разместите его в списке модулей. Хорошо будет указать, что именно делает модуль.

Напишите файл Changes

Добавьте все видимые пользователю изменения с момента последнего выпуска в файл Changes.

Пошаговая инструкция: Распространение вашего модуля

Получение идентификатора пользователя CPAN

Каждый разработчик, публикующий модули на CPAN, нуждается в идентификаторе CPAN. Посетите http://pause.perl.org/, выберите "Request PAUSE Account" и дождитесь одобрения вашей заявки администраторами PAUSE.

perl Makefile.PL; make test; make distcheck; make dist

Ещё раз, module-starter или h2xs выполнили всю работу за вас. Они производят стандартный Makefile.PL , который вы видите при загрузке и установке модулей, и это создаёт Makefile с dist целевым объектом.

После того, как вы убедитесь, что ваш модуль прошёл собственные тесты (всегда хорошая практика), вы можете make distcheck , чтобы убедиться, что всё в порядке, а затем make dist, и Makefile, надеюсь, создаст для вас хороший архив вашего модуля, готовый к загрузке.

Загрузка архива

В электронном письме, которое вы получили при получении идентификатора CPAN, будет указано, как войти в PAUSE (Perl Authors Upload SErver). Оттуда вы сможете загрузить свой модуль на CPAN.

В качестве альтернативы вы можете использовать скрипт cpan-upload, входящий в дистрибутив CPAN::Uploader на CPAN.

Исправление ошибок!

Когда у вас появятся пользователи, они начнут отправлять вам сообщения об ошибках. В лучшем случае, они даже пришлют исправления. Добро пожаловать в мир поддержки программного проекта...

АВТОР

Simon Cozens, simon@cpan.org

Обновлено Kirrily "Skud" Robert, skud@cpan.org

См. также

perlmod, perlmodlib, perlmodinstall, h2xs, strict, Carp, Exporter, perlpod, Test::Simple, Test::More ExtUtils::MakeMaker, Module::Build, Module::Starter http://www.cpan.org/, учебник Кena Уильямса по созданию собственного модуля на http://mathforum.org/~ken/perl_modules.html