You should also see:
Jasmin was created as a companion to the book "Java Virtual Machine", written by Jon Meyer and Troy Downing and published by O'Reilly Associates.
The Jasmin assembler does little compile-time processing and checking of the input code. For example, it doesn't check that classes you reference actually exist, or that your type descriptors are well formed. Jasmin also lacks many of the feautures found in full macro assemblers. For example, it doesn't inline mathematical expressions, perform variable substitutions, or support macros.
On the other hand, using Jasmin you can quickly try out nearly all of the features of the Java Virtual Machine, including methods, fields, subroutines, exception handlers, and so on. The Jasmin syntax is also readable and compact.
jasmin command runs Jasmin on a file.
For example:
% jasmin myfile.jassembles the file "myfile.j". Jasmin looks at the
.class directive contained in the file to
decide where to place the output class file. So if myfile.j starts
with:
.class mypackage/MyClass
then Jasmin will place the output class file "MyClass.java" in the
subdirectory "mypackage" of the current directory. It will create the
mypackage directory if it doesn't exist.You can use the "-d" option to tell jasmin to place the output in an alternative directory. For example,
% jasmin -d /tmp myfile.jwill place the output in /tmp/mypackage/MyClass.class.
Finally, you can use the "-g" option to tell Jasmin to include line number information (used by debuggers) in the resulting .class file. Jasmin will number the lines in the Jasmin source file that JVM instructions appear on. Then, if an error occurs, you can see what instruction in the Jasmin source caused the error. Note that specifying "-g" causes any .line directives within the Jasmin file to be ignored.
Directives and instructions can take parameters. These parameters are placed on the same line as the directive or instruction, separated by spaces.
All directive names start with a "." character. The directives in Jasmin are:
.catch .class .end .field .implements .interface .limit .line
.method .source .super .throws .var
Some example directive statements are:
.limit stack 10
.method public myMethod()V
.class Foo
The parameters used by each directive are described in more detail
later in the document.
Jasmin uses the standard mnemonics for JVM opcodes as instruction names. For example, aload_1, bipush and iinc are all Jasmin instruction names.
Here are some examples of instruction statements:
ldc "Hello World"
iinc 1 -1
bipush 10
See the Instruction Guide for more details on
the syntax of instructions in Jasmin.
Foo:
Label:
Label names cannot start with a numeric digit, and cannot contain
any of the special characters:
= : . " -You cannot use directive names or instruction names as labels. Other than that, there are few restrictions on label names. For example, you could use the label:
#_1:Labels can only be used within method definitions. The names are local to that method.
Note that the semicolon must be the first character in the token, i.e. embedded semicolons are ignored. For example,
abc;defis treated as a single token "abc;def", and
Ljava/lang/String;is the token "Ljava/lang/String;", whereas
foo ; baz dingis the token "foo" followed by a comment "baz ding".
1, 123, .25, 0.03, 0xA
but not
1e-10, 'a', '\u123'
Quoted strings are also very basic. The full range of
backslash escape sequences are not supported yet, although "\n" and "\t"
are.
java/io/PrintStream/println(Ljava/lang/String;)V
is the method called "println" in the class java.io.PrintStream, which
has the type descriptor "(Ljava/lang/String;)V" (i.e. it takes a String
and returns no result). In general, a method specification
is formed of three parts: the characters before the last '/' form the class
name. The characters between the last '/' and '(' are the method name. The
rest of the string is the type descriptor for the method.
foo/baz/Myclass/myMethod(Ljava/lang/String;)V
--------------- ---------------------
| -------- |
| | |
class method descriptor
As another example, you would call the Java method:
class mypackage.MyClass {
int foo(Object a, int b[]) { ... }
}
using:
invokevirtual mypackage/MyClass/foo(Ljava/lang/Object;[I)I
getstatic mypackage/MyClass/my_font Ljava/lang/Font;
gets the value of the field called "my_font" in the class mypackage.MyClass.
The type of the field is "Ljava/lang/Font;" (i.e. a Font object).
Typically, a Jasmin file starts with the three directives:
.source <source-file>
.class <access-spec> <class-name>
.super <class-name>
For example, the file defining MyClass might start with the directives:
.source MyClass.j
.class public MyClass
.super java/lang/Object
If no .source directive is given, the name of the Jasmin file you are compiling is used instead as the SourceFile attribute instead.
.interface public foo
.implements <class-name>
where <class-name> has the same format as was used by .class and .super.
For example:
.class foo
.super java/lang/Object
.implements Edible
.implements java/lang/Throwable
A field is defined using the .field directive:
.field <access-spec> <field-name> <descriptor> [ = <value> ]
where:
For example, the Java field definition:
public int foo;
becomes
.field public foo I
whereas the constant:
public static final float PI = 3.14;
becomes
.field public static final PI F = 3.14
A method is defined using the basic form:
.method <access-spec> <method-spec>
<statements>
.end method
where:
.method foo()V
return ; must give a return statement
.end method
.limit stack <integer>
.limit locals <integer>
.line <integer>
.method foo()V
.line 5
bipush 10 // these instructions generated from line 5
istore_2 // of the source file.
.line 6
...
.var <var-number> is <name> <descriptor> from <label1> to <label2>
.method foo()V
.limit locals 1
; declare variable 0 as an "int Count;"
; whose scope is the code between Label1 and Label2
;
.var 0 is Count I from Label1 to Label2
Label1:
bipush 10
istore_0
Label2:
return
.end method
.throws <classname>
.throws java/io/IOException
This information isn't required by Java runtime systems,
but it is used by the Java compiler to check that methods
either catch exceptions they can cause, or declare
that they throw them.
.catch <classname> from <label1> to <label2> using <label3>
.catch java/io/IOException from L1 to L2 using IO_Handler
If classname is the keyword "all", then exceptions of any
class are caught by the handler.
.method abstract myAbstract()V
.end method
note that abstract methods can have .throws directives, e.g.
.method abstract anotherAbstract()V
.throws java/io/IOException
.end method
.method and
.end method directives. VM instructions can take zero or more
parameters, depending on the type of instruction used. Some example
instructions are shown below:
iinc 1 -3 ; decrement local variable 1 by 3
bipush 10 ; push the integer 10 onto the stack
pop ; remove the top item from the stack.
See the instruction reference for more details on the syntax
of instructions in Jasmin.