=encoding utf8

=head1 НАЗВАНИЕ

perlnewmod - подготовка нового модуля для распределения (for distribution)

=head1 ОПИСАНИЕ

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

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

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

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

=head2 Предупреждение

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

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

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

Давайте брать пример. Предположим, вы читаете данные из местного формата в хэш-из-хэшей в Perl, превращаете это в дерево, идете по дереву, а затем выводите (piping) каждый узел(node) на сервер Acme Transmogrifier.

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

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

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

=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> и убедитесь, что вы не тот, изобретать велосипед!

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

Вы можете любить его. Вы можете почувствовать, что все остальное в ней нуждается. Но не может быть фактически любой реальный спрос на его там. Если вы не знаете о вашем спроса модуль будет иметь, рассмотреть вопрос о направлении прощупывать на C<comp.lang.perl.modules> телеконференции, или в крайнем случае, попросите список модулей на C<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> опускает автозагрузку кода,  C<-X> опускает XS элементов, C<--skip-exporter> опускает Экспортер кода,  C<--use-new-tests> устанавливает современную среду тестирования, и C<-n> указывает имя модуля.

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

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

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

Модуль L<Carp|Carp> позволяет представить ваши сообщения об ошибках с точки зрения абонента, это дает вам возможность сигнализировать проблемы с абонентом, а не модуля вашего. Например, если вы говорите, это:

    warn "имя хоста не дано";

пользователь увидит что-то вроде этого:

    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 * Николай Мишин (Tech & Language Lead)

=back    