Last Update: Fri Nov 06 15:39:09 -0500 2009

Builds are hard

smartcard needs to talk to hardware (card readers), so it‘s bound to use a Ruby extension. This means C, and platform-specific building nightmares. Read below for details.

The build system

smartcard uses echoe for builds. This automates most of the building and packaging work, and can even push the gem to rubyforge, with a bit of luck. Most used commands:

        rake manifest # builds the manifest (do this after checking out)
        rake package # builds the gem for your platform
        rake mswin package # cross-builds the gem for Windows
        rake test # builds the gem and runs the tests
        rake docs # runs Rdoc to produce the docs

On the other hand, you have to gem install echoe to be able to build anything.

Platform-specific information


You need to install the Developer Tools to get gcc.

Leopard and Snow Leopard (OSX 10.5 / 10.6) include a working PC/SC provider, as well as a good driver for CCID readers.

Tiger‘s (OSX 10.4) PC/SC implementation is broken and incomplete, so the Ruby extension code in smartcard has a few hacks to work around that (look for the RB_SMARTCARD_OSX_TIGER_HACK define. The following commands are broken / don‘t work:

  • Smartcard::PCSC::Context#is_valid (always returs true)
  • Smartcard::PCSC::Card#get_attribute (not implemented, throws exception)
  • Smartcard::PCSC::Card#set_attribute (not implemented, throws exception)
  • Smartcard::PCSC::Card#control (Tiger‘s API is broken, the call may not work)

The developer team doesn‘t support or test against ports of gcc or pcsclite, but we welcome patches or success stories.


A lot of effort has been spent to make Windows builds as easy as possible. smartcard is currently built using a full edition of Visual Studio 6.0, but all sources indicate that Visual C++ Express 2005 works, as long as you also install a Windows SDK (you‘re on your own for that). Visual Studio 2008 might work, but it hasn‘t been tested yet.

A summary of the hacks that have been done to get Windows builds working:

  • removing the extension files from the gemspec at the "right time" so that

echoe compiles the extension, and the gem doesn‘t require re-compilation (see the Rakefile)

  • adding the compiled extension to the file list in the gemspec
  • adding code to extconf.rb to patch the Makefile so a manifest is

embedded in the extension dll (and ruby doesn‘t crash if it uses a different version of the C runtime)


smartcard is developed (and tested) against the MUSCLE project. If you go this route, you need to get at least the pcsclite library and a driver. smartcard developers use the CCID driver, which works on most (new) readers.


Installing the following packages (and their dependencies) gets you going on Ubuntu (tested on 8.04, 8.10, 9.04 and 9.10):

  • build-essential
  • libccid
  • libpcsclite-dev (depends on libpcsclite or libpcsclite1)
  • pcscd
  • pcsc-tools