When we run the bundle gem new_gem command, a directory is created with those files:
create new_gem/Gemfile
create new_gem/Rakefile
create new_gem/.gitignore
create new_gem/new_gem.gemspec
create new_gem/lib/new_gem.rb
create new_gem/lib/new_gem/version.rb
By default, the file new_gem/lib/new_gem.rb is a module named NewGem.
My question is the following: how can I do if NewGem is a class? Rather then having NewGem::NewGem, I would like to just define this class (without a root module).
I tried to just replace module by class inside this file, and then make a local gem in order to test it, but after its installation, I can not load it in IRB (with require 'new_gem').
Thanks for your help.
You should ask yourself why you want to do this. The module is there to namespace your gem's code. Typically to provide a context for all the classes within, but even in a single class gem, this would help to provide conflicts with other code out in the world.
Unless your class is named SomethingThatCouldNeverPossiblyBeDefinedAnywhereElse, leaving that module in place is probably a good thing. And regardless of that, leaving the module intact is still a good thing as it's the convention, and what people expect when examining/using your code.
With that in mind, there are a few things you'd need to do if you wanted a single class gem.
The generated gemspec wants to require 'new_gem/version' to find it's version number. Change that to simply require 'new_gem'.
The gemspec also lists its contained files using git ls, and the generated gem package already has new_gem/version included in the pre-built git repo. Remove this:
git rm lib/new_gem/version.rb
Change your new_gem module to a class, as you did previously.
Remove the generated version.rb require from your class, and instead define the version there, e.g.:
class NewGem
VERSION = '0.0.1'
end
Finally install the gem via rake install. You won't be able to load it in IRB until you've done this.
Related
Try creating a gem based on bundler's official guide on developing a Ruby gem.
Running bundle gem foodie will create a structure and generate files in the lib directory:
foodie
version.rb
foodie.rb
foodie.rb reads
require "foodie/version"
module Foodie
# Your code goes here...
end
Running ruby lib/foodie.rb (or also from different directories) will result in
C:/Ruby23-x64/lib/ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require': cannot load such file -- foodie/versio
n (LoadError)
from C:/Ruby23-x64/lib/ruby/2.3.0/rubygems/core_ext/kernel_require.rb:55:in `require'
from foodie.rb:1:in `<main>'
On the other hand installing the gem via rake install and then requiring the gem works just fine.
It works from source if require "foodie/version" is changed to require_relative "foodie/version" in foodie.rb. As I understand
require works based on modules
require_relative works based on directory structure
To me the latter looks like a hack. It'd no longer make sense to structure your code via modules as it wouldn't be enforced (maybe it'd still make sense but you could make mistakes and never notice).
My questions are:
Is it possible to test a gem from source without installing it while following the bundler convention (using require instead of require_relative)?
Why does the gem work after installed?
Is there any best practice for the usage of require, require_relative, modules, files and general structure?
Thank you.
You need to add your lib dir to Ruby’s load path. The load path is a list of directories that Ruby searches for files in when you call require. Rubygems also manages the load path when you are using gems, which is why your code works when installed as a gem.
You say “as I understand ... require works based on modules”, this is not correct. require works with files, it’s just convention that a class or module is defined in a file with a matching name, e.g. MyModule might be in my_module.rb.
There are a few ways to add a dir to the load path. From the command line you can use the -I option:
$ ruby -I lib lib/foodie.rb
If you wanted to avoid typing -I lib you could use the RUBYLIB environment variable. Ruby adds the contents of this to the load path:
$ export RUBYLIB=lib
$ ruby lib/foodie.rb
(On Windows I think you will need to use set rather than export.)
You can also manipulate the load path from withing the program itself. It is stored in the global variable $LOAD_PATH, aliased as :$. This is how Rubygems and Bundler manage your gems.
I am creating a gem where I'd like to define some constants to be available.
In my actual gemspec, I added the following:
config = File.expand_path('../config', __FILE__)
$LOAD_PATH.unshift(config) unless $LOAD_PATH.include?(config)
require 'constants.rb'
In constants.rb I have a simple var defined: $FOO = "Hello, World!"
Then in my lib/gem_name/core.rb, I'm attempting to puts $FOO but it doesn't seem to be available. No error, just comes up blank. Am I not understanding how gem dependencies and the require tree works here?
** UPDATE **
I have also tried just adding a config directory directly underneath lib which is in the LOAD_PATH already. then in my library, I am attempting to require config/constants, but that's saying it cannot load such a file.
I have also tried just moving constants.rb to the lib directory directly and requiring that, and it's warning me that it cannot load such file. Something is terribly wonky.
According to Katz,
When your gem is built, Rubygems will run that code and create a static representation. This means it’s fine to pull your gem’s version or other shared details out of your library itself. Do not, however, use other libraries or dependencies.
That means that require 'constants.rb' and $LOAD_PATH.unshift(...) etc are run when you build the gem. At runtime, it doesn't change the $LOAD_PATH or cause a global require. Use gem.require_paths instead to modify $LOAD_PATH at runtime.
For example, in your gemspec, use
gem.files += Dir['config/**/*']
gem.require_paths = %w[lib config]
Then in places where $FOO is required, use
require 'constants'
Side Notes
You don't need to include the .rb extension when using require.
Make sure all the files you need are in gem.files.
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.
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.