=encoding utf8

=head1 НАИМЕНОВАНИЕ

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

=head1 ОПИСАНИЕ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=over 3

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

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

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

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

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

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

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

=item Выберите имя

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

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

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

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

=back

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

=over 3

=item Начните с F<module-starter> или F<h2xs>

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

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

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

Типичный вызов L<h2xs|h2xs> для чисто Перлового модуля Perl будет:

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

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

=item Используйте L<strict|strict> и L<warnings|warnings>

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

=item Используйте L<Carp|Carp>

Модуль L<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.

Вы можете сделать это с помощью L<Carp|Carp>, заменив C<warn> на C<carp>. Если вам нужно C<die> , скажитн C<croak> вместо этого. Однако, имейте C<warn> и C<die> на месте для проверки вменяемости - там, где ошибка получается по вине вашего модуля.

=item Используйте модуль L<Exporter|Exporter> - мудро!

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

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

=item Используйте L<plain old documentation|perlpod>

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

=item Пишите тесты

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

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

Если вы загружаете на CPAN, автоматизированная Гремлины будет извлечь файл README и место, что в вашем каталоге CPAN. Она будет также отображаться в главном F<by-module> и F<by-category> каталоге, если вы сделаете это на список модулей. Это хорошая идея, чтобы положить здесь то, что на самом деле делает модуль в деталях, и видимых пользователю изменений с момента последнего релиза.

=back

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

=over 3

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

Каждый разработчик публикации модулей на CPAN нуждается в CPAN ID.  Посетите C<http://pause.perl.org/> Выберите "Форма запроса на аккаунт PAUSE", и ждать вашего запроса должно быть одобрено PAUSE администраторов.

=item C<perl Makefile.PL; make test; make dist>

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


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

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

=item Загрузить архив (Upload the tarball)

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

=item Объявление о списке модулей

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

=item Объявите в clpa

Если у вас есть горячее желание рассказать миру о вашем освобождении, разместить объявление в умеренных C<comp.lang.perl.announce> новостей.

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

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

=back

=head1 АВТОР

Simon Cozens, C<simon@cpan.org>

Updated by Kirrily "Skud" Robert, C<skud@cpan.org>

=head1 СМОТРИТЕ ТАКЖЕ

L<perlmod>, L<perlmodlib>, L<perlmodinstall>, L<h2xs>, L<strict>,
L<Carp>, L<Exporter>, L<perlpod>, L<Test::Simple>, L<Test::More>
L<ExtUtils::MakeMaker>, L<Module::Build>, L<Module::Starter>
http://www.cpan.org/ , Ken Williams's tutorial on building your own
module at http://mathforum.org/~ken/perl_modules.html


=head1 ПЕРЕВОДЧИКИ

=over

=item * Николай Мишин  C<< <mishin@cpan.org> >>

=back    
