README

Semblance version 0.2
=====================

Semblance is eventually meant as a set of tools to manipulate assembly code.
Currently it only contains a single program:

dump - produce disassembly and other information from exectable files.
       Originally written to support NE (New Executable) files due to the lack
       of any available tool. Currently supports MZ (aka DOS), NE, and PE/PE+
       (Portable Executable, i.e. Win32) executables.

Semblance is free software, released under the GNU GPL v3; see the file
LICENSE for the details.


Semblance is hosted at the following URL:

https://gitlab.winehq.org/zfigura/semblance

It was originally hosted on GitHub, but has since been moved.


Installing
----------

To build, just run:

    ./autogen.sh
    ./configure
    make

To install to your computer, subsequently run "make install" as root.

About
-----

I originally wrote Semblance as a disassembler for NE images, in the absence
of any existing tool. As I wrote it I added some quite useful features, and
eventually decided these were useful enough to extend it to PE images as well,
where an existing decompilation tool (objdump) had enough annoyances that
Semblance actually ended up being more useful.

Some of the notable features of Semblance are:
    * Instead of indiscriminately trying to dump everything as assembly, it
      scans entry points and exports, following branches, to determine what
      instructions are valid code, and dumps only these by default. This
      avoids dumping data or zeroes, inserted into text sections, as code.
    * Prints warnings when bogus instructions are disassembled.
    * Can disassemble NE resources. (PE resources are forthcoming.)
    * Detects instructions that call PE imports better—e.g. can recognize a
      call into an IAT.
    * Prints PE relocations inline.
    * Supports MASM, NASM, and GAS-based syntax.