================================================================================
B A S T A R D                                            disassembly environment


Introduction
============
See the manual (doc/bastard.txt) or the HOWTO (doc/Disasm-HOWTO.txt). The
"Internal Representation" section of the manual explains how the DB works with
the target, in excruciating detail, while the "Installation" and "Quickstart"
sections should help out beginners.

For those who dislike the command line interface, there is a Tk front-end in
the utils directory called 'lgb'.


Installation
============
The disassembler should be compiled with:
	make install
Thie will compile the bastard and install it to /usr/local/bastard, with the
main executable symlinked to /usr/local/bin/bastard.

The makefile contains a few options [program name, install location, etc] at
the very top if the defaults are not satisfactory. In order to do partial 
builds, the makefile provides the following targets:

	all       -- make the program and required libraries
	install   -- make all, install to $(INSTALL_DIR), link to $(INSTALL_BIN)
	uninstall -- remove $(INSTALL_DIR) and $(INSTALL_BIN)
	seer      -- make the seer library and utilities
	typhoon   -- make the typhoon library and utilities
	arch      -- make the disassembler libraries
	asm       -- make the assembler libraries
	lang      -- make the high-level language libraries
	release   -- make all, strip the executable and shared libraries
	clean     -- remove the binaries and object files
	distclean -- remove the seer and typhoon object files
	tgz       -- make the distribution tarballs

The required libraries and headers may need to be installed on your system. The
general procedures for manual compilation if 'make all' does not work are:

	Readline [required, not included]:
	/usr/src/readline> ./configure;make;make install

	EiC [required]:
	/usr/src/bastard/src/EiC> config/makeconfig; make; make install
	/usr/src/bastard/src/EiC> cp lib/*.a /usr/src/bastard/lib
	/usr/src/bastard/src/EiC> cp include/eic* ../../include/script
	/usr/src/bastard/src/EiC> cp -r include/* ../../include/script/eic
               
	
	Typhoon [required]:
	/usr/src/bastard/src/typhoon> ./configure; make
   /usr/src/bastard/src/typhoon> cp src/libtyphoon.a /usr/src/bastard/lib

	Bastard:
	/usr/src/bastard> make && make install

The program can be run from any directory; it will determine the location of
its home directory based on the location of the bastard binary. Therefore it 
is important to leave the bastard binary in its home directory, and use 
symlinks to place it in the path. Alternatively, the environment variable
$BASTARD_HOME can be set to override the location of the home directory.

EiC Compile problems:
Change line 221 of config/gensdtio from
		crt_inttypedef(fp, "fpos_t", sizeof(fpos_t));
to
     crt_inttypedef(fp, "fpos_t", sizeof(__off_t));
	  


Required Libraries
==================
  libtyphoon	: Typhoon 1.11 Embedded Relational Database 
  libeic 		: EiC Embedded C Interpreter
  libreadline  : GNU readline library version 4.1

Both Typhoon and EiC are supplied with this distribution in binary and source
form; they can also be downloaded from the Bastard distribution site at
	http://www.sourceforge.net/projects/bastard
The licenses for the libraries are in .license/typhoon, .license/EiC, and 
.license/GNU.

Also, readline headers are assumed to be in $INCLUDE/readline.


Intended Usage
==============
All types of devious purposes.

To get a list of the interpreter commands, type "?" at the ;> prompt. The LOAD 
command [shortcut "l"] will load ./a.out as ELF format; or you can specify a
target filename [as well as format and CPU type, though these two do not do 
much at the moment]. The DISASM command [shortcut "d"] will output the 
disassembly to the console. 

Additional commands, as well as the BC scripting language, are documented
in doc/bastard.txt ; the include files api.h and bdb.h are also recommended
reading material. Finally, the README.CODERS file has hints on using the
bastard, a brief discussion of how it works, and the philosophy --such as it
is-- behind it.

Caveats: Typhoon uses a semaphore in /tmp, so two processes cannot use 
Typhoon simultaneously. This means that one process cannot make database calls
while another process is making them -- you can run two sessions of the bastard
concurrently, but they will have to take turns using the DB [e.g. printing a
disassembled listing, disassembling a file, and basically any behavior other
than sitting there idle].



License
=======
This bastard is given artistic license to roam free, as specified in the file
.license/bastard in the bastard's home directory.

Despite the reuse provisions of the GNU license, which has a "forest for the
trees" flaw typical of rms' stuff and tends to violate in letter what it 
promises in spirit, the source code for libopcodes and libreadline are *not* 
being distributed along with this package. The source code for either is too 
huge, and they are too readily available from other sources ... in fact, it 
seems so far that every extant linux distribution comes with both of them.


CVS
===
Bastard developers can retrieve the latest source code from the CVS repository
at Sourceforge. The CVSROOT for the project is
	username@cvs.bastard.sourceforge.net:/cvsroot/bastard
and ssh must be used to along with cvs to handle the remote connection.

For the lead-me-by-the-hand non-CVS types:

  [/usr/src]$>mkdir bastard; cd bastard
  [/usr/src/bastard]$>export CVS_RSH=`which ssh`
  [/usr/src/bastard]$>cvs -duser@cvs.bastard.sourforge.net:/cvsroot/bastard co .

Alternatively, the cvs tarball can be downloaded from SourceForge at:
  http://cvs.sourceforge.net/cvstarballs/bastard-cvsroot.tar.gz


Known Bugs
==========
Please submit your favorites!

This now has its own file...
