Skip to content

Commit b92a6af

Browse files
jovan-vukicjovan-vukic
committed
Create README.md
1 parent 8f258e6 commit b92a6af

File tree

4 files changed

+216
-0
lines changed

4 files changed

+216
-0
lines changed

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Jovan Vukić
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
<div id="top"></div>
2+
3+
<!-- PROJECT [othneildrew] SHIELDS -->
4+
5+
<!-- PROJECT LOGO -->
6+
<br />
7+
<div align="center">
8+
<h2 align="center">MicroJava Compiler - Jovan Vukić</h2>
9+
10+
<p align="center">
11+
This project is a compiler for the MicroJava language. It translates syntactically and semantically correct programs into MicroJava bytecode for execution on MicroJava virtual machines. It includes lexical, syntactic, and semantic analysis, as well as code generation functionalities.
12+
<br />
13+
<a href="https://github.com/jovan-vukic/microjava-compiler"><strong>Explore the project »</strong></a>
14+
<br />
15+
<br />
16+
<a href="https://github.com/jovan-vukic/microjava-compiler/issues">Report Bug</a>
17+
·
18+
<a href="https://github.com/jovan-vukic/microjava-compiler/issues">Request Feature</a>
19+
</p>
20+
</div>
21+
22+
<!-- TABLE OF CONTENTS -->
23+
<details>
24+
<summary>Table of Contents</summary>
25+
<ol>
26+
<li>
27+
<a href="#about-the-project">About The Project</a>
28+
</li>
29+
<li>
30+
<a href="#getting-started">Getting Started</a>
31+
<ul>
32+
<li><a href="#prerequisites">Prerequisites</a></li>
33+
<li><a href="#installation">Installation</a></li>
34+
<li><a href="#expected-output">Expected Output</a></li>
35+
</ul>
36+
</li>
37+
<li><a href="#usage">Usage</a></li>
38+
<li><a href="#contributing">Contributing</a></li>
39+
<li><a href="#license">License</a></li>
40+
<li><a href="#contact">Contact</a></li>
41+
<li><a href="#acknowledgments">Acknowledgments</a></li>
42+
</ol>
43+
</details>
44+
45+
<!-- ABOUT THE PROJECT -->
46+
## About The Project
47+
48+
The aim of the project is to implement a compiler for the MicroJava programming language.
49+
The compiler enables the translation of syntactically and semantically correct MicroJava programs into MicroJava bytecode, which runs on the MicroJava virtual machine.
50+
Syntactically and semantically correct MicroJava programs are defined by [the language specification](docs/language%20specification.pdf). The compiler has four basic functionalities: lexical analysis, syntactic analysis, semantic analysis, and code generation.
51+
52+
The lexical analyzer should recognize language lexemes and return a set of tokens extracted from the source code, which are further examined within the syntactic analysis.
53+
If a lexical error is detected during lexical analysis, an appropriate message should be printed to the output.
54+
55+
The syntactic analyzer is tasked with determining whether the extracted tokens from the source code of the program can form grammatically correct sentences.
56+
After parsing syntactically correct MicroJava programs, it is necessary to inform the user about the success of parsing. If the source code has syntax errors, it is necessary to issue a suitable explanation of the detected syntax error, perform recovery, and continue parsing.
57+
58+
The semantic analyzer is formed based on the abstract syntax tree that resulted from syntactic analysis. Semantic analysis is conducted by implementing methods for visiting nodes of the abstract syntax tree. The tree is formed based on the grammar implemented in the previous phase. If the source code has semantic errors, an appropriate message about the detected semantic error should be displayed.
59+
60+
The code generator translates syntactically and semantically correct programs into executable form for the selected MicroJava VM runtime environment. Code generation is implemented in a similar way to semantic analysis, by implementing methods that visit nodes.
61+
62+
This project considers programs that only contain the main function (method), which do not use loops or branches, nor support the creation of classes.
63+
Examples of programs written in this Java-like language are provided in the files [`program.mj`](test/program.mj) and [`test301.mj`](test/test301.mj).
64+
65+
<p align="right">(<a href="#top">back to top</a>)</p>
66+
67+
<!-- GETTING STARTED -->
68+
## Getting Started
69+
70+
To get a local copy up and running follow these simple steps.
71+
72+
### Prerequisites
73+
74+
List of things you need to do:
75+
76+
* Download and launch your favorite Java IDE.
77+
78+
### Installation
79+
80+
Setup & execution:
81+
82+
1. Clone the repo:
83+
```sh
84+
git clone https://github.com/jovan-vukic/microjava-compiler.git
85+
```
86+
2. Set the Java version in the project to 1.8 for the best compatibility.
87+
3. Mark all folders present in this repository (except `docs` and `lib`) as Sources Root folders (for some IDEs this step may not be necessary)
88+
4. Execute the `compile` target from the `build.xml` file present in the project folder, which performs lexical, syntactic, and semantic analysis.
89+
5. Run the [`Compiler.java`](test/rs/ac/bg/etf/pp1/Compiler.java) class, which will perform code generation and create the object file `test/test301.obj`. Before creating the object file, pass the following command-line arguments to the `Compiler.java`:
90+
```sh
91+
test/test301.mj test/test301.obj
92+
```
93+
6. After creating the object file, execute it by running the `runTest301` or `debugTest301` targets from the `build.xml`. They utilize the MicroJava VM implementation provided in the `lib/mj-runtime-1.1.jar` file.
94+
7. Consider changing the input value for the program `test/test301.mj`, which is located in the file `test/test301_input.txt`. By doing so or by modifying the code itself, it is possible to obtain different output values. The same test can be run for the file `test/program.mj`.
95+
96+
### Expected Output
97+
98+
```sh
99+
9 6 6 true b c -28
100+
```
101+
102+
<p align="right">(<a href="#top">back to top</a>)</p>
103+
104+
<!-- USAGE EXAMPLES -->
105+
## Usage
106+
107+
Since the execution of lexical, syntactic, and semantic analysis, as well as code generation, relies on the use of tools in the `lib` directory, executing the `compile` target from the `build.xml` file can also be done via the command line, as shown below.
108+
109+
**Parser generation**
110+
111+
A parser is generated based on the [CUP tool](lib/cup_v10k.jar), where for each grammar production, a corresponding class is generated in the `ast` folder in the `src/rs/ac/bg/etf/pp1` folder, enabling traversal of the syntax tree in subsequent compiler phases.
112+
The specification of the language grammar provided as input to this tool is defined in the `spec/mjparser.cup` file.
113+
114+
```sh
115+
java -jar lib/cup_v10k.jar -destdir src/rs/ac/bg/etf/pp1/ -ast src.rs.ac.bg.etf.pp1.ast -parser MJParser -buildtree spec/mjparser.cup
116+
```
117+
118+
After this, the `MJParser.java` class is generated in the `src/rs/ac/bg/etf/pp1` folder. It is necessary to change the package name to `rs.ac.bg.etf.pp1` in all files in the `ast` folder, as instructed in the `repackage` target in the `build.xml` file.
119+
120+
**Lexer generation**
121+
122+
By using the [JFlex tool](lib/JFlex.jar) with the lexer specification provided in the `spec/mjlexer.flex` file, a lexer class is generated into the file `YYlex.java`. Prior execution of the parser generation was necessary because it produces the `sym.java` class used in the mentioned specification.
123+
124+
```sh
125+
java -jar lib/JFlex.jar -d src/rs/ac/bg/etf/pp1/ spec/mjlexer.flex
126+
```
127+
128+
**Semantic analysis and code generation**
129+
130+
All of this is done through Java code by running the `Compiler.java` class, with `test/program.mj test/program.obj` passed to it as command-line arguments.
131+
132+
**Program execution**
133+
134+
The object file is executed using the MicroJava VM specified in the `lib\mj-runtime-1.1.jar` file, through the `Run` class.
135+
136+
```sh
137+
java -cp lib\mj-runtime-1.1.jar rs.etf.pp1.mj.runtime.Run test\program.obj
138+
```
139+
140+
It is also possible to disassemble the MicroJava code using the `disasm` class from the same file.
141+
142+
```sh
143+
java -cp lib\mj-runtime-1.1.jar rs.etf.pp1.mj.runtime.disasm test\program.obj
144+
```
145+
146+
**Expected output**
147+
```sh
148+
true 3
149+
```
150+
151+
<p align="right">(<a href="#top">back to top</a>)</p>
152+
153+
<!-- CONTRIBUTING -->
154+
## Contributing
155+
156+
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
157+
158+
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
159+
Don't forget to give the project a star! Thanks again!
160+
161+
1. Fork the Project
162+
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
163+
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
164+
4. Push to the Branch (`git push origin feature/AmazingFeature`)
165+
5. Open a Pull Request
166+
167+
<p align="right">(<a href="#top">back to top</a>)</p>
168+
169+
<!-- LICENSE -->
170+
## License
171+
172+
Distributed under the MIT License. See `LICENSE` for more information.
173+
174+
<p align="right">(<a href="#top">back to top</a>)</p>
175+
176+
<!-- CONTACT -->
177+
## Contact
178+
179+
Jovan - [@jovan-vukic](https://github.com/jovan-vukic)
180+
181+
Project Link: [https://github.com/jovan-vukic/microjava-compiler](https://github.com/jovan-vukic/microjava-compiler)
182+
183+
<p align="right">(<a href="#top">back to top</a>)</p>
184+
185+
<!-- ACKNOWLEDGMENTS -->
186+
## Acknowledgments
187+
188+
This project was done as part of the course 'Compiler Construction 1' (13E114PP1) at the University of Belgrade, Faculty of Electrical Engineering.
189+
190+
Used resources:
191+
192+
* [The full specification of the project in Serbian language](./docs/project%20specification.pdf)
193+
* [The MicroJava language specification in Serbian language](./docs/language%20specification.pdf)
194+
195+
<p align="right">(<a href="#top">back to top</a>)</p>

‎docs/language specification.pdf‎

5.57 MB
Binary file not shown.

‎docs/project specification.pdf‎

442 KB
Binary file not shown.

0 commit comments

Comments
 (0)