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/, выберите "Запросить учетную запись 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