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 распространяется как часть пакета 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

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

Используйте простую документацию

Работа не закончена до тех пор, пока не будет сделана документация, и вам понадобится время для написания документации вашего модуля. module-starter или h2xs предоставят заготовку для заполнения; если вы не уверены в формате, обратитесь к perlpod для знакомства. Предоставьте хорошее описание того, как используется ваш модуль в коде, описание, а затем заметки о синтаксисе и функции отдельных подпрограмм или методов. Используйте Perl-комментарии для заметок для разработчиков и POD для заметок для конечных пользователей.

Напишите тесты

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

Напишите README

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

Напишите Изменения

Добавьте любые видимые пользователю изменения с момента последнего выпуска в ваш файл Изменения.

Пошаговая инструкция: Распространение вашего модуля

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

Каждый разработчик, публикующий модули на CPAN, нуждается в идентификаторе CPAN. Перейдите на http://pause.perl.org/, выберите "Запросить учётную запись PAUSE" и дождитесь одобрения вашего запроса администраторами 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. Оттуда вы сможете загрузить свой модуль на 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/