gitweb on Svarog

projekti pod git sistemom za održavanje verzija -- projects under the git version control system
wsl metrics, reorganized comments for GPL
[mjc2wsl.git] / docs / mjc2wsl.txt
1 mjc2wsl tool
2 ============================================================
4 This tool converts MicroJava bytecode into WSL code.
6 The specification currently supported is from 1999. There
7 are some changes introduced later. For instance there is the
8 2006 specifcation but there were no big changes, mostly some
9 pieces of the language and bytecode were removed, presumably
10 for simplification and more focus on the concepts.
12 More details about the specifications can be found in the
13 MicroJava folder in the docs folder.
15 For usage guides run the tool without parameters, or with
16 "-h" for the basic help, or with "--help" for the longer
17 help screen.
20 What works
21 ----------
23 Currently all of the commands of the 99 specification are
24 reconised and processed properly. All tested examples showed
25 the same behaviour when executing the original bytecode and
26 executing the translated WSL code.
28 Some details below:
30 There are virtual stacks to simulate both the expresion and
31 the method stack.
33 There are arrays representing the static variables and the
34 local variables.
36 The local variables arrays is swaped out on recursive calls.
38 Objects and arrays are stored in arrays with all the regular
39 access code mapping properly.
42 What is different
43 -----------------
45 Objects and arrays are not directly held on a single heap,
46 and the memory maping is simulated to behave the same, but
47 there is no rounding for direct access to pieces of memory.
49 Object and arrays are actually held in different memory
50 storages.
52 There is not stack pointer or frame pointer, the local
53 variables array is swaped out as needed.
56 What does not
57 -------------
59 Character codes are not converted to actuall characters when
60 printed on the screen.
62 The heap is not actually simulated byte-per-byte, so any
63 code that would attempt to optimise by doing so would not
64 work. Note however that the language specification is not
65 allowing direct access to the memory, neither is the
66 bytecode actually working directly with the heap, and that
67 array and object access are done by specialised commands.
68 Still there is an option for using fields beyond the actuall
69 object that could produce unexpected behaviour.
70 Array access in the MJVM does check for indexe out of bounds
71 errors.
73 The size of the heap is not taken into consideration when
74 allocating new arrays and objects. What this means is that
75 there will be no heap overflow exception thrown, since our
76 heap is seemingly endless.
78 Null access does not throw explicit errors, although it
79 will cause problems with the list access. maintanance Doni Pracner