Metasm installation notes

Metasm is a pure ruby lib, and the core (metasm/ subdir) does not depend on any ruby library (except the metasm/gui, which may use gtk2).

So the install is quite simple.

Download

Metasm is distributed using the mercurial source control system.

The recommanded way to install is to use that tool, so you can always be up-to-date with the latest developpements.

You will also need the Ruby interpreter (version 1.8 and 1.9 are supported).

Linux

Issue the following commands to install the mercurial and ruby software

    sudo apt-get install ruby
    sudo apt-get install mercurial

Then download metasm with

    hg clone http://metasm.cr0.org/hg/metasm/

This will create a new directory metasm/ with the latest version of the framework.

Windows

The ruby website offers many ruby packages. The RubyInstaller should work fine. Go to http://www.ruby-lang.org/en/downloads/, under the Ruby on Windows section.

The mercurial website has links to various installers: http://mercurial.selenic.com/wiki/BinaryPackages Choose one, then use the clone repository command with the following url:

    http://metasm.cr0.org/hg/metasm/

This will create a new subdirectory metasm/ with the latest version of the framework.

Upgrading

To upgrade to the latest and greatest version, launch a shell prompt and navigate to the metasm directory, then issue:

    hg pull -u

which will upgrade your installation to the latest available version.

With TortoiseHG, simply issue the upgrade command on the metasm directory.

Local installation

If you simply want to install metasm for your personnal usage (VS a system-wide installation), follow these steps.

Download the metasm source files under any directory, then update the environment variable RUBYLIB to include this path. The path you add should be the directory containing the metasm.rb script and the metasm/, samples/, doc/ subdirectories.

If RUBYLIB is empty or non-existant, simply set its value to the directory, otherwise you can append the path to an existing list by separating the values with a : such as:

  RUBYLIB='/foo/bar:/home/jj/metasm'

Linux

Under linux or cygwin, this is done by modifying your shell profile, e.g. ~/.bash_profile, by adding a line such as:

  export RUBYLIB='/home/jj/metasm'

You may need to restart your session or start a new shell for the changes to take effect.

Windows

The environment variables can be set through :

If a line RUBYLIB exists, add ;C:\path\to\metasm at the end, otherwise create a new variable RUBYLIB with the path as value.

You may need to restart your session for the changes to take effect.

Systemwide installation

For a systemwide installation, you should create a metasm.rb file in the site_ruby directory (that would be /usr/lib/ruby/1.8/ under linux, or C:\apps\ruby\lib\ruby\1.8\ for windows users) with the content

  # if metasm.rb can be found in /home/jj/metasm/metasm.rb
  require '/home/jj/metasm/metasm'

Testing

Open a new shell session and type

  ruby -r metasm -e "p Metasm::VERSION"

It should print a single line with a (meaningless) number in it.

Gui

If you intend to use the graphical user-interface (debugger/disassembler), if you are under Windows with a 32bit x86 ruby, this should work out of the box. In any other case, you'll need the ruby-gtk2 library.

Linux

Under linux, use your package manager to install ruby-gtk2, e.g. for Debian/Ubuntu, type:

    sudo apt-get install libgtk2-ruby

Windows

If you run a 32bit Ia32 ruby interpreter (check that ruby -v returns something like [i386-mswin32]), the Gui should work right away without gtk2, so go directly to the Testing part.

Otherwise, you'll need to install the gtk2 libs and the ruby bindings manually. Please follow the instructions at http://ruby-gnome2.sourceforge.jp/hiki.cgi?Install+Guide+for+Windows

Testing

To test the correct working of the Gui, simply launch the samples/disassemble-gui.rb script found in the metasm directory (double-click on the script, or type ruby samples/disassemble-gui.rb at a command prompt). It should display a window with a menu, and should answer to a ctrl-o keystroke with an open binary file dialog.

See the usage/disassembler_gui.txt for more information.