pluotsorbet/tools/jasmin-2.4

Jasmin README file                         1 March 1997, Jonathan Meyer

                                              Last updated October 2004



Introduction

------------

Welcome to Jasmin version 1.1.



Jasmin is a Java Assembler Interface. It takes ASCII descriptions for Java

classes, written in a simple assembler-like syntax, using the Java

Virtual Machine instruction set. It converts them into binary Java class 

files suitable for loading into a Java interpreter.



Jasmin was originally written as the companion to the 

book "Java Virtual Machine", published by O'Reilly, written by 

Jon Meyer and Troy Downing. (See http://www.ora.com/catalog/javavm/).

The book is now out of print. However, the Jasmin assembler retains its

usefulness as a utility, and continues its life as an OpenSource project.



Background

----------

Jasmin is today a little long in the tooth. It was originally coded in

1996 as a stop-gap until Sun released their own assembler. It has seen 

no major upgrades since 1997. By 2004 Sun still has not released an 

official assembler, so I decided to release Jasmin as a sourceforge

project. Hopefully this will inject some fresh life into the project...



Home Page

---------

Check out the Jasmin home page at:



    http://jasmin.sourceforge.net



Requirements

------------

Jasmin is written in Java, and should work with most Java 1.1 environments. 



To run Jasmin you need to have a Java 2 Runtime Environment available (e.g. JDK 1.4). 

This can be downloaded from "http://www.javasoft.com/j2se/".



Getting Started

---------------

The Jasmin distribution contains a jasmin.jar file holding the Jasmin assembler. 

To run Jasmin, execute the Jarfile, specifying any files to assemble 

as command-line parameters, e.g. to assemble the "HelloWorld.j" file in examples,

first use cd to change into the Jasmin directory:



    cd c:\jasmin-1.1                                   [Windows]

or

    cd ~/jasmin-1.1                                    [Unix]



Then, to run Jasmin, use:



    java -jar jasmin.jar examples\HelloWorld.j         [Windows]

or

    java -jar jasmin.jar examples/HelloWorld.j         [Unix/MacOsX]

	



After running Jasmin as above, it generates a compiled HelloWorld.class file

in the examples directory.



You can then run the HelloWorld program by doing:



    java examples.HelloWorld



Build Instructions

------------------

Jasmin uses Ant as its build mechanism. See build.xml for instructions on how

to build Jasmin. In brief, you need to:



1. Start a Terminal or Command window. 

2. Change (cd) into the Jasmin directory

3. Make sure that java, javac etc. are on your path

4. Run build.bat (Windows) or build.sh (Unix).



For example, on Windows, this might look something like:



    cd c:\jasmin-1.1                 # change to Jasmin directory

    build all

			

Or, for Unix, it might be like:



    cd ~/jasmin-1.1                  # change to Jasmin directory

    ./build.sh all



These scripts use the build.xml configuration file to specify build parameters.



Where Next

----------

After trying Jasmin out, have a look at the HelloWorld.j source in the examples directory, 

try compiling and running the other examples.



There is documentation for Jasmin in the doc directory. You should probably

start with the 'guide.html' document. 



Files

-----

The following files are included in this distribution:



    README.txt  - this file

    jasmin.jar  - executable Jar file containing Jasmin assembler

    examples/   - directory containing example files written for Jasmin

    src/        - the Java source code and for the jasmin package

    lib/        - Contains Java sources for the java_cup and jas packages

    docs/       - various documentation files.



Copyright

---------

Jasmin is Copyright (1997-2004) Jonathan Meyer, under the terms of

the GNU General Public License. See license-jasmin.txt for more.



Jasmin uses the JAS package which has its own copyright - see lib/jas/README.

[sbktech.org no longer seem to be in existence, but the code lives

on in this project].



Jasmin utilizes Scott E. Hudson's Java Cup package v0.9e, which is also in 

the lib directory. See http://www.cs.princeton.edu/~appel/modern/java/CUP/