h1. New Gem Generator
h1. newgem
h2. What
Quickly bundle any Ruby libraries into a RubyGem and share it with the world, your colleagues, or perhaps just with yourself amongst your projects.
RubyGems are centrally stored, versioned, and support dependencies between other gems, so they are the ultimate way to bundle libraries, executables, associated tests, examples, and more.
Within this gem, you get one thing - newgem - an executable to create your own gems. Your new gems will include designated folders for Ruby code, test files, executables, and even a default website page for you to explain your project, and which instantly uploads to RubyForge website (which looks just like this one by default)
h2. Installing
The newgem application is distributed itself as a RubyGem and is available immediately after installation.
<pre syntax=“ruby”>sudo gem install newgem</pre>
Alternately, download the gem and install manually.
h2. The basics
Go to the folder where you want to create your new gem folder structure, and run the newgem command to generate your gem scaffolding.
<pre>$ cd ~/ruby_projects $ newgem wizzo
create create doc create lib create script create tasks create lib/wizzo create History.txt create Rakefile create README.rdoc create PostInstall.txt create lib/wizzo.rb dependency install_test_unit create test create test/test_helper.rb create test/test_wizzo.rb dependency install_website create website/javascripts create website/stylesheets create config exists script exists tasks create website/index.txt create website/index.html create config/website.yml.sample create script/txt2html dependency plain_theme exists website/javascripts exists website/stylesheets create website/template.html.erb create website/stylesheets/screen.css create website/javascripts/rounded_corners_lite.inc.js dependency install_rubigen_scripts exists script create script/generate create script/destroy create script/console create Manifest.txt readme readme
Important
Open Rakefile
Update missing details (gem description, dependent gems, etc.)</pre>
You can generate test::unit or rspec test stubs via the -T or --test-with options. For example, -T rspec generates a spec folder with some test stubs.
h3. Setup
Now modify the constants at the top of config/hoe.rb, with your name, email and the location where you’ll host your website for the gem. The defaults are tied to RubyForge for uploading the gems and the website (see below).
h3. Create code and tests
Then create your libraries (files in lib) and your tests (files in test that look like test_TESTNAME.rb). “James Edward Gray II”:blog.grayproductions.net/ did a “nice video”:macromates.com/screencasts on test-driven design, that’s worth watching if TDD is new to you.
If you create any new files, you need to manually add them to the Manifest.txt. Alphabetical order is optional, but it will make the results of rake check_manifest look clean if you keep them ordered. If a file is not in the Manifest.txt it will not be included in the gem when you package and release it.
h3. Executables
You can include executable Ruby applications in your gem, which will be accessible on Windows and Unix/Linux/MacOS, by creating scripts in the bin folder. When the gem is deployed by users, these executables will be automatically placed within their path.
h3. Website
The final step before releasing your gem to the world is the all-important website. Edit the file website/index.txt using Textile/Redcloth syntax. Syntax highlighting is also supported (see below). If you need more website pages, create more txt files in the website folder.
Run the rake task rake website_generate to convert all your website txt files into html files.
NOTE: Currently, the initial index.txt file includes my details not yours. Currently you need to change this manually.
If you don’t want a website, remove the website related files from the Manifest.txt.
h3. Change the gems version number
The version number is set in the file lib/#gem name#.rb. Update it as appropriate with major, minor and bug fix numbers. This value will be used when generating your website, for example.
h3. Check the manifest
<blockquote>Manifest: a customs document listing the contents put on a ship or plane.</blockquote> <cite>“Google - define:manifest”:www.google.com/search?q=define%3Amanifest>
Similarly here, a manifest is the log of the files to be packaged into a gem. If its not in the Manifest.txt file, the users won’t get it.
Before you package your gem, you can compared the list of files in your gem folder, with the Manifest.txt:
<pre>rake check_manifest</pre>
The results show a diff of the two.
h2. Package and test locally
Before releasing a new version of a gem, it is a great idea to install the gem locally and do some sanity checks. You know, to limit the chance of you looking like a noob.
<pre>rake install_gem</pre>
This locally installs the gem, ready for testing and local use.
Now pretend to be a user, and do some tests - especially of new functionality - so you are comfortable all the files have been packaged up, and you haven’t missed anything in the Manifest.txt.
One set of tests you should do is to repeat any tutorials you include in your website. If your gem is dependent on other gems that are rapidly changing, its possible your tutorial might be invalid even if your unit tests are successful. Best you find any errors before the users start emailing you!
h2. Releasing your gem to the world
Once you’re ready for release there are some final steps.
<a name=“setup_rubyforge”></a>
h3. Setup your environment to upload to RubyForge.
There are several steps you need to perform initially to “setup your environment for uploading gems to RubyForge”:rubyforge.html.
h3. Document changes in History.txt
Between each version of your gem, you probably changed something. You should document this in the History.txt file. For each new release, you need to add two paragraphs that look like this:
<pre>== 0.5.4 14/4/2007
1 major improvement
150% more Wizzos
2 bug fixes
Wizzos are the proper colour
You only get Wizzos when you ask for them
</pre>
The two paragraphs will be automatically picked up by the following release process and documented against the release on RubyForge site. To see an example of the end result, look at the “History page for newgem”:newgem.rubyforge.org/rdoc/files/History_txt.html.
The History.txt notes for your first release have already been started for you.
h3. Release the website (optional)
By default, newgem installs a one-page website to promote your RubyGem. (You can disable this with the -W option). Once you have changed the gem version number, you can push the latest website to rubyforge (or any target host) with a rake task.
Check the file config/website.yml and give it your rubyforge username if necessary. Also, if you want to put your website on a different host than rubyforge.org you can change the username@host and /path/to/www in this file.
Then rsync the website files with:
<pre>rake website</pre>
This will also generate RDocs and put them in the doc subfolder. Perhaps link to it in your website.
h3. Release the gem
Run rake release VERSION=X.Y.Z after you’ve done all these steps. It packages and uploads your gem to RubyForge.
It can take 20 minutes to an hour before new gem releases are available via the gem installer. But when they are ready, everyone will be able to download and install your gem using:
<pre>sudo gem install gem_name#</pre>
If your GEM_NAME and RUBYFORGE_PROJECT name are the same, then:
RUBYFORGE_PROJECT.rubyforge.org is your website, and
RUBYFORGE_PROJECT.rubyforge.org/rdoc is your rdocs
If they are different, then:
RUBYFORGE_PROJECT.rubyforge.org/GEM_NAME is your website, and
RUBYFORGE_PROJECT.rubyforge.org/GEM_NAME/rdoc is your rdocs
h2. Bonus tasks thanks to Hoe
Your gem uses the Hoe gem to provide a dozen or so useful rake tasks for managing your gem, such as release, check_manifest and publish_docs.
See them all with:
<pre>rake -T</pre>
Remember, the Rakefile is yours to extend as you please with more rake tasks, such as the website tasks which are already added.
For more information about each task, see the “Hoe README”:seattlerb.rubyforge.org/hoe/
h2. Related articles
“Original blog article and tutorial”:drnicwilliams.com/2006/10/11/generating-new-gems/
“Tutorial: Publishing RubyGems with Hoe”:nubyonrails.com/articles/2007/06/15/tutorial-publishing-rubygems-with-hoe by “Geoffrey Grosenbach”:geoffreygrosenbach.com/
“Using New Gem Generator in Windows”:codeconversations.blogspot.com/2007/07/using-new-gem-generator-in-windows_8009.html by “Jorge Cangas”:codeconversations.blogspot.com/
“Building a Ruby Gem”:bogojoker.com/blog/2008/05/building-a-ruby-gem/ by “Joseph Pecoraro”:bogojoker.com/ (includes a Problems/Troubleshooting section!!)
“An Almost Fix for Creating RubyGems on Windows”:blog.emson.co.uk/2008/06/an-almost-fix-for-creating-rubygems-on-windows/ by “Ben Emson”:blog.emson.co.uk/
h2. Dr Nic’s Blog
“www.drnicwilliams.com”:http://www.drnicwilliams.com - for future announcements and other stories and things.
h2. Forum
“groups.google.com/group/new-gem-generator”:http://groups.google.com/group/new-gem-generator
h2. How to submit patches
Read the “8 steps for fixing other people’s code”:drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section “8b: Submit patch to Google Groups”:drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
You can fetch the source from either:
rubyforge: “rubyforge.org/scm/?group_id=<%= rubyforge_project_id %>”:rubyforge.org/scm/?group_id=<%= rubyforge_project_id %>
<pre>git clone git://rubyforge.org/newgem.git</pre>
<pre>git clone git://github.com/drnic/newgem.git</pre>
h3. Build and test instructions
<pre>cd newgem rake test rake install_gem</pre>
h2. License
This code is free to use under the terms of the MIT license.
h2. Contact
Comments are welcome. Send an email to “Dr Nic Williams”:drnicwilliams@gmail.com.
Generated with the Darkfish Rdoc Generator 2.