89 lines
4.7 KiB
Markdown
89 lines
4.7 KiB
Markdown
# The Translators α Compiler
|
||
#### Members: Annie Slenker, Meyer Simon, Partho Bhattacharya, & Scarlett Kadan
|
||
|
||
## Alpha Compiler Flags & Expected Results:
|
||
### -tok
|
||
Prints the token stream provided by the Lexical Analyzer to a `.tok` file. Output can be found in `/out/<file>.tok`. Tokenization follows the specified format found in the alpha language spec.
|
||
|
||
### -st
|
||
Prints the symbol table to a file. Follows the format provided in the alpha language spec. if the `-ir` flag is also present, the symbol table will print out temporary variables. Output can be found in `out/<file>.st`.
|
||
|
||
### -asc
|
||
Prints the annotated alpha source code to a file. Will display any syntax errors that are present below the line they occur on. If more than one error is present, the messages will stack. Output can be found in `out/<file>.asc`.
|
||
|
||
### -tc
|
||
Throws type check errors to the asc output file. If the `-asc` flag is not present, no errors will be displayed. Output can be found in `out/<file>.asc`
|
||
|
||
### -ir
|
||
Prints the intermediate code representation stream to a file. Output can be found in `out/<file>.ir`. This flag modifies the `-st` flag, allowing for temporary variables to print out.
|
||
|
||
### -cg
|
||
Prints the alpha program's unique x86 assembly to a `.s` file. Assembly stream is valid x86 code that can be assembled and linked with other .s files. Output can be found in `out/<file>.s`
|
||
|
||
### -debug
|
||
Prints debug messages to the console if present. Our debug messages utilizes a wrapper function for `printf()` called `printdebug()`. This allows for us to file names, code lines, and colors!
|
||
|
||
### -help
|
||
Prints a general help message. (If you read this far, you probably won't need this flag)
|
||
|
||
|
||
## Alpha Tools: Testing & Building
|
||
We have built a few tools to aid in the development processes. These include `./test.sh` and `./genx.sh`. Below you can find information about each.
|
||
|
||
### ./test.sh
|
||
All tests under sprint 1, 2, 3, & 4 will work with the testing suite, along with running it directly with the alpha executable. These files do not use the `#include` directive, instead opting to define everything used within the file.
|
||
> **Arguments:**</br>
|
||
> `-exp` Generate expected output files</br>
|
||
> `-diff` Compare output files with expected output files</br>
|
||
> `-help` Show this help message</br>
|
||
|
||
> **Usage:**</br>
|
||
> `./test.sh <file.alpha> [flags]` Run the test on a single file</br>
|
||
> `./test.sh <directory> [flags]` Run the test on all files in a directory</br>
|
||
|
||
> **Examples:** </br>
|
||
> `./test.sh test.alpha` Runs test flags in header on test.alpha</br>
|
||
> `./test.sh test/` Runs test flags in header on all .alpha files in test/</br>
|
||
> `./test.sh test/ -exp` Runs test flags in header on all .alpha files in test/ and generates expected output files</br>
|
||
> `./test.sh test/ -diff` Runs test flags in header on all .alpha files in test/ and compares output files with expected output files</br>
|
||
> `./test.sh test/ -exp -diff` Runs test flags in header on all .alpha files in test/ and generates expected output files and compares output files with expected output files</br>
|
||
|
||
> **Notes:**</br>
|
||
> To create a test file, on the first line of the .alpha file, add:</br>
|
||
> `(* TEST: [ <test_flags> ] *)`</br>
|
||
> where <test_flags> are the alpha flags to be used. Ex:</br>
|
||
> `(* TEST: [ -debug -asc -tc ] *)`</br>
|
||
|
||
### ./genx.sh
|
||
GenX is our preprocessor tool. It is able to handle `#include` statements within an alpha file. The tool allows for includes of `.alpha`, `.s`, and `.c` files, given a relative path to them. You can also include our library file `std.alpha` which does not require a relative path.</br>
|
||
|
||
**NOTE:** *Due to the nature of include statements, running the alpha compiler on alpha files that use include statements will most likely result in syntax/type errors. When dealing with a file with include statements, it is advised to use GenX.*</br>
|
||
|
||
*You can also use the following command to preprocess a file:* `cpp -P -x c -o simple.cpp.alpha simple.alpha`
|
||
|
||
> **Arguments:** </br>
|
||
> `-help` Displays this message</br>
|
||
|
||
> **Usage:** </br>
|
||
> `./genx.sh <file.alpha || file.s>` </br>Generates executable file from <file.alpha></br>
|
||
|
||
> **Notes:** </br>
|
||
> Generates .s and links alpha driver and general library and other includes.</br>
|
||
|
||
## Other Notes:
|
||
|
||
### Lexical Analyzer:
|
||
**Undefined Behavior:**</br>
|
||
* Spaces are not required between tokens. For instance, an INTEGER and an ID are valid even if there is no space between them
|
||
```
|
||
Input: *5variable*
|
||
Output: 2 14 301 "5"
|
||
1 1 101 "variable"
|
||
```
|
||
* Added an `#include` token to stop syntax errors from being reported on certain alpha files.
|
||
|
||
### CG/IR Not Implemented:
|
||
* Arrays
|
||
* And conditionals not tested
|
||
* While loops may or may not be working (More testing needed)
|
||
* *...and other small issues* |