Almost complete ruby ​​gems writing guide

Good day, user .

Not so long ago, I had the task to make a prototype for one project. It included work with the Facebook Graph API. Having picked up some gems, I realized that they are not very convenient for me or they implement the necessary functionality too difficult. And then an old idea of ​​writing my heme came to my mind. Having a lot of inquiries on this topic, I did not find complete information, especially on Russian-language resources. This is how the idea of ​​this article appeared. The manual is called “almost complete” , since not all aspects are covered here, but only those that are minimally necessary and desirable for the beginning of the existence of the product of your imagination. I ask under the cat!

Let's start with the basic (thanks to Wikipedia):

RubyGems (from gem, gems — gem) is a package management system for the Ruby programming language that provides the standard format for Ruby programs and libraries (in the self-contained “gems” format), tools designed to easily manage the “gems” installation, and server for their distribution.

')
NOTE: Please note that it is Ruby Gems, not Rails Gems or RoR Gems !!! This means that gems are written directly on pure and brilliant Ruby , and what is marked as Rails Gem is just Ruby Gem, but using or supplementing Rails (by the way, who does not know, Rails is also Ruby Gem).

I use JetBrains IDE - RubyMine (v6.3) for development. Mainly due to convenient autocomplete and integration with Git, SFTP and other goodies. Therefore, all frauds will show it in this IDE. For followers of Sublime / Vim / Emacs + Terminal there is a bunch of instructions for generating gem templates through the console.

So, let's begin.

I am the creator, albeit still damp, but functioning heme Fobos (current v0.0.6). All the knowledge I took from the process of its development.

Step 1: Create a blank

In RubyMine, this looks like creating a new project, but with the choice of Poject Type : Ruby Gem.



Next is the choice of the Ruby version. That, in principle, is clear and does not require an explanation.

As a result, we get a project with such a structure (I removed the checkboxes to create the bin and test directories).



Consider the entire structure in order.

• lib - directly stores all the code (or almost all) of your application;
• .gitignore - stores a list of files and folders that should not be under version control (database files, compiled assets, logs, etc.);
• Gemfile, Gemfile.lock - a list of other gems that you use to work or when developing an image. But in the case of heme they are not available, because they are specified in the * .gemspec file;
• LICENSE.txt - stores the license of use. In my case, this is MIT;
• Rakefile - stores Rake Tasks. More can be easily found on the Internet;
• REAMDE, md - the "face" of your application. Displayed on the GitHub and RubyDoc start pages;
• SomeCoolGem.gemspec is a manifest that stores the main information and dependencies of the application.

Step 2: Creating a structure for the application

Now we will work directly with the lib directory.
The file SomeCoolGem.rb is the start file. In theory, it should keep all the logic, but, as practice shows, it is much more expedient to create a module and divide the application into classes according to functionality, and then simply load them into this file. For those familiar with C ++ / Java / C # languages, this file is somewhat similar to the main () method.

Immediately create a HelloWorld module. And in it we will create class Alloha.

Since the entire gem, in fact, is a module, the following code will already be in the SomeCoolGem.rb file:

require "SomeCoolGem/version" module SomeCoolGem # Your code goes here... end 

This is how the project structure has changed:



Here is the class alloha:

 module SomeCoolGem module HelloWorld class Alloha end end end 

Step 3: We do the necessary functionality

Add a field, a constructor, and some methods to the Alloha class to demonstrate:

 module SomeCoolGem module HelloWorld class Alloha attr_accessor :name def initialize(name) @name = name end def generate_alloha "Alloha, #{@name}, from SomeCoolGem!" end def say_alloha puts generate_alloha end end end end 

Step 4: We check the workability

Since a heme is a module, we can also use it as a module. For verification, I usually use IRB .

Here is an example:

 2.1.2 :001 > load 'alloha.rb' => true 2.1.2 :002 > object = SomeCoolGem::HelloWorld::Alloha.new('User') => #<SomeCoolGem::HelloWorld::Alloha:0x00000000e7f950 @name="User"> 2.1.2 :003 > object.generate_alloha => "Alloha, User, from SomeCoolGem!" 2.1.2 :004 > object.say_alloha Alloha, User, from SomeCoolGem! => nil 2.1.2 :005 > 

As you can see, not much different from the work usually project. Roughly speaking, when using a heme, your application simply connects a module with nested modules / classes and you can use them like regular Ruby modules / classes.

Step 5: Connect everything to the main file

To do this, you need to slightly modify our startup file SomeCoolGem.rb:

 require "SomeCoolGem/version" module SomeCoolGem require 'SomeCoolGem/hello_world/alloha' end 

Now, when we specify our gem in the Gemfile application, we can use it as a regular Ruby module.

Step 6: Heme Build and Versioning

The file version.rb stores the current version of our gem:

 module SomeCoolGem VERSION = "0.0.1" end 

Before each release will need to change this value.

I’ll say right away that if you make a new commit, you don’t have to change the version. However, if the program logic changes, it is better to make a release.

To compile a heme version, you need to run the command:

 gem build SomeCoolGem.gemspec 

The file SomeCoolGem-0.0.1.gem will appear in the project root.

Congratulations. The first version of the heme is collected!

Step 7: Push Heme

Detailed and fresh instruction is always here .

The same set of instructions is here .

Everything is well described there.

Step 8: Enlightenment

Now I would like to talk about some of the buns that are interesting to many.

1. You can update the heme profile on RubyGems. There are settings in which you can add a description, links, and more.
2. Badges. Badges deserve a separate small topic. But in a nutshell - these are ordinary pictures that you post to your README file. They display the status of passed tests on various services. For example, checking the purity of the code. More details can be found here .
3. README file you must compile yourself. Try to specify which versions are compatible with which or not. If global changes were made or part of the old functionality is closed, change not the minor version, but the older one, depending on the global changes.
4. Describe the quality documentation. Often it depends on her desire to use your life or not.
5. Try to implement the functionality with minimal dependencies on other gems and make sure to use the new versions in your work.

On this, perhaps, everything. Good luck to all those who begin their journey in this direction. I will be glad to criticism and clarification.

UPD:
Spend more time on * .gemspec and README files.

To edit the * .gemspec file, you can read the article here.

Also note that all gems that you use in your application must also be specified in the *. Gemspec file