What is the canonical mechanism for creating a Ruby gem? - ruby

I've looked in a lot of places - including www.rubygems.org - but can't find any tutorial that describes an easy, straightforward, technique for producing gems that doesn't rely on other (non-standard-Ruby) components, such as newgem and hoe.
I have several requirements for gem production, from the simplest case of one library file+one test file, to complex ones involving C source files and multiple utility .rb files.
All help gratefully received!

I was researching gem making recently and was also surprised that there wasn't a single, obvious way that everyone does it like how RubyGems is the one-stop shop for managing gems. I discovered that you can actually use Bundler to create gems, and I've chosen this route for my own gems. Take a look at this guide on gem development with Bundler by Radar.

look into Jeweler or one of these options:
http://ruby-toolbox.com/categories/gem_creation.html
its seems like overkill, but you don't need to use all the options, you can use it just to create the skeleton of the gem.

I've recently been looking into the same thing. Here are a few sources I found useful Walk through of a simple gem, Gem spec reference. Also I found it useful to check out large projects on github and model after them Thor's Gem spec.

Don't know if you've seen "Gemcutter Is The New Official Default RubyGem Host", but it's a good starting point. RubyGems.org is a good second stop to read Creating Your Own Gem.

Related

Ruby Project VS Ruby Gem

I have read through Q&A/articles that explain the ideal structure of a Ruby project. I read the RubyGems guides on how to create a Ruby gem. I have just read a Q&A asking at what point a ruby project becomes a ruby gem but I can not for the life of me see the difference between the two. The structure seems to be the same. The files, where they go, everything looks the same to me. Is it how they're used? Can someone please explain the difference between the two to me?
The question that must be answered respect to 'Gemify' or not is: am I writing something that is readily reusable in a different context? If the answer is yes then your application is a candidate for 'Gemification'. If not then generally it is not worth the additional complexity to convert a Ruby project into a Gem.
For example. If one makes a CLI Ruby application that collects mortgage rates from multiple vendors and updates a database then there are two ways this could be converted into a gem.
First: You could generalise the interface/configuration and make it useful as a plugin/add-on/extension to projects written by someone needing the same or similar functionality. So someone could add the gemified version to their project and use it to do the grunt work for them and just make use of the results. This describes the most common use case for gems.
Second: However, you could also extract the framework of your CLI project layout into a generator gem for others to easily create their own CLI project layouts. This is how Rails came to be.

Getting newer gems

I'm really just a beginner to ruby, so hopefully this is an easy one. I've got to the point where I'm starting to look into some of the gems that the community have put together. I decided to check out something that would help my application consume rss feeds. So, headed over to rubygems (which is where i thought people go to get these kinds of things) and searched for rss. I found this one;
http://rubygems.org/gems/simple-rss
instructions were to just install the gem with
gem install simple-rss
So far, so good. When i came to actually use the gem, the documentation I received from doing the above was a bit naff, so i searched a bit further and found the git repo;
https://github.com/cardmagic/simple-rss
The documentation there (their code examples) complain about missing methods etc. and after a bit of digging I came to the conclusion that I must have downloaded an older version of the gem than the git trunk.
So, my question is, should I be using rubygems to get the latest gems, and if not, what other resources are out there to help find the latest builds of the comminities gems?
As far as finding a good gem for a task — use Ruby Toolbox, since it also shows you how actively maintained a gem is. Here's, for example, a section on feed parsing.
If you want to get the latest gem code that hasn't been released yet, you could download the code directly from github and build the gem yourself. However, it's easier to use bundler for that. It allows you to create a Gemfile for your project looking something like the following.
gem 'simple_rss', :git => "git://github.com/cardmagic/simple-rss.git"
Then run bundle command to download and build these gems from their corresponding sources.
In general, bundler is a great solution for managing gem dependencies for any ruby project. It provides ways to quickly reference any released gems, automatically builds gems directly from a git source, git refs, or paths on your filesystem, and has other convenient features.
By far the best place for all things Ruby & Ruby on Rails for the devs is the Ruby Toolbox

