Внимание! Прочитайте, пожалуйста, текст в правой колонке (внизу).
Внимание! Прочитайте, пожалуйста, текст в правой колонке (внизу). Внимание! Прочитайте, пожалуйста, текст в правой колонке (внизу). Homepage Карта сайта Версия для печати

Джентльменский набор Web-разработчика   Ларри Уолл о Perl6   Наблы Система Orphus
 

37. Публикация модулей на CPAN, или поделитесь кусочком своего мира

[1 января 2004 г.] обсудить статью в форуме

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

Чайник 

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

Что, где, когда

Вначале, как водится, необходимо внимательно прочитать официальную документацию. Необходимая статья называется perlnewmod и доступна, например, по адресу http://perldoc.perl.org/perlnewmod.html. Вкратце приведу рекомендации оттуда, которые, безусловно, не заменят прочтения документации (настоятельно советую потратить на это некоторое время, чтобы потом не попасть впросак).

  • Проверьте, нет ли уже сходного модуля на CPAN. Незачем делать дважды одну работу.
  • Аккуратно выберите имя пакета для модуля. Изучите, какие на CPAN есть пакеты и как они используются. Можно посмотреть, например, вот на такую классификацию.

    Чайник 

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

  • Используйте директивы use strict и ключ -w при разработке модуля. Это позволит упростить отладку и выявить потенциальные ошибки.
  • Не злоупотребляйте количеством экспортируемых функций. Чем меньше модуль экспортирует, тем лучше. Дело в том, что при чрезмерно большом списке экспорта ваш модуль может начать конфликтовать с модулем другого производителя.

Автоматизация процесса

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

  • Дистрибутив должен представлять собой одну директорию, запакованную архиватором tar, а затем — gzip. Я опишу процесс упаковки чуть позже.
  • Имя главной директории для модуля Имя::Модуля должно иметь следующий вид: Имя-Модуля-1.23, где 1.23 — это версия модуля.

    Чайник 

    Иными словами, необходимо взять полное имя пакета модуля, заменить :: на дефисы, добавить в конец номер версии и создать директорию с получившимся именем. Например, модуль CGI::WebOut версии 2.10 располагается в архиве CGI-WebOut-2.10.tar.gz, содержащем единственную директорию CGI-WebOut-2.10.

  • Внутри главной директории должен находиться скрипт Makefile.PL, который управляет созданием Makefile для сборки и установки дистрибутива. Кроме того, там также может находиться README-файл.

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

Чайник 

Далее я буду предполагать, что новый модуль называется Module::Name и имеет версию 1.00.

Создайте где-нибудь директорию, имя которой соответствует описанным выше требованиям: Module-Name-1.00. Затем перейдите в нее и запустите следующую команду:

Листинг 1
h2xs -AX -n Module::Name -v 1.00

Чайник 

Для справки наберите h2xs -h. Излишне напоминать, что данные команды доступны лишь в случае, если у вас установлена полная версия Perl с библиотеками (в Денвере для этого есть специальный пакет расширения).

