RubyGems - detail

First , let's define the following concepts:
RubyGems - a framework for installing and packing Ruby libraries and applications.
gem - a package (file) with a library or application. It has a standardized look and is located in the network storage.
gem command tool - RubyGems provides a gem utility for working with gem packages from the command line. It is integrated with Ruby and allows you to access installed gems as libraries.

What is the purpose of RubyGems?

Before RubyGems appeared, to install a new library you had to find, download it, try to install it, often just to make sure there were no necessary dependencies. If the library is packed using RubyGems, just ask RubyGems to do this for us and get the installed, integrated library with all the necessary dependencies. In addition to everything, the gem utility is platform independent, no matter which OS you use, everywhere the installation mechanism of libraries and applications will be the same. Great, right?

Under the cut will be described:
1) Search, obtain details, install gem's
2) Access documentation on installed gem
3) Use installed gem's
4) Work with gem's versions
5) Create your own gem's

1. Search, get parts, install gem's

Let's say a lot of XML is generated in your current project. And somewhere you heard that there is a wonderful Jim Weirich's Builder library that allows you to create XML directly in Ruby code.
Let's see if it is available as a gem: --details - displays details about the gem found --remote - searches on the remote storage ( --locale - search on the local machine) --name-matches build - filters gem's by the contents of the string 'build 'in the name Number near the name of each gem, shows the latest version. A list of all available versions for a particular gem, run the list command with the --all option : To install the latest version:
% gem query --details --remote --name-matches build
*** REMOTE GEMS ***
AntBuilder (0.4.3)
  Author: JRuby-extras
  Homepage: jruby-extras.rubyforge.org
  AntBuilder: Use ant from JRuby. Only usable within JRuby
builder (2.1.2)
  Author: Jim Weirich
  Homepage: onestepback.org
  Builders for MarkUp.
  ...






% gem list --details --remote --all builder
*** REMOTE GEMS ***
builder (2.1.2, 2.1.1, 2.0.0, 1.2.4, 1.2.3, 1.2.2, 1.2.1, 1.2.0, 1.1.0,
1.0.0, 0.1.1, 0.1.0)
  Author: Jim Weirich
  Homepage: onestepback.org
  Builders for MarkUp.


% gem install builder #RubyGems сам выберет последнюю
By default (if you are not using RVM ), the system directories are used to install gem's, so under Unix you need to add sudo before the gem command.
List of gem's already installed on your computer:
gem list
*** LOCAL GEMS ***
builder (2.1.2)


2. Reading the documentation of the installed gem

We installed gem builder, the question is, how to work with it?
In most cases, gem contains documentation, it is stored in the / doc directory, for example: /usr/local/lib/ruby/gems/1.9.0/doc - here lies the documentation for installed gem's / usr / local / lib / ruby ​​/ gems / 1.9.0 / doc / builder-2.1.2 / rdoc / index.html - the full path to the gem builder documentation in my case There are 2 ways to read the documentation: 1. Go to the directory with the gem documentation and run the index.html 2 file An easier way is to start the web server using the command By default, it will start on port 8808 and will be available at the localhost link: 8808 In the browser you will see the documentation for all installed gem's.
#Узнаем путь где хранятся наши gem's
% gem environment gemdir
/usr/local/lib/ruby/gems/1.9.0






% gem server


The path to the gem's directory and the port can be overridden by using the options -p and -d

3. Using installed gem's

After installing gem, just write the command require <gem name> to connect it. Those. working with gems is no different from working with regular libraries.

# пример генерации XML с помощью установленной нами библиотеки
require 'builder'
xml = Builder::XmlMarkup.new(target: STDOUT, indent: 2)
xml.person(type: "programmer") do
  xml.name do
    xml.first "Dave"
    xml.last "Thomas"
  end
  xml.location "Texas"
  xml.preference("ruby")
end

4. Work with gem's versions

What if the latest released version of the gem you are using is not compatible with the one you are using now?
Fortunately, RubyGems allows us to store multiple versions of gem at the same time. The following commands will install both versions of builder.
% gem install builder -v 2.1.2
% gem install builder -v 1.1.0
% gem list builder
*** LOCAL GEMS ***
  builder (2.1.2, 1.1.0)


#Подключение builder v.1.1.0
gem 'builder', '= 1.1.0'
require 'builder'
xml = Builder::XmlMarkup.new(STDOUT, 2)
xml.person do
  name("Dave Thomas")
  location("Texas")
end

Here are a few more tricks available:
gem 'builder' , '> 1'- use a version larger than the first
gem 'builder' , ''>= 2.2.0', '< 3.0''- use a version greater than 2.2.0 and less than 3.0
Full list of expressions:
= идентичная версия
!= неидентичная версия
> версия больше чем
< версия меньше чем
>= большая и равная версия
<= меньшая или равная версия
~> примерно больше чем (подробнее RubyGems docs)


5. Create your own gem's

Everything is quite simple here, I will describe the basic steps, details can be read here

1. writing code corresponding to the gem structure
2. creating specification file (ourgem.gemspec)
3. create gem file
   % gem build mygem.gemspec
   
4. placing the created gem on rubygems.org server
   %gem push mygem.gemspec
   

Sources:
http://docs.rubygems.org/
Programming Ruby 1.9 3rd Edition