Выпуск 32. Октябрь 2015

← Анонс коллективного блога @backendsecret | Содержание | Развертывание Perl приложений при помощи Docker →

Как стать Perl-автором

Пошаговое руководство по загрузке своего первого модуля на CPAN

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

Захотелось поработать — ляг поспи

Первым пунктом в памятках “при чрезвычайных ситуациях” зачастую можно встретить фразу: “сохраняйте спокойствие!”. Ровно также стоит поступать, когда захотелось написать какой-то модуль.

Для начала определитесь: а что вы хотите от этого получить? Славу, денег, женщин? Поверьте, есть более простые способы. Если же цель — решить какую-то конкретную проблему — вы на правильном пути.

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

С чего начинаются модули

Вы всё ещё это читаете, а значит нужно сделать что-то новое!

Если спросить у программиста: “Что самое сложное в твоей работе?”, можно услышать: “Придумать название переменной” в ответ. Действительно, задача нелёгкая — описать всю глубину происходящего в паре слов. Причём так, чтобы окружающие вас поняли. Так что ${"капец"} и ${"ААААА!!!"} — не подойдут. Что уж и говорить о названии модуля — там-то происходит ещё больше всякого!

Что ж, здесь нам может помочь опыт наших собратьев: посмотрите, как названы модули, которые вы используете. Также посмотрите на то, для чего вы их используете. Если эти две величины не сходятся, то либо модуль назван криво, либо вы его не тем местом применяете…

К примеру, модуль Test::WWW::Selenium имеет довольно говорящее название. А вот имя модуля Mojolicious не наводит на мысль, о чём он.

Думаю, общий принцип именования ясен. Но! Есть же ещё и общепринятые договорённости. К примеру, Test::WWW::Selenium мог быть и WWW::Test::Selenium, и даже Selenium::Test. Почему же он назван так? Вероятно, потому, что есть уже большое количество модулей с именем Test::*, что намекает на принаделжность к инструментам тестирования.

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

Страна должна знать своих героев

Если я не успел у вас отбить желание программировать и публиковать свои творения, вам стоит познакомиться с сервисом PAUSe (The [Perl programming] Authors Upload Server). Тут-то и происходит публикация модулей на CPAN (The Comprehensive Perl Archive Network).

Первым делом надо завести учётку (Request PAUSE account). В принципе, тут всё просто и незатейливо — пока скан паспорта, тьфу-тьфу, не просят. Заранее проверьте, чтобы Desired ID, который вы запрашиваете, ещё не существует. Сделать это просто: http://search.cpan.org/~$desired_id/ не должно быть :)

Раньше на PAUSe был ещё раздел, в котором запрашивались имена модулей (к примеру, очередной принципиально новый веб-фреймворк должен называться нескучно!), но ныне я этого пункта в меню не вижу. Впрочем, и раньше было легко получить желаемое название — достаточно было сформулировать свою идею.

Show me the code

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

.
├── Build.PL
├── CHANGES
├── example
│   └── small.pl
├── lib
│   └── MyModule.pm
├── LICENSE
├── README
└── t
    ├── 00-test_some_aspect.t
    ├── ...
    └── 99-last_test.t

Первый файл — Build.PL — как раз тот, что мы должны написать для сборки. Он нам нагенерит кучу прочих файлов, которые должны быть в пакете. Пример:

#!/usr/bin/env perl
use strict;
use warnings;
use Module::Build;

Module::Build->new(
  module_name         => 'MyModule',
  dist_abstract       => 'Мой модуль для решения проблем. Возможно, и ваших',
  license             => 'perl',
  dist_author         => 'Моё имя <крутой_ник@cpan.org>',
  dist_version_from   => 'lib/MyModule.pm',
  build_requires      => { 'Test::More' => 0, },
  configure_requires  => { 'Module::Build' => '0.40', },
  requires => {
    'perl'                           => 5.008,
    'Ещё::Один::Модуль::Зависимости' => 0,
  },
  meta_merge => {
    resources => {
      repository => 'https://github.com/реп_модуля',
    },
    keywords => [ qw/Ключевые слова а-ля SEO/ ],
  },
  add_to_cleanup     => [],
  create_makefile_pl => 'traditional',
)->create_build_script();

В файле CHANGES можно увидеть что-то подобное:

Revision history for MyModule

0.02  22-10-2015
  - Fix everything

0.01  21-10-2015
  - Add everything

Со стороны может показаться, что это атавизм. Но я с удивлением обнаружил, что его читают. Однажды хотел пропиарить свой модуль Pony::Object — мол вышла новая версия, объекты теперь ещё более объектные. На что услышал, что мол и без вас знаем (собеседник не знал о моей роли в проекте :) ).

Следующая на очереди — папка examples. По-хорошему, этой папки быть не должно. Если у вас понятно написаны доки, а тесты хорошо оформлены, то необходимость в examples отсутствует. Иначе — приводите там скрипты с использованием вашего модуля.

lib — душа и сердце вашего модуля — именно там расположен код, который вы публикуете.

LICENSE — правила использования вашего кода (обычно используется “The Artistic License”).

README — руководство. Предлагаю генерировать (pod2text) из POD-документации вашего модуля.

t — тесты. Вы ведь пишете тесты, правда?

Стоит также упомянуть, что нужно указывать версию модуля в файле, куда указывает dist_version_from файла Build.PL:

our $VERSION = "0.01";

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

Мистер Сулу, установите курс, скорость варп два!

Что же, вот и готов наш модуль. Осталось только выполнить пару команд Build.

perl Build.PL

сгенерирует исполняемый файл Build.

./Build help
покажет доступные команды.

./Build distmeta # чтобы были META файлы как у “пацанов” ./Build disttest # чтобы не облажаться ./Build manifest # генерирует файл MANIFEST со списком файлов дистрибутива ./Build dist
теперь мы имеем файл MyModule-0.01.tar.gz. Его следует загрузить на PAUSe (Upload a file to CPAN).

Совсем скоро ваш модуль появится на CPAN (дайте серверу немного времени, чтобы создать веб-страничку и добавить модуль в индекс), и вы будете просто обязаны рассказать о нём всему миру! Ведь если вы написали модуль, а он не решает проблем человечества, то всё зря…

P.S.

Теперь, когда ваш модуль используют люди по всему миру, вам будут слать pull-реквесты, предлагать фичи. Придётся поддерживать и дорабатывать своё детище. В общем, если всё сделано правильно — работы вам только прибавилось.

Так стоит ли писать и публиковать модули на CPAN? “Если можешь не писать — не пиши”, — как сказал то ли Чехов, то ли Толстой, а иной раз эту цитату приписывают и Хемингуэю. В общем, вы поняли.

■ Георгий Бажуков