Creating Gems - Guide

Although on Habré already articles about creating gems have already skipped, they either contain outdated or incomplete information.

How do you really need to create, develop and publish your gems?

A modern approach is to use the Bundler with other tools, such as Git, YARD and RSpec-2 .
')

Creating a basic structure

So, to create a new gem, just run the command

bundle gem YOUR-GEM-NAME 

Naturally, you must have already installed the bundler gem install bundler ( gem install bundler ) before executing this command.

After this, you will receive the basic structure of your new gem in the YOUR-GEM-NAME catalog with ready-made commands for geme construction, its installation and publication in rubygems:

 cd YOUR-GEM-NAME rake -T rake build # Build YOUR-GEM-NAME-0.0.1.gem into the pkg directory rake install # Build and install YOUR-GEM-NAME-0.0.1.gem into system gems rake release # Create tag v0.0.1 and build and push YOUR-GEM-NAME-0.0.1.gem to Ru... 

It is important to note that the source library code should not litter the global namespace. Please place all your classes inside a class or module with the name suggested by Bundler in the lib / YOUR-GEM-NAME subdirectory, including them from the file lib / YOUR-GEM-NAME .rb. Avoid using autoload, as this feature has been deprecated for Ruby 2.0.

Whenever possible, all documentation files should use Markdown markup (preferably having a README.md file).

Documenting code

A modern tool for documenting code is the YARD in markdown mode using the redcarpet module to support code highlighting using GitHub syntax. In this case, you automatically receive the publication of documentation on rubydoc.info ( example ).

Connecting it is quite simple:

• Add development time dependency to gemspec:
  

    s.add_development_dependency "redcarpet", "~> 1.17" s.add_development_dependency "yard", "~> 0.7.5" 

  
  If you use ruby ​​version 1.8, then it is also advisable to use the gem ripper, which will add useful functionality for YARD. Connect it better through a gemfile:
  

   gem "ripper", :platforms => :ruby_18, :group => :development 

  
  
• We perform the installation of gems
  

   bundle install 

  
  
• Customize YARD by creating a .yardopts file with these contents:
  

   --markup markdown
   --markup-provider redcarpet
   --charset utf-8
   - readme README.md
   -
   README.md
   LICENSE
  

  
  Here, after a single-line hyphen, we indicate a list of files that must be additionally included in the documentation (usually a readme and license).
  
• And add the rake yard task to generate the documentation in the Rakefile:
  

   require 'yard' YARD::Rake::YardocTask.new 

  
  

Now, using the rake yard command, we will receive the complete library documentation in the doc directory.

By the way, do not forget to add doc /, .yardoc / and Gemfile.lock to .gitignore.

We start writing specs

Personally, I prefer to use for specs RSpec 2 together with RR . Add the appropriate dependencies to gemspec:

  s.add_development_dependency "rspec-core", "~> 2.0" s.add_development_dependency "rspec-expectations", "~> 2.0" s.add_development_dependency "rr", "~> 1.0" 

Install gems and create basic RSpec 2 files

 bundle install bundle exec rspec --init 

Add the rake spec task to the rakefile:

 require 'rspec/core/rake_task' RSpec::Core::RakeTask.new 

And please use the default RR in spec / spec_helper.rb:

  config.mock_with :rr 

Everything, now you can write specs and code.

Little about executables

The files that you put into the bin directory of your gem are installed as executable files of the target operating system during gem installation.

There is a small nuance here: in different operating systems, this installation occurs in different ways, and sometimes your executable files are not run from the bin subdirectory of your heme, which you could accidentally tune into.

In this regard, the best practice when creating an executable file is to transfer all the logic to the library so that the binary file of your-gem-exec would look like this somewhere:

 require 'rubygems' #    ruby 1.9   require 'your-gem' require 'your-gem/exec' 

In addition, this approach means that most of the logic can be covered with specs.

Version control

The general rule is to use Git as a repository and semantic versioning when generating gem version numbers. rake release will automatically create the necessary tags in the repository and publish the gems in rubygems.

Removing erroneous versions of gems

Sometimes there is a task to delete any version of the heme with rubygems due to problems of a specific version (errors in the code or incorrect versioning). This task is performed using the command

 gem yank gemname -v version 

This command does not come with rubygems by default, so you need to install a jeweler gem to use it.

 gem install jeweler