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 для подписки; см. http://lists.perl.org/list/module-authors.html для получения дополнительной информации и ссылки на архив).

Выбор имени

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

Проверка ещё раз

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

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

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

Начало с module-starter или h2xs

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

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

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

Использование 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. Он также появится в основных каталогах by-module и by-category, если вы попадете в список модулей. Хорошо добавить сюда подробное описание того, что делает модуль на самом деле.

Написание Changes

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

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

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

Каждый разработчик, публикующий модули на CPAN, нуждается в идентификаторе CPAN. Посетите http://pause.perl.org/, выберите "Запросить учетную запись PAUSE" и дождитесь одобрения вашей заявки администраторами 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