Pull to refresh

Знакомство с Gem. Часть вторая

Reading time 6 min
Views 2.5K
Доброго времени суток!

Вместо введения


Наконец-то я нашёл немного времени для того, чтобы продолжить своё повествование о разнообразных чудесах в Ruby. Как вы помните, в прошлой части мы познакомились с основами написания своего гема. Мы узнали, какой минимальный набор файлов должен быть для того, чтобы его собрать. Также мы узнали как мы можем опубликовать своё творение в RubyGems. В тот же день (после написания первой части) в RubyGems неожиданно проявился всплеск гемов под названием hello-world. Причём я застал довольно много вариаций оного. Некоторые даже не удосужились поменять строку, где указывается автор гема.
g.author = "krovatti"

Некоторые вовсе задавали гему следующие значения версий:
g.version = "666"
g.version = "111"
g.version = "911"

В общем было достаточно много других вариаций, что меня, как автора, безусловно, не могло не радовать.


Что нас ожидает сегодня


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

С чего начнём


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

Итак, начнём.

date

Тип: Time.
Значение по умолчанию: Time.now
Описание: Дата/время, когда гем был создан.
Пример:
g.date = File.utime('VERSION')

Примечание: обычно это поле программистами не заполняется, т.к. оно уже имеет значение по умолчанию.

name

Тип: String.
Значение по умолчанию: не имеет.
Описание: Имя нашего гема.
Пример:
g.name = 'woohaha'

Примечание: в имени нельзя писать номер версии нашего гема, т.к. для этого есть отдельное поле.

platform

Тип: String.
Значение по умолчанию: Gem::Platform::Ruby
Описание: Платформа, для которой, собственно, мы и написали наш гем.
Пример:
g.platform = Gem::Platform::Win32

Примечание: данное свойство стоит заполнять лишь в том случае, если в вашем геме имеется расширение, предназначенное лишь для определённой платформы. Например, мы написали обёртку Win API.

require_paths

Тип: Array.
Значение по умолчанию: [«lib»]
Описание: Листинг, в котором указывается обязательное наличие какой-либо папки с нашими .rb или README файлами.
Пример:
# если все файлы расположены в корневом каталоге
g.require_paths = '.'

# или, например, у нас есть папки 'lib и 'ext'
g.require_paths << 'ext'

Примечание: данное свойство не стоит использовать лишь в случае HelloWorld'ов, в остальных же, несомненно, стоит, т.к. порой всё же удобно распологать коней в их конюшнях, а не всех держать в одной.

summary

Тип: String.
Значение по умолчанию: не имеет.
Описание: краткое описание нашего гема.
Пример:
g.summary = 'I love Ruby and this extension was created specially for its beauty'

Примечание: данное свойство довольно часто путают со свойством description, которое является менее важным свойством.

И последнее обязательное свойство на сегодня. и на всю жизнь

version

Тип: String.
Значение по умолчанию: не имеет.
Описание: версия нашего гема.
Пример:
g.version = '1.0.5'

Примечание: также допустимым значением могут являться значения, представленные классом Gem::Version, но в основном его никто не использует. Помните, что строка должна содержать лишь числовые значения, а не текст.

Вот и всё. С обязательными свойствами мы с вами разобрались. Теперь, вы можете спокойно подставлять свои имена, номера версий и прочее, а не публиковать их под моим именем. Шучу, я, конечно же не против.
Устали? Сильно? Можете выпить чашечку кофе, после чего вернуться к нам на огонёк.

Итак, продолжим


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

author или authors

Тип: String или Array, в случае, если авторов несколько.
Значение по умолчанию: не имеет.
Описание: указывает имя или ник автора гема, или же создателя Вселенной библиотеки, содержащейся в геме.
Пример:
# если автор один
g.author = 'Mike Vazovski'

# или же их несколько
g.authors = ['Mike Vazovski', 'Vladimir Putin']

Примечание: без комментариев.

autorequire

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

bindir

Тип: String.
Значение по умолчанию: «bin»
Описание: Папка, содержащая файлы какого-либо исполняемого файла, т.е. приложения, если такие имеются.
Пример:
g.bindir = 'bin'

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

default_executable

Тип: String.
Значение по умолчанию: не имеет. Имеет. Как в графе «семейное положение» всё сложно. На самом деле нет. Читайте примечание.
Описание: Папка, содержащая в себе приложение, которое можно запустить из гема.
Пример:
g.default_executable = 'bin/debin'

Примечание: если в executables указывается лишь одна директория, то она и будет являться значением для default_executable. Данное значение стоит трогать, если у вас два или более исполняемых файлов.

