Permalink
Browse files

fill out what is a gem guide

  • Loading branch information...
1 parent 6a4d91f commit 096bbec4ddee69a05f5899f6d48f9914b41593b1 @qrush qrush committed Apr 28, 2011
Showing with 123 additions and 28 deletions.
  1. +1 −1 index.md
  2. +5 −0 stylesheets/screen.css
  3. +9 −0 stylesheets/screen.scss
  4. +108 −27 what-is-a-gem.md
View
2 index.md
@@ -3,7 +3,7 @@ layout: home
---
[What is a gem?](/what-is-a-gem)
----------------
+--------------------------------
Unpack the mystery behind what's in a RubyGem.
View
5 stylesheets/screen.css
@@ -696,6 +696,11 @@ body.home {
color: #fff;
padding: 10px;
font-family: Courier, Sans-serif; }
+ #container #content pre code {
+ background: #333; }
+ #container #content code {
+ background: #eee;
+ padding: 2px; }
#container #content ul, #container #content ol {
padding-top: 10px;
margin-left: 30px;
View
9 stylesheets/screen.scss
@@ -173,6 +173,15 @@ body.home {
color: #fff;
padding: 10px;
font-family: Courier, Sans-serif;
+
+ code {
+ background: #333;
+ }
+ }
+
+ code {
+ background: #eee;
+ padding: 2px;
}
ul, ol {
View
135 what-is-a-gem.md
@@ -44,46 +44,127 @@ Gems contain three components:
Each gem follows the same standard structure of code organization:
-<pre><code>% tree
-awesome/
-|-- lib/
-| `-- awesome.rb
-|-- test/
-| `-- test_awesome.rb
-|-- README
-|-- Rakefile
-`-- awesome.gemspec
-</code></pre>
+ % tree freewill
+ freewill/
+ |-- bin/
+ | `-- freewill
+ |-- lib/
+ | `-- freewill.rb
+ |-- test/
+ | `-- test_freewill.rb
+ |-- README
+ |-- Rakefile
+ `-- freewill.gemspec
Here, we see the 3 major components: code, in the `lib` directory, hopefully
-along with some tests as well. Tests usually appear in `test` or `spec`,
-depending on the test framework used. A gem usually has a `Rakefile`, which the
+along with some tests as well. Tests appear in `test` or `spec`, depending on
+the test framework used. A gem usually has a `Rakefile`, which the
[rake](http://rake.rubyforge.org/) program uses to help automate running tests,
-generating code, and more.
+generating code, and more. This gem also includes an executable file in the
+`bin` directory, which will loaded onto your `PATH` once installed.
Documentation is usually included in the `README` and inline with the code. When
you install a gem, documentation is generated automatically for you. Most gems
include [RDoc](http://rdoc.sourceforge.net/doc/) documentation, but
[YARD](http://yardoc.org/) docs are also nice as well.
The final piece is the gemspec, which contains information about the gem. The
-gem's author, email, name, along with the gem's files, test information,
-platform, version number and more are all laid out here. The full [Specification
-Reference](http://guides.rubygems.org/specification-reference) goes over each
-metadata field in detail.
-
-Loading code
--------------------
-
-explain how code gets loaded
+gem's files, test information, platform, version number and more are all laid
+out here along with the author's email and name.
+
+Gem structure
+-------------
+
+RubyGems manages your Ruby load path, or how your Ruby code is found
+by the `require` statement. When you `require` a gem, really you’re just placing
+that gem’s `lib` directory onto your `$LOAD_PATH`. Let’s try this out in `irb` and get
+some help from the `pretty_print` library included with Ruby. Passing `-r` to
+`irb` will automatically require a library when loaded.
+
+ % irb -rpp
+ >> pp $LOAD_PATH
+ [".../lib/ruby/site_ruby/1.8",
+ ".../lib/ruby/site_ruby",
+ ".../lib/ruby/vendor_ruby/1.8",
+ ".../lib/ruby/vendor_ruby",
+ ".../lib/ruby/1.8",
+ "."]
+
+By default we have just a few system directories on our load path and the Ruby
+standard libraries. If we were to run `require 'rake'` right now, it would fail,
+because RubyGems isn’t loaded yet.
+
+ % irb -rpp
+ >> require 'rake'
+ LoadError: no such file to load -- rake
+ from (irb):2:in `require'
+ from (irb):2
+ >> require 'rubygems'
+ => true
+ >> require 'rake'
+ => true
+ >> pp $LOAD_PATH[0..1]
+ [".../gems/rake-0.8.7/bin",
+ ".../gems/rake-0.8.7/lib"]
+
+Once we’ve required rake, then RubyGems automatically drops the `bin` and
+`lib` directories onto the `$LOAD_PATH`. The `bin` directory is used for
+creating executables that use your gem’s code, such as `rake`. These are
+completely optional and you could have multiple per gem if you wanted.
+
+That’s basically it for what’s in a gem. Drop Ruby code into `lib`, name a
+Ruby file the same as your gem (so for freewill, `freewill.rb`) and it’s loaded
+by RubyGems.
+
+The `lib` directory normally contains only one `.rb` file on the top directory,
+and then another folder with the same name as the gem with more code in it. For
+example:
+
+ % tree freewill/
+ freewill/
+ |-- lib/
+ | |-- freewill/
+ | | |-- core_ext/
+ | | | |-- array.rb
+ | | | `-- string.rb
+ | | |-- user.rb
+ | | |-- widget.rb
+ | | `-- ...
+ | |-- freewill.rb
The Gemspec
--------------------
-
-brief detail about a gemspec
+-----------
+
+Your application, your gem's users, and you 6 months from now need to know who
+wrote a gem, when, and what it does. The gemspec tells you this information and
+is your guide to understanding what a gem contains for you. Many developers
+generate these files from build tools like [Hoe](http://seattlerb.rubyforge.org/hoe/),
+[Jeweler](https://github.com/technicalpickles/jeweler), or just plain old
+[Rake](http://rake.rubyforge.org/classes/Rake/GemPackageTask.html).
+
+Here's an example of one. The next tutorial covers [how to make a
+gem](/make-your-own-gem).
+
+ % cat freewill.gemspec
+ Gem::Specification.new do |s|
+ s.name = 'freewill'
+ s.version = '1.0.0'
+ s.date = '2010-04-27'
+ s.summary = "Freewill!"
+ s.description = "I will choose Freewill!"
+ s.authors = ["Nick Quaranto"]
+ s.email = 'nick@quaran.to'
+ s.homepage = 'http://example.com'
+ s.files = ["lib/freewill.rb"]
+ end
+
+For more information on the gemspec, please check out the full [Specification
+Reference](http://guides.rubygems.org/specification-reference) which goes over
+each metadata field in detail.
Credits
-------------------
+-------
This guide was adapted from [Gonçalo Silva](https://twitter.com/#!/goncalossilva)'s
-original tutorial on docs.rubygems.org.
+original tutorial on docs.rubygems.org and from [Gem Sawyer,
+Modern Day Ruby Warrior](http://rubylearning.com/blog/2010/10/06/gem-sawyer-modern-day-ruby-warrior/).

0 comments on commit 096bbec

Please sign in to comment.