RubyGems - detail

To begin with, we will define the concepts:
RubyGems is a framework for installing and packing Ruby libraries and applications.
gem - package (file) with a library or application. It has a standardized view and is located in the repository on the network.
gem command tool - RubyGems provides the “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 it, download it, try to install it, often just to make sure that the necessary dependencies were missing. If the library is packaged with RubyGems, all you have to do is ask RubyGems to do it for us and get an installed, integrated library with all the necessary dependencies. In addition to everything, the gem utility is platform independent, no matter what OS you use, everywhere the installation mechanism of libraries and applications will be the same. Great, right?
')
Under the cat will be described:
1) Search, receive parts, install gem's
2) Documentation access for the installed gem
3) Use installed gem's
4) Working with gem's versions
5) Create your own gem's

1. Search, obtain parts, install gem's

Suppose you generate a lot of XML in your current project. And somewhere you have heard that there is a wonderful library Jim Weirich's Builder library, which allows you to create XML directly in the Ruby code.
Let's see if it is available as a gem:
% 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.
...

--details - displays details about the gem found
--remote - searches remote storage ( --locale - local search)
--name-matches build - filters gem's by the contents of the string 'build' in the name
The number next to the name of each gem shows the latest version.
List of all available versions for a specific gem, run the list command with the --all option:
% 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.

To install the latest version:
% gem install builder #RubyGems
By default (if you do not use RVM ), common system directories are used to install gem's, so under Unix you need to add sudo before the gem command.
The list of gem's already installed on your computer:
gem list
*** LOCAL GEMS ***
builder (2.1.2)


2. Reading the documentation for the installed gem

We installed gem builder, the question arises, how to work with it?
In most cases, gem contains documentation, it is stored in the / doc directory, for example:
# gem's
% gem environment gemdir
/usr/local/lib/ruby/gems/1.9.0

/usr/local/lib/ruby/gems/1.9.0/doc - here is the documentation for the installed gem's
/usr/local/lib/ruby/gems/1.9.0/doc/builder-2.1.2/rdoc/index.html - full path to the documentation of the gem builder 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 file
2. An easier way to start a web server is with the % gem server command.
By default, it will start on port 8808 and will be accessible via the link localhost: 8808
In the browser you will see the documentation for all installed gem's.
The path to the gem's directory and port can be redefined using the -p and -d options.

3. Using installed gem's

After installing the gem, just write the command require <name gem> 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. Working with gem's versions

What if the latest version of the gem you are using is not compatible with the one you are using now?
Fortunately, RubyGems allows us to simultaneously store several versions of the gem. The following commands will install both versions of the 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 version greater than first
gem 'builder' , ''>= 2.2.0', '< 3.0'' - use version greater than 2.2.0 and less than 3.0
Full list of expressions:
=
!=
>
<
>=
<=
~> ( RubyGems docs)


5. Creating your own gem's

It's all pretty simple, I will describe the basic steps, details can be read here.

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

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