При этом создастся структура директорий Module/Name/*, а в ней — заглушки для следующих файлов:

  • Changes — файл, в который рекомендуется добавлять сведения об изменениях при переходе к следующей версии модуля.
  • MANIFEST — список файлов в дистрибутиве.
  • README — заглушка для README-файла.
  • Makefile.PL — скрипт для генерации Makefile, в который вам следует вписать собственное имя и координаты.
  • test.pl — тестовый скрипт.
  • Name.pm — файл модуля Module::Name.

В большинстве случаев дополнительная структура каталогов нам не нужна, так что перенесите все файлы прямо в директорию Module-Name-1.00 и удалите ветку Module/Name.

Проверка заглушки дистрибутива

В настоящий момент у вас есть рабочая заглушка для нового дистрибутива. Проверьте, все ли с ней в порядке. Для этого запустите по очереди следующие команды:

Листинг 2
perl Makefile.PL
make
make test
make clean

Чайник 

Напоминаю, что, если Вы работаете в Windows, на машине должна быть установлена Microsoft Visual Studio. Кроме того, следует использовать nmake, а не make. Убедитесь также, чтобы имя текущей директории не содержало пробелов.

Последняя команда выполняет «чистку» дистрибутива, удаляя все служебные файлы, созданные при компиляции.

Создание дистрибутива

Подготовительные операции завершены, и теперь остался самый ответственный момент.

  1. Необходимо вставить код вашего модуля в существующие заглушки.
    • Аккуратно скопируйте код модуля в соответствующую секцию pm-файла внутри дистрибутива.
    • Вернитесь к этапу проверки модуля, описанному в предыдущем разделе.
    • Можете также выполнить команду make install (или nmake install для Windows), чтобы проинсталлировать модуль в свою систему и проверить его «в действии».
  2. Если все идет хорошо, модифицируйте скрипт test.pl, добавив туда другие тесты для своего модуля. Чем больше тестов, тем лучше. Тестирование — важный этап при установке модуля. Если он будет отсутствовать, не все смогут установить ваши библиотеки.
  3. Включите в модуль (файл с расширением pm) документацию в формате POD (plain old documentation — старая-добрая текстовая документация). Данная рекомендация является практически обязательной к выполнению. О POD можно прочитать в статье perlpod: http://www.perldoc.com/perlpod.html. Примерный шаблон POD-документа есть в сгенерированной для модуля заглушке. Если вам его недостаточно, посмотрите, как сделано в других модулях.

    Чайник 

    POD-документ внутри модуля будет показываться на страницах CPAN, как только ваш модуль проиндексируется роботом. Так что, если вы опустите этап его создания, ваш модуль лишится своего описания.

    Проверить, как выглядит HTML-представление POD-документа, можно при помощи утилиты pod2html:

    Листинг 3
    pod2html Name.pm > Name.htm

    После генерации файла Name.htm можно просмотреть его в браузере.
  4. Обязательно модифицируйте файл README и впишите в него возможно более адекватное содержимое. Лучше всего, если оно будет включать простейший пример использования модуля. README-файл будет доступен прямо со страниц CPAN.
  5. Внутри каждого модуля должна определяться переменная $VERSION, содержащая номер версии модуля в строковом представлении. Это — число в формате x.xx, например: 1.01, 1.10, 1.65, 3.04 и т. д. Другой формат версий не допускается. Номер версии задается в единственном месте — в pm-файле, и больше нигде. Удостоверьтесь, что название директории соответствует номеру версии, указанному внутри модуля.

Упаковка дистрибутива

Итак, предположим, что после многочисленных проверок вы получили рабочий дистрибутив модуля, который может быть установлен по make install и работает как в Windows, так и в Unix.

Чайник 

Обязательно проверьте модуль в обеих ОС, прежде чем отправлять его на CPAN!

Вначале удалите все лишние файлы из дистрибутива, запустив make clean. Удалите вручную тот мусор, который не удалился. В результате должны остаться только те файлы, которые перечислены в MANIFEST.

Теперь необходимо запаковать дистрибутив, для чего вам понадобятся утилиты tar и gzip. Если вы работаете в Unix, он там уже есть. В Windows же их по умолчанию нет, так что рекомендую установить пакет UnxUtils: http://unxutils.sourceforge.net и прописать в переменную окружения PATH путь к директории, в которую вы установили утилиты.

Перейдите в директорию, родительскую по отношению к Module-Name-1.00, и выполните там последовательно две команды:

Листинг 4
tar cvf Module-Name-1.00.tar Module-Name-1.00
gzip --best Module-Name-1.00.tar

После этого появится архив Module-Name-1.00.tar.gz, который можно отправлять на CPAN.

Регистрация на CPAN

Наконец-то мы добрались до финального этапа — отправки модуля на CPAN. Первое, что необходимо сделать, — это зарегистрироваться в системе PAUSE (The Perl Authors Upload Server) по адресу http://pause.perl.org, выбрав затем «Request PAUSE account».

Выберите себе запоминающийся логин (в терминологии PAUSE он называется ID), который будет идентифицировать вас как автора модулей. Не забудьте также ввести E-mail.

Через некоторое время (увы, оно может достигать нескольких дней в зависимости от загруженности сервера и модераторов) вам придет письмо с просьбой подтвердить свое желание зарегистрироваться и предложением сменить пароль. Не медлите, сделайте это сразу же по получении.

Как только регистрация будет завершена, вы получите виртуальный ящик ID@cpan.org (где ID — ваш логин), переадресовывающий на введенный ранее E-mail. Рекомендуется в качестве контактного адреса в POD-документации и README-файлах использовать именно этот ящик. Во-первых, так вы можете в будущем легко сменить свой настоящий адрес, не опасаясь, что придется менять все ссылки в модуле. Во-вторых, вы скроете свой настоящий ящик, что усложнит жизнь спамерам. Так что лучше прямо сейчас поправьте все адреса E-mail в своих модулях, а затем заново их перепакуйте.

Вы сможете использовать свой логин и пароль для доступа на страницу сервисов PAUSE (вход возможен по ссылке Login на главной странице PAUSE). Например, зайдите в секцию персональных параметров (Edit account info) и установите желаемые адреса E-mail, с которыми вы будете работать.

Закачка модуля

Оказывается, закачать свой дистрибутив на CPAN проще простого. Для этого войдите под своим логином и паролем и выберите слева ссылку «Upload a file to CPAN». Появится страница с формой закачки. Укажите нужный файл архива и нажмите «Upload this file from my disk». Теперь остается только подождать, пока робот доберется до вашего дистрибутива, проверит его и поместит в ваш домашний каталог на CPAN (обычно этот процесс занимает не более получаса). Например, мой домашний каталог — http://cpan.org/authors/id/K/KO/KOTEROV.

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

Чайник 

Учтите, что нельзя закачивать новые файлы поверх старых, можно только добавлять новые. Это отчасти объясняет стандарт именования дистрибутивных архивов, когда в конец имени добавляется номер версии модуля. Впрочем, вы все же можете удалять файлы, но процесс этот длительный, и может пройти несколько суток, прежде чем файлы исчезнут из домашнего каталога.

Когда файлы появляются в домашней директории, это еще не значит, что они сразу же становятся доступными через поисковую машину http://search.cpan.org. В дело должен вступить второй робот, который тщательно изучит содержимое дистрибутива и обновит свои базы данных. Этот процесс может занять часов 12-15, так что запаситесь терпением.

В итоге все модули, которые вы закачали, должны находиться при помощи запроса на http://search.cpan.org. Попробуйте ввести на этой странице имя своего модуля.

Регистрация модуля в общем списке

На CPAN существует один большой документ, доступный по адресу http://www.cpan.org/modules/00modlist.long.html. Он содержит список модулей Perl, которые пользуются популярностью на CPAN. Если вы хотите включить свой модуль в этот список, вам необходимо выполнить все рекомендации, которые написаны в верхней части документа.

В частности, рекомендуется согласовать с другими авторами CPAN имя вашего модуля, его тип и описание, для чего необходимо послать письмо в свободном формате по адресу modules@perl.org. Общайтесь с другими разработчиками.

Ссылки для самостоятельного изучения

обсудить статью в форуме

 
Рекламный блок
    {{GoogleVertical300: empty}}

На странице:
    37. Публикация модулей на CPAN, или поделитесь кусочком своего мира
Что, где, когда
Автоматизация процесса
Проверка заглушки дистрибутива
Создание дистрибутива
Упаковка дистрибутива
Регистрация на CPAN
Закачка модуля
Регистрация модуля в общем списке
Ссылки для самостоятельного изучения

Важное объявление:
    автор категорически против копирования и распространения в Интернете всех статей «Куроводства» с возрастом, меньшим 6 месяцев. Печальный опыт «расползания» чрезвычайно устаревших ошибочных версий статьи про Apache действительно объясняет такое решение.

Орфография на «Куроводстве»:
    если вы заметили орфографическую, стилистическую или другую ошибку на этой странице, просто выделите ошибку мышью и нажмите Ctrl+Enter. Выделенный текст будет немедленно отослан вебмастеру, а Вы даже ничего и не заметите — настолько быстро все произойдет.

На заметку:
    если вы уже вскипели насчет дизайна этой страницы, то присмотритесь повнимательнее к названию, почитайте FAQ, сходите по лебедевским местам, как это уже предлагалось выше. Можно ли считать пародию плагиатом? Надеюсь, что нет.

Параметры этой страницы
   
GZip

Ссылки от спонсоров
    {{PromotionBlockRight: empty}}


Дмитрий Котеров | 1 января 2004 г. ©1999-2016 | Генеральный спонсор: Хостинг «Джино» | Контакт Вернуться к оглавлению