Загрузка...


  • 17.1. Программа RDoc
  • 17.1.1. Простая разметка
  • 17.1.2. Более сложное форматирование
  • 17.2. Установка и подготовка пакета
  • 17.2.1. Библиотека setup.rb
  • 17.2.2. Система RubyGems
  • 17.3. RubyForge и RAA
  • 17.4. Заключение
  • Глава 17. Создание пакетов и распространение программ

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

    (Дэйв Бэрри)

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

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

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

    Один из самых замечательных имеющихся инструментов — программа

    RDoc
    , написанная Дэйвом Томасом. С нее и начнем.

    17.1. Программа RDoc

    RDoc
    — не единственный инструмент документирования для Ruby: его предшественником является программа RDTOOL. Но во многих отношениях
    RDoc
    превосходит своих конкурентов; к тому же он наиболее распространенный, по крайней мере, в США.

    Замечательной особенностью

    RDoc
    является то, что он пытается вывести нечто полезное, даже если в исходном тексте вообще нет комментариев. Для этого он анализирует текст программы и собирает информацию обо всех классах, модулях, константах, методах и т.д.

    Тем самым вы можете получить более или менее полезный HTML-файл из исходного текста, не содержащего никакой внутренней документации. Если раньше не пробовали, попробуйте сейчас.

    Но это еще не все.

    RDoc
    также пытается ассоциировать найденные комментарии с конкретными частями программы. Общее правило таково: блочный комментарий, предшествующий определению (скажем, класса или метода), считается описанием этого определения.

    Если просто вызвать

    RDoc
    для какого-нибудь исходного текста на Ruby, будет создан каталог
    doc
    , в который помещаются все выходные файлы (этот стандартный шаблон уже неплох, но есть и другие). Откройте в браузере файл index.html и изучите его.

    В листинге 17.1 приведен простой (почти ничего не содержащий) исходный файл. Все определенные в нем методы пусты. Но

    RDoc
    даже в таком случае формирует симпатичную страницу документации (рис. 17.1).

    Листинг 17.1. Простой исходный файл

    require ' foo'


    # Внешний класс MyClass.


    class MyClass

     CONST = 237


     # Внутренний класс MyClass::Alpha...


     class Alpha


      # Класс The MyClass::Alpha::Beta...


      class Beta

       # Метод класса Beta mymeth1.

       def mymeth1

       end

      end


      # Метод класса Alpha mymeth2.

      def mymeth2

      end

     end


     # Инициализировать объект.


     def initialize(a,b,c)

     end


     # Создать объект со значениями по умолчанию


     def self.create

     end


     # и метод экземпляра.


     def do_something

     end


    end

    Рис. 17.1. Выходной файл, формируемый программой RDoc по исходному тексту в листинге 17.1

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

    Кроме того, когда программа RDoc распознает URL, она помещает в выходной файл гиперссылку. По умолчанию текст гиперссылки совпадает с самим URL, но это можно изменить. Если перед URL поместить в фигурных скобках какой-нибудь описательный текст, то он и станет содержимым ссылки. Если текст состоит из одного слова, фигурные скобки можно опустить.

    17.1.1. Простая разметка

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

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

    В листинге 17.2 приведено несколько примеров разметки; дополнительную информацию ищите в книге «Programming Ruby» или в документации по

    RDoc
    . На рис. 17.2 показано, во что преобразуется текст в листинге 17.2 (нижний фрейм).

    Листинг 17.2. Пример разметки для RDoc

    # This block comment will be detected and

    # included in the rdoc output.

    #

    =begin rdoc

    So will this one. Note the presence of the "rdoc"

    tag on the begin-line. This is to distinguish the

    block comment as belonging to rdoc as opposed to

    being read by some other tool.

    =end

    =begin rdoc

    Here are some formatting tricks.


    Boldface, italics, and "code" (without spaces):

    This is *bold*, this is _italic_, and this is +code+.


    With spaces:

    This is a bold phrase. Have you read Intruder

    in the Dust? Don't forget to require thread

    at the top.


    = First level heading

    == Second level heading

    === Third level heading


    Here's a horizontal rule:

    ---


    Here's a list:

    - item one

    - item two

    - item three


    =end

    =begin

    This block comment is untagged and will not show up in

    rdoc output. Also, I'm not putting blank lines between

    the comments, as this will terminate the comments until

    some real program source is seen. If this comment had

    been before the previous one, processing would have

    stopped here until program text appeared.

    =end

    Рис. 17.2. Результат работы RDoc для примера из листинга 17.2

    В листинге 17.2 приведено несколько правил разбора документов, принятых в

    RDoc
    . Не все они интуитивно очевидны. Считается, что пустые строки завершают блок комментариев, даже если вслед за пустой строкой сразу идет еще один такой блок.

    Внутри блока комментариев, начинающегося со знака

    #
    , можно отключить копирование текста в выходной файл, вставив строку
    #--
    (а следующая такая строка вновь включает копирование). Ведь не все комментарии должны быть частью пользовательской документации.

    Отметим еще, что если используются маркеры

    =begin
    и
    =end
    , то после
    =begin
    должен находиться тег
    rdoc
    , иначе
    RDoc
    проигнорирует весь блок целиком. Это сделано во избежание конфликтов с более старыми инструментами, в которых такие блоки активно использовались.

    17.1.2. Более сложное форматирование

    RDoc
    позволяет довольно точно управлять тем, какие части исходного текста документируются и как к ним следует относиться. Для этого служат специальные теги в комментариях (модификаторы документации).

    Одним из самых важных является тег

    :nodoc:
    , отключающий вывод документации для определенного фрагмента. Обычно он ставится в той же строке, где начинается определение класса или метода.

    class Alpha # :nodoc:

     class Beta

      # ...

     end

     # ...

    end

    Здесь класс

    Alpha
    не будет документироваться. Однако тег
    :nodoc:
    не является рекурсивным — класс
    Beta
    документируется. Если желательно рекурсивное

    поведение, укажите

    :nodoc: all
    . В следующем примере игнорируются оба класса
    Gamma
    и
    Delta
    :

    class Alpha # :nodoc: all

     class Beta

      # ...

     end

     # ...

    end

    Имеется также модификатор

    :doc:
    с прямо противоположным смыслом. Он включает документацию для фрагментов, которые иначе не были бы документированы.

    Модификатор

    :notnew:
    специальный; он предотвращает документирование метода
    new
    (на основе существующего метода
    initialize
    ).

    Если вы хотите дать осмысленные имена параметрам

    yield
    , воспользуйтесь тегом
    :yields:
    . Например, если в самом тексте употребляются ничего не значащие имена
    x
    и
    у
    , то в документации их можно заменить.

    def iterate # :yields: element, index

     # ...

     yield x, i

    end

    Некоторые теги используются только внутри блока комментариев, например:

    • 

    :include:
    — включить содержимое указанного файла в документацию. При этом будут сформированы подходящие отступы;

    • 

    :titlе:
    — задать заголовок документа;

    • 

    :main:
    — задать начальную страницу документации.

    Дополнительную информацию вы найдете в книге «Programming Ruby» или в любом онлайновом справочном руководстве.

    17.2. Установка и подготовка пакета

    У пользователя должно быть ощущение «коробочного продукта». Как пользователи мы готовы подписаться под этим тезисом обеими руками, но как разработчики не любим заниматься вопросами создания пакетов и установки.

    К счастью, в Ruby все это не так болезненно, как в некоторых других языках и средах. Вы обязательно должны знать о библиотеке

    setup
    и системе RubyGems — «родных» для Ruby инструментах создания пакетов и развертывания.

    17.2.1. Библиотека setup.rb

    Автором библиотеки

    setup.rb
    является Минеро Аоки (Minero Aoki). Он же разработал библиотеку
    install.rb
    , которая сейчас используется реже.

    Кто-то скажет, что по мере развития системы RubyGems все это становится не актуальным. А кто-то возразит, что у gem-пакетов есть свои проблемы (технические, политические и пр.). А кто-то считает, что «добропорядочный гражданин» должен включать

    setup.rb
    даже в gem-пакет (упрощая задачу перепакетирования, например для создания Linux-дистрибутива). Решать вам.

    Половина дела будет сделана, если вы скопируете все файлы в нужные места. Вы должны организовать свой архив простым и разумным образом (создав каталоги с предопределенными именами).

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

    setup.rb
    помещается на верхний уровень).

    top_level/

     setup.rb

     metaconfig (необязательно)

     lib/

     ext/

      myext/

     bin/

     data/

     conf/

     man/

     test/

    Пустые каталоги можно опускать. Ниже описано назначение каждого каталога:

    • 

    lib
    —программы на Ruby;

    • 

    ext
    — расширения Ruby (написанные на С);

    • 

    myext
    — имя расширения (на том же уровне могут располагаться и другие расширения); в каталоге каждого расширения должен находиться либо файл
    extconf.rb
    , либо
    MANIFEST
    ;

    • 

    bin
    — команды;

    • 

    data
    — файлы данных;

    • 

    conf
    — конфигурационные файлы;

    • 

    man
    — страницы руководства;

    • 

    test
    — автономные тесты и другие тестовые программы.

    В общем случае эти файлы никак не обрабатываются, а просто копируются в нужное место. Но для специализированной настройки предусмотрены места подключения к каждому этапу процесса.

    Три основных этапа — это

    config
    ,
    setup
    и
    install
    , вызываемые пользователем именно в таком порядке (на последнем шаге могут потребоваться полномочия root или, по крайней мере, выполнение
    sudo
    ).

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

    lib/foobar
    , следует создать файл
    lib/foobar/pre-setup.rb
    и поместить в него произвольный код.

    Имя файла формируется следующим образом: префикс

    pre
    или
    post
    , дефис, имя задачи. Определены следующие имена задач:
    config
    ,
    setup
    ,
    install
    ,
    test
    ,
    clean
    и
    dist-clean
    .

    В библиотеке

    setup.rb
    есть понятия каталога исходных файлов, или исходного каталога (source directory) и каталога объектных файлов, или объектного каталога (object directory). Как правило, вы должны читать из исходного каталога и записывать в текущий каталог.

    Существует «API для подключения» (hook API), упрощающий решение ряда задач. Приведем некоторые определенные в нем методы:

    • 

    get_config_key(key)
    — принимает в качестве параметра ключ и возвращает ассоциированное с ним значение (например,
    get_config('prefix')
    возвращает путь, определенный с помощью конфигурационного параметра
    --prefix
    );

    • 

    set_config_key(key, val)
    — устанавливает значение конфигурационного параметра;

    • 

    config_key(key)
    — то же, что
    get_config_key
    ;

    • 

    curr_srcdir
    — текущий исходный каталог;

    • 

    curr_objdir
    — текущий объектный каталог;

    • 

    srcfiles(rel_path=".")
    — список всех файлов в каталоге с путем
    rel_path
    (относительно текущего исходного каталога).

    На верхнем уровне может находиться файл

    metaconfig
    . Если он есть, то в нем задаются некоторые глобальные конфигурационные параметры. Для этой цели имеется специальный «metaconfig API» — небольшой набор вспомогательных методов, в частности:

    add_path_config(confname, default, description)
    — определяет конфигурационный параметр, являющийся путем; задаются имя и значение по умолчанию. При вызове с флагом --help эта информация печатается;

    add_bool_config(confname, default, description)
    — аналог
    add_path_config
    , но описывается булевский параметр.

    Дополнительную информацию по этим API можно найти в актуальной онлайновой документации.

    17.2.2. Система RubyGems

    Идея и название системы RubyGems принадлежат Райану Ливенгуду (Ryan Leavengood), но текущая реализация зародилась на ночной вечеринке, состоявшейся после Международной конференции по Ruby 2003 года в Остине, штат Техас. Первый вариант кода написали Чэд Фаулер (Chad Fowler), Джим Вайрих (Jim Weirich), Дэвид Алан Блэк (David Alan Black), Рич Килмер (Rich Kilmer) и Пол Брэннен (Paul Brannan). С тех пор к ним присоединились и другие; особо стоит отметить Эрика Ходеля (Eric Hodel) и Райана Дэвиса (Ryan Davis).

    В настоящее время RubyGems, наверное, самая распространенная система создания пакетов, хотя до сих пор не включена в дистрибутив. Я полагаю, что после устранения нескольких мелких огрехов она станет настоящим стандартом для Ruby.

    Как и повсюду в этой главе, мы рассматриваем вопрос с точки зрения разработчика. Вы узнаете, как представлять плоды своего труда в виде gem-пакета, но о манипулировании пакетами извне мы говорить не будем. Это тема другого раздела.

    Возникает естественный вопрос: «Зачем нужно использовать gem-пакеты?» Вот перечень лишь некоторых их достоинств:

    • простота установки и удаления;

    • поддержка нескольких версий;

    • управление зависимостями;

    • механизм запроса и поиска пакетов.

    Имя gem-пакета обычно состоит из короткого описательного слова, за которым следует дефис и стандартный номер версии в формате «основной.дополнительный.рабочий», который ныне принят почти повсеместно (конечно, каждая часть номера может состоять из нескольких цифр). Мы настоятельно рекомендуем пользоваться механизмом рациональной нумерации версии; если вы с ним не знакомы, поищите описание в сети.

    Для построения gem-пакета нужно начать с создания предопределенного дерева каталогов (примерно такого же, как для

    setup
    ). На верхнем уровне неплохо поместить файл README, в который включаются информация об авторе и способе связи с ним, авторские права, лицензионное соглашение, перечень известных ошибок и т.д. Если вы напишете этот файл в формате
    RDoc
    , его можно будет включить и в состав HTML-документации проекта.

    Для построения gem-пакета необходимо создать его спецификацию (gemspec). Это один из тех случаев, когда стирается грань между кодом и данными. Спецификация - это просто исполняемый файл на языке Ruby:

    гequire 'rubygems'

    SPEC = Gem::Specification.new do |s|

     s.name = "Drummer"

     s.version = "1.0.2"

     s.author = "H. Thoreau"

     s.email = "cabin@waldenpond.com"

     s.homepage = "http://waldenpond.com/Drummer"

     s.platform = Gem::Platform::RUBY

     s.summary = "A Ruby app for those who march to a different drummer"

     s.files = Dir["./*"] + Dir["*/**"]

     s.test_file = "test/ts_drum.rb"

     s.has_rdoc = true

     s.require_path = "lib"

     s.extra_rdoc_files = ["README", "ChangeLog"]

     s.add_dependency "KirbyBase", ">=2.5.0"

    end

    Назначение многих атрибутов понятно из названия. Но есть и другие, хотя обычно они не так важны и встречаются реже. Обратитесь к онлайновой документации по RubyGems.

    Имея файл спецификации, можно создать gem-пакет двумя способами. Во-первых, можно просто выполнить файл (в конце концов, это ведь обычная программа на Ruby). Тогда в текущем каталоге будет создан пакет с указанным именем. Альтернативно можно воспользоваться командой

    gem build
    , которой передается имя файла спецификации. Результат будет один и тот же.

    Созданный gem-пакет можно распространять через Web или любым другим способом. Я настоятельно рекомендую для управления проектом пользоваться сайтом RubyForge. Если загруженный на него архив содержит файл спецификации, то пакет будет создан автоматически. В следующем разделе мы поговорим о сайте RubyForge и архиве приложений Ruby (RAA).

    17.3. RubyForge и RAA

    Есть два основных источника библиотек и приложений на языке Ruby (помимо стандартного дистрибутива). Первый и самый старый — это архив приложений Ruby (Ruby Application Archive или RAA), расположенный на официальном сайте Ruby по адресу http://raa.ruby-lang.org.

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

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

    Когда писалась эта книга, в архиве RAA было свыше 1400 проектов, распределенных по четырем основным рубрикам и 243 подрубрикам. Основными являются рубрики «Приложения», «Документация», «Библиотеки» и «Перенос на другие платформы». Из них последняя самая маленькая, так как задача переноса Ruby далеко не тривиальна. Рубрика «Документация» немногим больше. Более 90% содержимого RAA попадает в рубрики «Библиотеки» и «Приложения». Скорее всего, все созданное вами окажется там же.

    Рубрика «Приложения» состоит из 94 подкатегорий, включающих 449 проектов. Некоторые подрубрики достаточно обширны, например: «Языки», «Базы данных», «Редакторы», «Криптография», «Wiki», «Графические интерфейсы», «HTML». В рубрике «Библиотеки» 952 проекта, отнесенных к 127 подрубрикам, например: «Аудио», «Календарь», «Химия», «Файловые системы», «Численные методы» и «Телефония». Разумная классификация помогает быстрее найти интересующий вас проект. Конечно, на сайте есть и система поиска, но все равно иметь возможность просмотра иерархии полезно.

    Впрочем, следует отметить, что классификация не всегда полна и в ряде случаев не ортогональна. Если точной подрубрики для вашего проекта еще нет, пойдите на компромисс или создайте новую подрубрику (но осторожно).

    Само собой разумеется, что не следует усугублять проблему «битых» ссылок. Попытайтесь разместить свой проект на сайте, который никуда не денется. Время от времени просматривайте информацию о своих проектах в RAA и проверяйте, не изменился ли URL проекта или ваш электронный адрес.

    Второй лучший друг «рубиста» — сайт RubyForge (http://rubyforge.org). Это огромное хранилище проектов, построенное по образцу SourceForge. Конечно, по своей философии RubyForge сильно отличается от RAA. На этом сайте хранятся не только метаданные, но и сами файлы программ, документация и т.д. В настоящее время там находится свыше 1600 проектов (больше чем в RAA) и зарегистрировано более 6800 пользователей.

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

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

    У сайта RubyForge есть приятная особенность: если загруженный пакет содержит спецификацию gem-пакета, этот пакет будет создан и предложен для скачивания автоматически. Вот так и должно работать все в этом мире!

    Помимо страницы скачивания у каждого проекта может быть собственная страница. Многие, однако, обходятся без нее; заходя на страницу такого проекта, вы нередко видите всего лишь подразумеваемое по умолчанию сообщение «Coming soon!» (Скоро). Не думайте, что проект закрыт или заморожен — просто его владелец не счел нужным заполнять эту страницу. Если вы еще не поняли, к чему я веду, то скажу ясно — создавайте начальные страницы для своих проектов, даже если они размещены где-то в другом месте. Не так уж сложно поддерживать синхронизацию между ними.

    Обычно URL проекта начинается с короткого имени, например http://rmagick.rubyforge.org (это библиотека RMagick Тима Хантера).

    Для доступа к своему проекту на RubyForge, как правило, достаточно воспользоваться программой

    scp
    и скопировать файлы в точно определенные места. Для многих операций, скажем управления списками рассылки, имеется Web-интерфейс.

    Для организации более выразительного интерфейса с проектами на сайте RubyForge существуют также командные (и, быть может, даже графические) утилиты. Но они не являются «официальными» и широкого распространения не получили. Чтобы узнать, поддерживаются ли такие инструменты в настоящее время, займитесь поиском в сети.

    17.4. Заключение

    В этой главе мы изучили основы документирования проектов с помощью инструмента

    RDoc
    , а также познакомились с программой
    setup.rb
    и системой RubyGems — двумя наиболее популярными способами создания дистрибутивных пакетов.

    Наконец, мы бегло рассмотрели сайт RubyForge и архив приложений Ruby (RAA), которые позволяют оповещать о созданном программном обеспечении и распространять его. В следующей главе мы снова переключим передачу и поговорим об интересной и сложной предметной области: программировании для сетей и, в частности, Web.









    Главная | В избранное | Наш E-MAIL | Добавить материал | Нашёл ошибку | Наверх