Where to find the Rails API rdoc template

I'm trying to prettify my rdoc documentation, using version 3.5.3. I'm not a fan of the built-in darkfish theme, so I tried to find a way to replace it with the one used by the official Rails API documentation at http://api.rubyonrails.org/, but I've had no luck finding it in any readily available form. I've searched all over github, among other things.
What I've found so far is
https://github.com/mislav/hanna
which might be slightly out of date, and it's fork
https://github.com/rdoc/hanna-nouveau
Both are nice, but not quite what I want. So before I start fiddling with those templates, does anyone know if the template used by the Rails API docs is available as a gem somewhere?
Thanks!
I know this is very late, but it looks like the new version of Rails uses something called sdoc, which enhances the output with JavaScript searching, and is a little cleaner IMO. Doing a simple "gem install sdoc" will get what you need, then just use rdoc.options << '-f' << 'sdoc'.
The github project appears to be at https://github.com/voloko/sdoc/
By the way, thanks for the question! Without the initial answer posted, I'd have never found where to look, and been stuck with that horrible darkfish theme for my own projects!
This looks like it. Ignore the instructions that say to do a gem install horo --pre -- that'll actually give you an older beta version. Just do gem install horo and you'll get the current 1.0.3 version (Edit: I sent a pull request to update the instructions, which has already been accepted).
https://github.com/tenderlove/horo
By the way, I found this by looking at the Rails source code and viewing the Rakefile to see the RDoc options. Specifically, line 67 shows rdoc.options << '-f' << 'horo'.

Which resource did you find to be the most helpful when making a gem?

Hey, seems to be a few questions on SO about making a ruby gem. I'm interested in those of you that have actually built gems, hoping for Rails3, and your experiences with resources that you have used to make a gem.
My question is the title: Which resource did you find to be the most helpful when making a gem?
Jeweler is an awesome tool that does most of the packaging / gem layout work for you. I've used it in every gem I've made.
I found that intro quite useful to get started:
http://buzaz.com/index.php/2010/01/03/how-to-build-a-ruby-gem/
You could also have a look at this Railscast:
http://railscasts.com/episodes/135-making-a-gem

Discovering capabilities of Ruby gem

The Ruby (and RoR) community publishes a large number of gems. But more often than not using these gems requires a good amount of effort, specially if one is new to Ruby. It would to be nice if Ruby experts (rockstars) share the best approaches to utilize inadequately documented gems.
Thanks
--arsh
As my manager likes to say:
The truth is in the code.
Look for examples of how others have used it, and modify as necessary.
There are frequently example directories in gems
Search the internet, people like to put this stuff in blogs
Read the docs.
Maybe posted on github
Frequently a link from the rubygems page
If installed as a gem, you can host your own server with $ gem server then go to localhost:8808 to get a list of all your installed gems, and you click the one you are interested in to see its documentation.
Look for tutorials that cover the gem
Railscasts are great for this
Many gems will have a wiki on github
Many of the more useful / cool / fun gems will be talked about in different books. You can get a lot of tutorials about how to deal with a given gem by getting a book that uses that gem to do something. The downside of this is that these kinds of books tend to go out of date pretty quickly.
Look at the code
If the code base is small, or you have a specific question about how something works, or want the truly definitive source, go check out the code.
If the code is installed as a gem, you can type $ gem environment and it will tell you your rubygems dir. Go there, cd into the gem you are interested in, check out its code in the lib directory.
Ask a mailing list
If a gem or project is large enough, it will have its own mailing list. You can usually find these by going to its homepage or reading its readme.
If not, try asking about the gem on the Ruby or the Ruby on Rails mailing lists.
You can always give your own gems a rockstar promotion. Vimeo: Zombie-chaser version 0.1: Mutation testing ... with zombies!

Resources