Доброго времени суток!
Наконец-то я нашёл немного времени для того, чтобы продолжить своё повествование о разнообразных чудесах в Ruby. Как вы помните, в прошлой части мы познакомились с основами написания своего гема. Мы узнали, какой минимальный набор файлов должен быть для того, чтобы его собрать. Также мы узнали как мы можем опубликовать своё творение в RubyGems. В тот же день (после написания первой части) в RubyGems неожиданно проявился всплеск гемов под названием hello-world. Причём я застал довольно много вариаций оного. Некоторые даже не удосужились поменять строку, где указывается автор гема.
Некоторые вовсе задавали гему следующие значения версий:
В общем было достаточно много других вариаций, что меня, как автора, безусловно, не могло не радовать.
В сегодняшней части я хотел бы представить вам обзор доступных нам свойств в файле спецификации. Знание этих самых свойств является, на мой взгляд, MUST HAVE.
Так как сами гемы мы строить уже умеем, перейдем к самой теории.
Начнать перечисление, думаю, стоит в следующем порядке:
Итак, начнём.
Тип: Time.
Значение по умолчанию: Time.now
Описание: Дата/время, когда гем был создан.
Пример:
Примечание: обычно это поле программистами не заполняется, т.к. оно уже имеет значение по умолчанию.
Тип: String.
Значение по умолчанию: не имеет.
Описание: Имя нашего гема.
Пример:
Примечание: в имени нельзя писать номер версии нашего гема, т.к. для этого есть отдельное поле.
Тип: String.
Значение по умолчанию: Gem::Platform::Ruby
Описание: Платформа, для которой, собственно, мы и написали наш гем.
Пример:
Примечание: данное свойство стоит заполнять лишь в том случае, если в вашем геме имеется расширение, предназначенное лишь для определённой платформы. Например, мы написали обёртку Win API.
Тип: Array.
Значение по умолчанию: [«lib»]
Описание: Листинг, в котором указывается обязательное наличие какой-либо папки с нашими .rb или README файлами.
Пример:
Примечание: данное свойство не стоит использовать лишь в случае HelloWorld'ов, в остальных же, несомненно, стоит, т.к. порой всё же удобно распологать коней в их конюшнях, а не всех держать в одной.
Тип: String.
Значение по умолчанию: не имеет.
Описание: краткое описание нашего гема.
Пример:
Примечание: данное свойство довольно часто путают со свойством description, которое является менее важным свойством.
И последнее обязательное свойство на сегодня.и на всю жизнь
Тип: String.
Значение по умолчанию: не имеет.
Описание: версия нашего гема.
Пример:
Примечание: также допустимым значением могут являться значения, представленные классом Gem::Version, но в основном его никто не использует. Помните, что строка должна содержать лишь числовые значения, а не текст.
Вот и всё. С обязательными свойствами мы с вами разобрались. Теперь, вы можете спокойно подставлять свои имена, номера версий и прочее, а не публиковать их под моим именем. Шучу, я, конечно же не против.
Устали? Сильно? Можете выпить чашечку кофе, после чего вернуться к нам на огонёк.
Кроме обязательных свойств, которые вы обязаны применять, не стоит забывать и об опциональных. Ну что, приступим.
Тип: String или Array, в случае, если авторов несколько.
Значение по умолчанию: не имеет.
Описание: указывает имя или ник автора гема, или же создателяВселенной библиотеки, содержащейся в геме.
Пример:
Примечание: без комментариев.
Нет, на него отвлекаться мы не будем, т.к. его давным давно за ненадобностью запретили. И пойдём дальше.
Тип: String.
Значение по умолчанию: «bin»
Описание: Папка, содержащая файлы какого-либо исполняемого файла, т.е. приложения, если такие имеются.
Пример:
Примечание: под «приложением» подуразумевается любой файл, который можно выполнить через командную строку.
Тип: String.
Значение по умолчанию:не имеет. Имеет. Как в графе «семейное положение» всё сложно. На самом деле нет. Читайте примечание.
Описание: Папка, содержащая в себе приложение, которое можно запустить из гема.
Пример:
Примечание: если в executables указывается лишь одна директория, то она и будет являться значением для default_executable. Данное значение стоит трогать, если у вас два или более исполняемых файлов.
Тип: Array.
Значение по умолчанию: [], т.е. ничего не требуется.
Описание: Листинг гемов, необходимых для работы нашего.
Пример:
Примечание: сначала будет проверено хранилище, в котором живут уже установленные гемы. Если нужные нам будут найдены, то ничего страшного не произойдет, равно как и не найдет. В данном случае недостающие для работы гемы будут загружены из RubyGems репозитория.
Свойство аналогичное предыдущему.
По сути говоря, данное свойство не рекоммендуется использовать. Вместо него стоит использовать summary
email
Тип: String или Array.
Значение по умолчанию: не имеет.
Описание: e-mail для обратной связи с автором/авторами.
Пример:
Примечание: это ещё и был намёк для read-only аккаунтов, которые в слу обстоятельств часто просто-напросто не могут связаться с автором топика по каким-либо интересующим их вопросам.
О данном свойстве мы уже говорили в default_executable. Больше о нём нечего сказать.
Тип: Array.
Значение по умолчанию: не имеет.
Описание: Директории, содержащие в себе файлы-расширения.
Пример:
Примечание: эти файлы будут запущены, когда гем будет инсталлирован и расширения будут скомпилированы.
Тип: Array.
Значение по умолчанию: не имеет.
Описание: Листинг дополнительных файлов, которые будут использованы при генерации RDoc документации.
Пример:
Примечание: без комментариев.
Тип: Array.
Значение по умолчанию: не имеет.
Описание: Листинг файлов, содержащихся в геме.
Пример:
Примечание: тут тоже особо нечего комментировать.
Тип: Boolean.
Значение по умолчанию: false
Описание: Указывает, существует ли для данного гема RDoc документация.
Пример:
Примечание: свойство, отъедающее некоторое количество байт в вашем файле.
Тип: String.
Значение по умолчанию:microsoft.com, ага не имеет.
Описание: адрес сайта данног гема.
Пример:
Примечание: также без комментариев.
Тип: String или Array.
Значение по умолчанию: не имеет.
Описание: лицензия/лицензии, под которыми были опубликованы гемы.
Пример:
Примечание: каждое название лицензий должно составлять не более 64 символов.
Тип: Array.
Значение по умолчанию: []
Описание: указывает форматирование RDoc документации.
Пример:
Примечание: попробуйте и убедитесь в том, что это работает.
Тип: Gem::Version::Requirement.
Значение по умолчанию: > 0.0.0
Описание: версия Ruby, необходимая для работы с нашим гемом.
Пример:
Примечание: очень полезное свойство, которое приведёт к меньшему количеству ошибок при попытке использования гема. Взять ситуацию с тем же XMPP4R, который не работает с 1.9.0 или же заводиться по настроению.
Не будем рассматривать данное свойство за ненадобностью, т.к. оно несёт в себе лишь текстовую информацию для пользователя.
Тип: String.
Значение по умолчанию: не имеет.
Описание: имя проекта на RubyForge.
Пример:
Примечание: если у вас нет проекта на RubyForge не стоит трогать это свойство за ненадобностью.
И, о чудо (!!!) последнее свойство.
Тип: String или Array.
Значение по умолчанию: '' или []
Описание: Директория/директории, содержимым которой являются ваши юнит-тесты, если таковые имеются.
Пример:
На этом вторая часть нашего знакомства с gem закончена. Сегодня мы с вами узнали о всевозможных свойствах, используемых для корректной настройки гема. Хочется поздравить тех, кто дошёл до конца даннного топика со здоровыми глазами. Но, увы, сисек не будет!
До скорых встреч!
Ах да, чуть не забыл. Вы можете также руководствоваться вот этим гайдом при закреплении изученного.
Вместо введения
Наконец-то я нашёл немного времени для того, чтобы продолжить своё повествование о разнообразных чудесах в 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
Тип: 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.
Значение по умолчанию:
Описание: адрес сайта данног гема.
Пример:
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 закончена. Сегодня мы с вами узнали о всевозможных свойствах, используемых для корректной настройки гема. Хочется поздравить тех, кто дошёл до конца даннного топика со здоровыми глазами. Но, увы, сисек не будет!
До скорых встреч!
Ах да, чуть не забыл. Вы можете также руководствоваться вот этим гайдом при закреплении изученного.