readme

This Source-Navigator, an IDE for C/C++/Fortran/Java/Tcl/PHP/Python and a host of other languages.

This directory contains an example parser for Source-Navigator to parse
assembly language programs.

Because assembly language syntax differs so much depending on the target 
microprocessor and object file format, it is necessary to build an assembly 
parser customised to the assembly language being used.

This directory contains two such syntax definitions: one for the ELF object
format for Linux on an i486 processor and one for the ELF object format on 
SPARC Solaris.

___________________________
Building an assembly parser

This can be achieved by running "make TARGET=<target>" (ie. running
"make TARGET=solaris-sparc".  One of the provided syntax definitions will be
chosen and written to an M4 source file called `macros.m4'.

macros.m4 is always the current working definition for the parser.  The GNU
flex specification for the parser, abrowser.l.in, is preprocessed using the M4
macro processor to produce a customised version of the flex specification
(abrowser.l).  abrowser.l.in contains M4 macro invocations and those macros
are defined by macros.m4.

__________________________
Writing a syntax defintion

The assembly language parser needs the following information about the
particular assembly language syntax in order to parse source files:

	- the end-of-line comment character.  In some assembly languages,
	  this is a semicolon (`;') character.  In others, it is the
	  `#' character.

	- The set of opcode mneumonics for subroutine call instructions.
	  In some instruction sets, this may be `call', but in others,
          there may be more than one mneumonics such as `bra', `jsr', `jmp'.
	  When there is more than one instruction in the "jump" class of 
          instructions, an M4 macro called `oneof' is provided to specify
	  multiple mnemonics:

		oneof(bra,jsr,jmp)

        - The assembler's psuedo opcode for declaring a global data object
          (with external linkage).  In the GNU assembler, `gas', this is often
	  ".comm".
	
	- The assembler's psuedo opcode for declaring a static data object
	  without external linkage.  In `gas', this is often ".local".

	- The assembler's pseudo opcode for defining a macro.  In `gas', this
	  is often ".macro".

	- The assembler's syntax for labels.  Most assemblers use the format
	  "label:" with whitespace at the start of a line.  Other assemblers 
	  such as `gas' for HP PA processors use just "label" but enforce 
          that it starts in column 1.

	- The pattern used by a compiler when generating code in the
	  particular assembly syntax.  This is only important when parsing
	  code generated by a compiler instead of hand-written assembly
	  source.

Using one of the existing .m4 files, create a new syntax definition file by
copying it to a new name (e.g. coff-i386ex.m4) and customising it.  M4 macro
definitions take the form:

	define(`name', `replacement')

For each macro in the synax definition file, edit the `replacement' text so
that the right information is placed into the flex specification once it is
processed.

Generate the parser by typing:

	make TARGET=coff-i386ex

_____________________
Trying out the parser

To try out the parser, replace "SN=/usr/local/snavigator" in the Makefile
with the path to your Source-Navigator installation.

A number of example assembly source files are provided.  They have been
generated by a native GNU C compiler for the Intel 486 (ELF object file
format).  Therefore you should only attempt to parse them using the
appropriate version of the assembly parser.

Build and test the parser by running `make test'.  The Source-Navigator project
database will be created in the .snprj subdirectory.  You may then use the
database tools such as `dbdump' to inspect the project database.

Because different operating systems have different library names for the
dynamic loading library, you may need to change the "-ldl" library name
to the library which supports dynamic loading on your system. This is required
to get rid of libtcl8.1 linker errors.

Refer to the Source-Navigator Programmer's Reference Guide for details on
writing additional parsers for other programming languages.