Has much changed with the release of Bundler? Is there a template that can be used as a base? What are the best practices?
Some posts that I have found useful:
http://chneukirchen.github.com/rps/
http://tomayko.com/writings/require-rubygems-antipattern
http://yehudakatz.com/2009/07/24/rubygems-good-practice/
http://weblog.rubyonrails.org/2009/9/1/gem-packaging-best-practices
Edit (2012-01-10): An excellent all-around guide to gem best practices is RubyGems Guides. I would highly recommend starting here now.
To summarize the key points:
Use the basic lib/gem.rb and lib/gem/ structure for code.
Put any executables in bin, any data files in data and tests in test or spec.
Don't require or depend upon files outside of the load path. (VERSION files often seem to live in odd places in gems.)
Do not require 'rubygems'.
Do not tamper with the $LOAD_PATH.
If you find yourself writing require File.join(__FILE__, 'foo', 'bar'), you're doing it wrong.
The simplest way it's to use bundler:
bundle gem <gem_name>
You may even use it in an existing project from the parent directory.
When writing fat (binary) gems the structure is usually this:
lib/1.8/binary.so
lib/1.9/binary.so
lib/my_gem.rb (this file simply chooses which binary.so to load depending on ruby version)
And for native extensions:
lib/ext/my_gem/my_sources.*
lib/my_gem.rb
I also usually put a version.rb file here:
lib/my_gem/version.rb
and it simply contains something like:
module MyGem
VERSION = "0.1.0"
end
Also, IMO, don't put any .rb files except the file you want people to use to load the gem, in the lib/ directory. Instead put all auxiliary files in lib/my_gem/
This rubygems guide provides information about the structure of a gem and then goes into detail about what should be included in your gemspec
You may find it easier to use bundler to create the folder structure of the gem for you:
bundle gem <gem_name>
my_gem$ bundle gem my_gem
create my_gem/Gemfile
create my_gem/Rakefile
create my_gem/LICENSE.txt
create my_gem/README.md
create my_gem/.gitignore
create my_gem/my_gem.gemspec
create my_gem/lib/my_gem.rb
create my_gem/lib/my_gem/version.rb
Initializing git repo in /Users/keith/projects/my_gem/my_gem
Telemachus's advice is good. If you follow it your gem will be setup to play nicely with bundler.
You might also try using jeweler. It's a gem that generates skeletons for gems. The default skeleton that it spits out complies with all of the conventions Telemachus mentioned and it will also do some nice things like add your favorite test framework or create a GitHub repository.
Related
Basically, I'm trying to build a gem that does some form of test failure when certain dependencies are outdated. In the testing framework I can easily stub the crap out of Gem so that Gem.loaded_specs("foo") returns the spec for the gem foo. What I'm looking for is a way to provide a fixture Gemfile and then parse the lock file.
When I use Gem.loaded_specs it somehow magically knows which Gemfile to use, how do I feed it a different gemfile (ie: my fixture)?
I know somebody mentioned "use bundler" and that makes sense but in my code for the gem I do this:
gem_here = Gem.loaded_specs[gem_name]
gem_here.nil? ? :not_in_bundle : gem_here.version.to_s
I need to make this work with my fixture Gemfile and not the current projects gemfile.
Does this make any sense? Sorry if this is vague.
Note: I'm not trying to do this via the CLI. I'd like to use programmatic (ie: ruby api) methods if I can.
Edit:
I'm going with this kind of source now:
gem_here = Bundler.load.specs.detect do |specs|
specs.name == gem_name
end
gem_here.nil? ? :not_in_bundle : gem_here.version.to_s
Parsing yourself isn’t desirable as Bundler does the heavy-lifting (parsing, dependency resolution).
Bundler::LockfileParser.new(Bundler.read_file(Bundler.default_lockfile))
Then, use gemspecs and the lockfile to visit all runtime and/or development dependencies. Runtime/development deps for specific gems are available via a (currently undocumented, needs contrib) RubyGems JSON API https://api.rubygems.org/api/v2/rubygems/rails/versions/5.0.0.1.json
Note: Bundler 2.0 Gemfile.lock -> gems.locked
I'd like to develop some reusable step definitions and scenario outlines for Cucumber in Ruby.
I've scoured the Cucumber wiki but there seems to be no info on use of Cucumber with Ruby gems.
Is there support for execution of a feature from an installed Gem?
Or would a user have to manually change to the gem installation directory and explicitly referenced the feature(s) to run from there?
If I understood your question correctly, all you need is to create some lib for reusable definitions and steps, and then require this lib(or gem) in features/support/env.rb
Here is a gem does exactly the same as you need, you can use it as a reference: https://github.com/jayzes/cucumber-api-steps
Look at the features this gem provide: https://github.com/jayzes/cucumber-api-steps/blob/master/features/request.feature The gem created some reusable parts.
Turns out cucumber --help shows the way:
cucumber -r gem-name feature-name.feature
UPDATE: This doesn't work. Any other suggestions?
There is a cucumber gem which installs the binary cucumber.
Running this command, will assume default settings. This means it will look under ./features relative to the current path for files with the .feature extension. It will expect ./features/step_definitions to hold files with *_step.rb, where it will search for steps.
Edit: never mind, I misread your question and thought you wanted to know about the cucumber gem and its default paths.
I have git cloned a repo from Github, now I want to experiment with it, as in I want to poke around the code and mess with it. I've created a file test.rb that should load this gem, but I want to load my locally checked out version, what's the right way to do this?
Right now I'm just using a bunch of "require_relative 'the_gem_name/lib/file'", which feels wrong.
When you require 'foo' Ruby checks all the directories in the load path for a file foo.rb and loads the first one it finds. If no file named foo.rb is found, and you’re not using Rubygems, a LoadError is raised.
If you are using Rubygems (which is likely given that it is included in Ruby 1.9+), then instead of immediately raising a LoadError all the installed Gems are searched to see if one contains a file foo.rb. If such a Gem is found, then it is added to the load path and the file is loaded.
You can manipulate the load path yourself if you want to ensure a particular version of a library is used. Normally this isn’t something that’s recommended, but this is the kind of situation that you’d want to do it.
There are two ways of adding directories to the load path. First you can do it in the actual code, using the $LOAD_PATH (or $:) global variable:
$LOAD_PATH.unshift '/path/to/the/gems/lib/'
require 'the_gem'
Note that you normally want to add the lib dir of the gem, not the top level dir of the gem (actually this can vary depending on the actual Gem, and it’s possible to need to add more than one dir, but lib is the norm).
The other way is to use the -I command line switch to the ruby executable:
$ ruby -I/path/to/the/gems/lib/ test.rb
This way might be a bit cleaner, as normally you don’t want to be messing with the load path from inside your code, but if you’re just testing the library it probably doesn’t matter much.
Following apneadiving's suggestion in the comments, I created a Gemfile and added this line
source "http://rubygems.org"
gem 'gem_name', path: '~/path/to/gem/source/folder'
Then bundle install, and bundle exec ruby test.rb and it worked.
I'm trying to create a gem with Bundler, following this guide: http://rakeroutes.com/blog/lets-write-a-gem-part-one/. In it, it says:
I incorrectly thought after taking my first look through the gemspec
that I would need to add more require statements as I developed my
gem. That isn’t the case: the files just need to be in git.
I am trying to clean up some of my old gems to use this convention, but when I install my gem, the classes from the other files are not available. I have a couple directories nested under my /lib dir, but I wouldnt think that would be an issue. Is there anything simple to overlook that would prevent my other files from being required? Any help would be appreciated.
In the link, when he says he doesn't need to add a lot of "require" statements, he must mean adding files to the s.files, s.executables, and s.test_files arrays--these determine what files get packaged up into the gem and what files get ignored. As you can see from the gem spec, whatever's tracked by git in certain directories is going to be included in the packaged gem.
Ruby's require is a different story. Standard require rules still apply.
Ruby's gem system works by adding a bunch of different places for Ruby to look for "foo.rb" when you run require "foo". If "lib" is your only require path for your gem, when you require "my_gem" Ruby is only going to run the code in lib/my_gem.rb. If lib/my_gem.rb doesn't require any other files in your gem, then Ruby hasn't seen them and so you'll get undefined constant errors when you try to use the classes from those files.
For examples, you might take a look at two simple gems I've written; both were started with bundle gem: HashToHiddenFields and SimpleStats. In both gems, main Ruby file in lib/ requires everything that needs to be loaded for the gem to work correctly. For example, hash_to_hidden_fields.rb requires action_view/helpers/hash_to_hidden_fields so that the ActionView::Helpers::HashToHiddenFields constant+module exists so we can include it into ActionView::Base.
Hope that answers the question. I know Ruby requiring was pretty fuzzy to me for a while.
With Jeweler I created a gem folder structure with ease.
However, I still have some questions:
Why are params like --gemcutter and --rubyforge still available for Jeweler. Aren't these replaced by RubyGems? Do I have to specify anything to create a gem for RubyGems?
In the Rakefile I have information about the gem, and when I run "rake install" it created a gemspec. Why is the same information in two places?
What is a manifest? Just read about it, haven't seen such file.
How do I make my gem callable from the shell once I have installed it, like rails. Cause right now it's just accessible through a Ruby script using require.
Should I use "jeweler release" or "gem push" to push my gem to RubyGems.org?
I have to specify "handle" when signing up in RubyGems. What is that?
Thanks.
jeweler was created before RubyGems became what it is, so it still reflects the split. I'm not sure when jeweler was last updated, either. (I think it also still recognizes building gems on Github, which is now disabled.)
I'm not sure I follow what you're saying. The specification in the Rakefile details what the spec that gets written should look like. The spec that gets written details what should be installed and how, I believe.
A manifest is a list of all the files that your gem should ship with. Not everyone uses one. See the hoe documentation for some pro-manifest discussion.
Many Ruby gems are only libraries. If you want yours to also have a program like jeweler or rake or rails that you can call, you have to write the callable program, put it in bin in your gem's layout and specify (in your gemspec) that it should be packaged and installed. See the Gem::Specification reference under files and executable.
Not sure. Consult both jeweler's docs and the docs for RubyGems.
You can give an email address or use a name (a 'handle', like I use Telemachus here), which is all they mean by 'handle'.
For the record, if you are just learning how to write gems, you do not need to upload your first attempts using RubyGems or anything like it. You can simply install the gem on your machine only.