Metasm source code organisation

The metasm source code takes advantage of the ruby language facilities, which allows splitting the definition of a single class in multiple files.

Each file in the source tree holds code related to a particular feature of the framework.

Directories


The top-level directories are :

The core


The `metasm/` directory holds most of the code of the framework, along with the main `metasm.rb` file in the top directory.

The top-level `metasm.rb` has code to load parts of the framework source on demand in the ruby interpreter, which is implemented with ruby's <const_missing.txt>

Executable formats ##################

The `exe_format/` subdirectory contains the implementations of the various binary file formats supported in the framework.

Three files have a special meaning here:

The `main.rb` file is included in all other formats, as all file classes are subclasses of `ExeFormat`.

The `serialstruct.rb` implements a helper class to ease the description of binary structures, and generate parsing/encoding functions for those.

All other files implement a specific file format handler. The bigger files (`ELF` and `PE/COFF`) are split between the parsing/encoding functions and decoding/disassembly.

CPUs ####

The cpu-specific code is stored inside the `cpu/` subdirectory.

All supported architectures have a dedicated subdirectory, and a helper file that will simply include all the arch-specific files.

All those files will contribute to add functions to the same class implementing the CPU interface. Not all CPUs implement all those features. They are:

In some cases the files are small enough to be all merged into the `main.rb` file.

Operating systems #################

The `os/` subdirectory holds the code used to abstract an operating systems.

The files here define an API allowing to enumerate running processes, and interact with them in various ways. The <core/Debugger.txt> class and subclasses are defined there.

Those files also holds the list of known functions and in which system libraries they can be found (see <core/WindowsExports.txt> or <core/GNUExports.txt>), which are used when linking executable files.

Graphical user-interface ########################

The `gui/` subdirectory contains the code needed by the metasm graphical user-interfaces.

Currently those include the disassembler and the debugger (see the samples section).

Those GUI elements are implemented using a custom GUI abstraction, and reside in the various `dasm_*.rb` and `debug.rb`.

The actual implementation of the GUI are found in:

Please note that the Qt backend does not work *at all*.

The `gui.rb` file in the main directory is used to choose among the available GUI backend the most appropriate for the current session.

Others ######

The other files directly in the `metasm/` directory are either support files (eg `encode.rb`, `parse.rb`) that hold generic functions to be used by specific cpu/exeformat instances, or implement arch-agnostic features. Those include:

The samples


The `samples/` directory contains a lot of small files that intend to be exemples of how to use the framework. It also holds experiments and work-in-progress for features that may later be integrated into the main framework.

The comment at the beginning of the file should be clear about the purpose of the script, and the scripts are expected to be copy/pasted and tweaked for the specific task needed by the user (that's you).

Some of those files however are full-featured applications:

The `samples/dasm-plugins/` subdirectory holds various plugins for the disassembler.