dependencies

Тип: Array.
Значение по умолчанию: [], т.е. ничего не требуется.
Описание: Листинг гемов, необходимых для работы нашего.
Пример:
g.add_dependencies 'sinatra'

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

development_dependencies

Свойство аналогичное предыдущему.

description

По сути говоря, данное свойство не рекоммендуется использовать. Вместо него стоит использовать summary

email

Тип: String или Array.
Значение по умолчанию: не имеет.
Описание: e-mail для обратной связи с автором/авторами.
Пример:
# если автор один
g.email = 'krovatti@gmail.com'

# если авторов несколько
g.email = ['blablabla@yahoo.eu','krovatti@gmail.com']

Примечание: это ещё и был намёк для read-only аккаунтов, которые в слу обстоятельств часто просто-напросто не могут связаться с автором топика по каким-либо интересующим их вопросам.

executables

О данном свойстве мы уже говорили в default_executable. Больше о нём нечего сказать.

extensions

Тип: Array.
Значение по умолчанию: не имеет.
Описание: Директории, содержащие в себе файлы-расширения.
Пример:
g.extensions << 'ext/rmagic/wtf.rb'

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

extra_rdoc_files

Тип: Array.
Значение по умолчанию: не имеет.
Описание: Листинг дополнительных файлов, которые будут использованы при генерации RDoc документации.
Пример:
g.extra_rdoc_files = ['README', 'doc/user-guide.txt']

Примечание: без комментариев.

files

Тип: Array.
Значение по умолчанию: не имеет.
Описание: Листинг файлов, содержащихся в геме.
Пример:
g.files = Dir['lib/**/*.rb]

Примечание: тут тоже особо нечего комментировать.

has_rdoc

Тип: Boolean.
Значение по умолчанию: false
Описание: Указывает, существует ли для данного гема RDoc документация.
Пример:
g.has_rdoc = true

Примечание: свойство, отъедающее некоторое количество байт в вашем файле.

homepage

Тип: String.
Значение по умолчанию: microsoft.com, ага не имеет.
Описание: адрес сайта данног гема.
Пример:
g.homepage = 'http://github.com/ln/xmpp4r'

Примечание: также без комментариев.

license или licenses

Тип: String или Array.
Значение по умолчанию: не имеет.
Описание: лицензия/лицензии, под которыми были опубликованы гемы.
Пример:
g.license = 'MIT' # если одна лицензия
g.licenses = ['MIT', 'GPL-2'] # если двойная лицензия, например

Примечание: каждое название лицензий должно составлять не более 64 символов.

rdoc_options

Тип: Array.
Значение по умолчанию: []
Описание: указывает форматирование RDoc документации.
Пример:
g.rdoc_options << '--title' << 'Rake -- Ruby Make' << '--main' << 'README' << --line-numbers'

Примечание: попробуйте и убедитесь в том, что это работает.

required_ruby_version

Тип: Gem::Version::Requirement.
Значение по умолчанию: > 0.0.0
Описание: версия Ruby, необходимая для работы с нашим гемом.
Пример:
g.required_ruby_version = '>= 1.8.1'

Примечание: очень полезное свойство, которое приведёт к меньшему количеству ошибок при попытке использования гема. Взять ситуацию с тем же XMPP4R, который не работает с 1.9.0 или же заводиться по настроению.

requirements

Не будем рассматривать данное свойство за ненадобностью, т.к. оно несёт в себе лишь текстовую информацию для пользователя.

rubyforge_project

Тип: String.
Значение по умолчанию: не имеет.
Описание: имя проекта на RubyForge.
Пример:
g.rubyforge_project = 'yahoo-eu'

Примечание: если у вас нет проекта на RubyForge не стоит трогать это свойство за ненадобностью.

И, о чудо (!!!) последнее свойство.

test_files

Тип: String или Array.
Значение по умолчанию: '' или []
Описание: Директория/директории, содержимым которой являются ваши юнит-тесты, если таковые имеются.
Пример:
g.test_files = 'tests/wtf.rb' # 1
g.test_files = ['tests/wtf.rb',tests/wtf2.rb']


Вот и всё


На этом вторая часть нашего знакомства с gem закончена. Сегодня мы с вами узнали о всевозможных свойствах, используемых для корректной настройки гема. Хочется поздравить тех, кто дошёл до конца даннного топика со здоровыми глазами. Но, увы, сисек не будет!

До скорых встреч!

Ах да, чуть не забыл. Вы можете также руководствоваться вот этим гайдом при закреплении изученного.
Tags:
Hubs:
+33
Comments 23
Comments Comments 23

Articles