НАИМЕНОВАНИЕ

perlnewmod - подготовка нового модуля

ОПИСАНИЕ

Этот документ дает вам несколько советов о том, как писать модули на Perl, подготовить их к раздаче, и сделать доступными на CPAN.

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

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

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

Предостережение

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

Что мне нужно писать в модуле?

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

Рассмотрим пример. Предположим, вы читаете данные из местного формата в хэш хэшей в Perl, который превращается в дерево, обходите это дерево и затем посылаете каждый узел этого дерева через конвейер (pipe) на сервер компании Акме Трансмогрифиер. (Acme Transmogrifier, Acme - выдуманная мультяшная компания, Transmogrifier - преобразователь меча в Diablo 2)

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

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

Шаг-за-шагом: Подготовка почвы

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

Оглянись вокруг

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

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

Проверьте, что они самые свежие

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

Обсудите необходимость

Вы могли бы любить его. Вы можете чувствовать, что все остальные нуждаются в нем. Но на самом деле может и не быть реального спроса на него. Если вы не знаете будет ваш модуль иметь спрос или нет, рассмотреть вопрос о направлении вопроса в группу новостей comp.lang.perl.modules, или в качестве последнего средства, спросите в списке рассылки модулей на modules@perl.org. Помните, что это закрытый список с очень долгим временем отклика - будьте готовы довольно долгое время ответа от них.

Выберите имя

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

Проверьте еще раз

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

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

Шаг-за-шагом: Создание модуля

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

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

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

Код модуля должен сообщать предупреждения warnings и быть в чистом, строгом стиле 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 для более подробной информации.

Используйте plain old documentation

Работа не закончена, пока не закончена документация, вам нужно уделить какое-то время на написание документации для вашего модуля. module-starter или С<h2xs> даст шаблоны для заполнения кодом, если вы не уверены в формате pod посмотрите на perlpod для введения. Напишите хороший пример использования вашего модуля (synopsis) , описание, а затем более подробное описание синтаксиса и функций отдельных подпрограмм или методов. Используйте комментарии Perl для разработчиков и описание в POD для конечных пользователей модуля.

Пишите тесты

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

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

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

Шаг за шагом: Распространение вашей модуля

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

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

perl Makefile.PL; make test; make dist

правда эти команды справедливы для Unix (примечание mishin) для Windows, где Ларри советует Strawberry perl будет работать dmake test; dmake dist, но и dmake dist не выполниться, если предварительно не установить на систему gnu-tar и gnu-zip и добавить путь к ним в переменную PATH

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

Once you've ensured that your module passes its own tests - always a good thing to make sure - you can make dist, and the Makefile will hopefully produce you a nice tarball of your module, ready for upload.

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

Загрузите архив

В емейле, который вы получили с CPAN ID будет рассказано, как войти в систему PAUSE, the Perl Authors Upload SErver. (Авторский Perl Сервер Загрузки). Здесь в меню вы можете загрузить свой модуль на CPAN.

Объявление о новом модуле

После загрузки, он будет лежать незамеченным в вашем авторском каталоге. Если вы хотите, чтобы он был связан с остальной частью CPAN, вы должны будете найти пункт Регистрации Пространства имен "Register Namespace" на сервере PAUSE. После регистрации ваш модуль появится в с списках, отсортированных по-модулям и по категориям на CPAN.

Объявите в clpa

Если у вас есть горячее желание рассказать миру о вашем релизе - разместить объявление в группу новостей comp.lang.perl.announce.

Исправляйте баги!

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

АВТОР

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/ , учебник Кена Вильямса о том, как создать свой собственный модуль на http://mathforum.org/~ken/perl_modules.html, но похоже это дока устарела,т.к сейчас популярна Dist::Zilla и супер модуль от Tatsuhiko Miyagawa Dist::Milla, Minilla

ПЕРЕВОДЧИКИ

• Николай Мишин <mishin@cpan.org>