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 <www.ruby-lang.org/en/downloads/>, under the `Ruby on Windows` section.

The `mercurial` website has links to various installers: <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:pathtometasm` 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:appsrubylibruby1.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 <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.