metasploit-framework/lib/metasm/doc/install_notes.txt

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 :

* rightclick on `my computer`
* select tab `advanced`
* click `environment variables`

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.