Dr Nic

Create and deploy command line apps with RubyGems

RubyGems have many things going for them: they are a local, central repository for all external libraries, they have explicit versioning, you get inter-gem dependency checking, default integration with the RubyForge gem server, and the ability for you to run your own gem server. For free. Neat.

Hidden in the back, in no way obvious as to its existence nor how to use it, is my favouritest feature: command line executables that are platform-neutral.

Write your executable inside a gem, and regardless what platform the gem is deployed to they will be able to execute the application.

Examples of gems with command line applications

rails has the rails app to generate scaffolding for a new application, camping has its camping app as its runtime server, and cheat has the cheat app to retrieve and cache the cheat sheets.

Whilst rails and camping gems come with libraries of code and complementary test suites, cheat has nothing but its cheat app. The gem exists to deploy a command line application that is written in Ruby.

Create your own command line app in Ruby

Install the latest version of newgem (minimum v0.5)

gem install newgem

Create a new gem:

> newgem -b hello_world,print_date my_fun_apps
creating: my_fun_apps
creating: my_fun_apps/CHANGELOG
creating: my_fun_apps/README
creating: my_fun_apps/lib
creating: my_fun_apps/lib/my_fun_apps
creating: my_fun_apps/lib/my_fun_apps.rb
creating: my_fun_apps/lib/my_fun_apps/version.rb
creating: my_fun_apps/bin
creating: my_fun_apps/bin/hello_world
creating: my_fun_apps/bin/print_date
creating: my_fun_apps/Rakefile
creating: my_fun_apps/test
creating: my_fun_apps/test/all_tests.rb
creating: my_fun_apps/test/test_helper.rb
creating: my_fun_apps/test/my_fun_apps_test.rb
creating: my_fun_apps/examples
creating: my_fun_apps/setup.rb
NOW - update my_fun_apps/Rakefile with gem description, etc

The new -b app[,app2] parameter generates the scaffolding for two executables – hello_world and print_date. If you need more apps in a gem after running newgem scaffolding, its very simple, as shown below.

In bin/hello_world put:

puts "Hello world"

In bin/print_date put:

puts Time.now

And build and install your gem:

> rake package
(in C:/InstantRails/ruby_apps/my_fun_apps)
rm -r .config
  Successfully built RubyGem
  Name: my_fun_apps
  Version: 0.0.1
  File: my_fun_apps-0.0.1.gem
mv my_fun_apps-0.0.1.gem pkg/my_fun_apps-0.0.1.gem

> gem install pkg/my_fun_apps-0.0.1.gem
Attempting local installation of 'pkg/my_fun_apps-0.0.1.gem'
Successfully installed my_fun_apps, version 0.0.1
Installing RDoc documentation for my_fun_apps-0.0.1...

or simply use the install task to do both jobs (on unix machines):

> rake install

Note: If you get a build error it may be because you don’t have the ability to generate the tar file version of the gem. Change p.need_tar = true to p.need_tar = false near the end of the Rakefile and run the above lines again.

And presto! You have two new command line applications:

> hello_world
Hello world

> print_date
Wed Oct 18 12:05:56 W. Europe Daylight Time 2006

Adding more executables to a gem

Two step process:

  1. Create a new text file in the bin folder with the name of the application, and fill it with Ruby goodness. Perhaps investigate SimpleConsole for advanced console coding wizardry.
  2. In the Rakefile, add the application name to the BIN array, at the top.

And then repackage and install.

Deploying for communal usage

That’s another topic for another day.

Hint: get a new RubyForge account and Request New Project, and I’ll try to finish the article before RubyForge administrators accept your proposal.

Related posts:

  1. Closing in on The Dream: “one-click-to-deploy Rails apps” Got a simple app you want to build? Allocate...
  2. My RubyGems development tools and workflow The Open Source Developers Conference (osdc) is a nifty...
  3. newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...
  4. Unit Testing iPhone apps with Ruby: rbiphonetest Everything to love about Ruby: the concise, powerful language;...
  5. What is *jour and why they are killer apps for RailsCamp08 Uploaded with plasq’s Skitch! RailsConf 2008 was a few weeks...

12 Responses to “Create and deploy command line apps with RubyGems”

  1. Anonymous says:

    Dr Nic Create and deploy command line apps with RubyGems…

    RubyGems have many things going for them: they are a local, central repository for all external libraries, they have explicit versioning, you get inter-gem dependency checking, default integration with the RubyForge gem server, and the ability for you …

  2. [...] Usando o New Gem Generator, o trabalho de produzir novos pacotes “gem” praticamente desaparece. Há um pequeno tutorial nesse link, mas aqui vai o “básico do básico”: [...]

  3. [...] RubyGems have many things going for them, but hidden in the back, in no way obvious as to its existence nor how to use it, is my favourite feature: command line executables that are platform-neutral.read more | digg story Share and Enjoy:These icons link to social bookmarking sites where readers can share and discover new web pages. [...]

  4. Jason says:

    Great stuff! Thanks for this!

  5. [...] The New Gem Generator rocks. Type newgem <gem_name> and you get all standard scaffolding for a gem. They look just like plugins, or vice versa. And the -b option bangs out new command line apps. Sweet. [...]

  6. Orion says:

    Two things:

    I am using a newer version of newgem (0.8.1). With that version I do not see the BIN array in the rake file.

    If I have a gem I already created with newgem but did not add the binaries at the time of creating the gem. How would I add the binaries to this gem.

  7. Likewise here, I’ve got 0.11.0, the most recent version according to rubyforge, and am having no luck with finding a BIN constant in the rake file or otherwise getting my scripts in /bin to run…

  8. Never mind! I just added a new BIN=”the_name_of_my_bin_script” to the rakefile right above the AUTHOR, EMAIL, etc. constants and it started working. The one other piece, at least for me, was to remember to include my bin script in the Manifest.txt.

  9. Dr Nic says:

    @Gregory Borenstein [via] – in the latest version of newgem and Hoe you don’t need to specify the bins; only that you add them to your Manifest.txt as normal. If they are in the bin folder, they will be picked up as applications.

  10. [...] I also wanted the structure of the application to follow a standard structure and I didn’t want to put ‘.’ into my path, for security reasons. Dr Nic came to the rescue with a couple of excellent articles describing how to create gems using newgem and specifically command-line apps as gems. [...]

  11. Ben says:

    Hi Dr Nic

    Your articles on RubyGems has been really useful and informative. I’ve written my own article which I hope answers the .hoerc file questions:

    http://blog.emson.co.uk/2008/06/an-almost-fix-for-creating-rubygems-on-windows/

    Keep up the good work,
    Ben…

  12. DaveI says:

    Dr. Nic,

    Perhaps you could comment on my miss-adventure with newgem
    version 1.5.2. – what I did wrong and how to do it right.

    I had an .rb file that I wanted to remain in the lib directory
    to be ‘required’ but also wanted version of the file without the
    .rb extension in the bin directory to be run as a shell command.
    I thought, “I’ll just put a link in the bin directory to the lib directory
    version of the file”. I then re-ran newgem and it replaced, via my link,
    its target with a script of its own (a version saving wrapper – I
    think.) I’m a noobee to newgem, but I don’t like it deleting my data
    without warning.

    Thanks,
    Dave