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 много модулей, и легко упустить похожий на тот, который вы планируете внести. Поработайте с https://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 распространяется в составе пакета 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

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

Использовать 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. Перейдите на https://pause.perl.org/, выберите "Request PAUSE Account" и дождитесь одобрения вашей заявки администраторами PAUSE.

Создание tar-архива

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

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

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

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

В письме, которое вы получили при получении вашего идентификатора 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 https://www.cpan.org/