This is a trivial example of how to make a gem
-
Install “echoe” gem:
gem install echoe
Build a structure like the one here:
. |--README.rdoc |--Rakefile `--lib `--uniquify.rb
The “Rakefile” is very important:
$ cat Rakefile # http://railscasts.com/episodes/135-making-a-gem require "rubygems" require "rake" require "echoe" Echoe.new('uniquify', '0.1.0') do |p| p.description = "Generate a unique token with Active Record." p.url = "http://github.com/crguezl/uniquify" p.author = "Casiano Rodriguez-Leon" p.email = "[email protected]" p.ignore_pattern = ["tmp/*", "script/*"] p.development_dependencies = [] end Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }
-
$ rake manifest
Cleaning Building Manifest + Manifest + README.rdoc + Rakefile + lib/uniquify.rb
Once we have built the "Manifest" we can see the available tasks: $ rake -T rake announce # Generate a release announcement, edit it, and post it to Rubyforge. rake build # Generates manifest & gemspec in one go rake build_gemspec # Builds the .gemspec rake clean # Remove any temporary products. rake clobber # Remove any generated file. rake clobber_docs # Remove RDoc HTML files rake clobber_package # Remove package products rake console # Start an irb session and load the library. rake details # Display Echoe's knowledge of your system rake docs # Build RDoc HTML files rake gem # Build the gem file uniquify-0.1.0.gem rake install # Install the gem rake install:development # Install the gem including development dependencies rake manifest # Build a Manifest list rake package # Build all the packages rake prerelease # Override this task to add prerelease checks rake publish_docs # Publish documentation to the internet. rake redocs # Rebuild RDoc HTML files rake release # Package and upload the release to Gemcutter rake repackage # Force a rebuild of the package files rake uninstall # Uninstall the gem
-
Now we can install the gem:
$ rake install Cleaning - pkg rm -rf pkg Gemspec generated mkdir -p pkg mkdir -p pkg/uniquify-0.1.0 rm -f pkg/uniquify-0.1.0/README.rdoc ln README.rdoc pkg/uniquify-0.1.0/README.rdoc rm -f pkg/uniquify-0.1.0/Rakefile ln Rakefile pkg/uniquify-0.1.0/Rakefile mkdir -p pkg/uniquify-0.1.0/lib rm -f pkg/uniquify-0.1.0/lib/uniquify.rb ln lib/uniquify.rb pkg/uniquify-0.1.0/lib/uniquify.rb rm -f pkg/uniquify-0.1.0/Manifest ln Manifest pkg/uniquify-0.1.0/Manifest rm -f pkg/uniquify-0.1.0/uniquify.gemspec ln uniquify.gemspec pkg/uniquify-0.1.0/uniquify.gemspec cd pkg tar zcvf uniquify-0.1.0.tar.gz uniquify-0.1.0 a uniquify-0.1.0 a uniquify-0.1.0/lib a uniquify-0.1.0/Manifest a uniquify-0.1.0/Rakefile a uniquify-0.1.0/README.rdoc a uniquify-0.1.0/uniquify.gemspec a uniquify-0.1.0/lib/uniquify.rb cd - cd pkg/uniquify-0.1.0 WARNING: description and summary are identical mv uniquify-0.1.0.gem .. cd - Private key not found; gem will not be signed. Targeting "ruby" platform. Password: Successfully uninstalled uniquify-0.1.0 Successfully installed uniquify-0.1.0 1 gem installed Installing ri documentation for uniquify-0.1.0... Installing RDoc documentation for uniquify-0.1.0...
-
This is the tree after “rake install”
$ tree . |--Manifest |--README.rdoc |--Rakefile |--lib | `--uniquify.rb `--pkg |--uniquify-0.1.0 | |--Manifest | |--README.rdoc | |--Rakefile | |--lib | | `--uniquify.rb | `--uniquify.gemspec |--uniquify-0.1.0.gem `--uniquify-0.1.0.tar.gz
-
Now we can use the just installed gem:
$ irb ruby-1.9.2-p290 :001 > require "uniquify" => true ruby-1.9.2-p290 :002 > Uniquify.new.hello Hello World! => nil
-
Let us use control version:
$ git init Initialized empty Git repository in /Users/casianorodriguezleon/Dropbox/src/gemwithechoe/uniquify/.git/
-
We decided for git to ignore some files
$ vi .gitignore $ cat .gitignore pkg doc Manifest
-
Let us add the files to the rep:
git add . git status -s A .gitignore A README.rdoc A Rakefile A lib/uniquify.rb
-
And commit them:
$ git commit -m 'initial repository' [master (root-commit) 7b0ff4e] initial repository 4 files changed, 190 insertions(+), 0 deletions(-) create mode 100644 .gitignore create mode 100644 README.rdoc create mode 100644 Rakefile create mode 100644 lib/uniquify.rb
-
Build a repository in GitHub using GitHub web interface (www.github.com). I built:
https://github.com/crguezl/gemexample
-
Set github rep as remote of the local rep:
$ git remote add origin [email protected]:crguezl/gemexample.git $ git remote -v [email protected]:crguezl/gemexample.git (fetch) [email protected]:crguezl/gemexample.git (push)
-
Push your changes upstream to the remote:
$ git push -u origin master Counting objects: 7, done. Delta compression using up to 2 threads. Compressing objects: 100% (5/5), done. Writing objects: 100% (7/7), 2.47 KiB, done. Total 7 (delta 0), reused 0 (delta 0) To [email protected]:crguezl/gemexample.git * [new branch] master -> master Branch master set up to track remote branch master from origin.
-
Point your browser to your github rep (github.com/crguezl/gemexample). The files must be there.
-
Build a gemspec:
$ rake build_gemspec Gemspec generated
This creates a uniquify.gemspec file:
$ ls -ltr total 40 drwxrwxr-x 3 casianorodriguezleon staff 102 5 jun 20:43 lib -rw-rw-r– 2 casianorodriguezleon staff 46 5 jun 20:48 Manifest -rw-rw-r– 2 casianorodriguezleon staff 497 5 jun 21:07 Rakefile drwxrwxr-x 5 casianorodriguezleon staff 170 5 jun 21:13 pkg -rw-rw-r– 2 casianorodriguezleon staff 7914 5 jun 22:10 README.rdoc -rw-rw-r– 1 casianorodriguezleon staff 1020 5 jun 22:19 uniquify.gemspec
With the following contents:
$ cat uniquify.gemspec # -*- encoding: utf-8 -*-
Gem::Specification.new do |s|
s.name = "uniquify" s.version = "0.1.0" s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version= s.authors = ["Casiano Rodriguez-Leon"] s.date = "2012-06-05" s.description = "Generate a unique token with Active Record." s.email = "[email protected]" s.extra_rdoc_files = ["README.rdoc", "lib/uniquify.rb"] s.files = ["README.rdoc", "Rakefile", "lib/uniquify.rb", "Manifest", "uniquify.gemspec"] s.homepage = "http://github.com/crguezl/uniquify" s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Uniquify", "--main", "README.rdoc"] s.require_paths = ["lib"] s.rubyforge_project = "uniquify" s.rubygems_version = "1.8.10" s.summary = "Generate a unique token with Active Record." if s.respond_to? :specification_version then s.specification_version = 3 if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then else end else end
end
-
Add the gemspec to the rep:
$ git add . $ git status -s M README.rdoc A uniquify.gemspec $ git commit -m 'adding gemspec file' [master accfc87] adding gemspec file 2 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 uniquify.gemspec $ git push Counting objects: 6, done. Delta compression using up to 2 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (4/4), 2.13 KiB, done. Total 4 (delta 2), reused 0 (delta 0) To [email protected]:crguezl/gemexample.git 7b0ff4e..accfc87 master -> master
-
Now the project can be used as a gem if you download the project
from github:
$ gem build uniquify.gemspec WARNING: description and summary are identical Successfully built RubyGem Name: uniquify Version: 0.1.0 File: uniquify-0.1.0.gem $ ls -l uniquify-0.1.0.gem -rw-rw-r-- 1 casianorodriguezleon staff 6656 5 jun 22:37 uniquify-0.1.0.gem $ gem install uniquify-0.1.0.gem Successfully installed uniquify-0.1.0 1 gem installed Installing ri documentation for uniquify-0.1.0... Installing RDoc documentation for uniquify-0.1.0...
* Ruby 1.8.x or later.
gem install: $ gem install uniquify
* RailCasts: Ruby on Rails Screencasts. "Making a Gem". Episode #135 Nov 10, 200. 9 minutes URL: http://railscasts.com/episodes/135-making-a-gem
Uniquify is distributed under the terms of the GNU Lesser General Public License version 2.
Any kind of bug reports are welcome. If you find a bug , please email me. Casiano Rodriguez-Leon [email protected] http://gplus.to/casiano