[Blog Post] Add Blog post for Bril array & arguments extensions #429
Conversation
There was a problem hiding this comment.
Very nice, @AliceSzzze! This looks great. Thanks for the detailed narrative in the blog post! I just have a few scattered suggestions on the text.
Do you want to submit your additions back to the real Bril repo? It would be great to merge them! Both of these are things I can imagine being really useful for other people.
content/blog/2023-12-11-arrays-and-variable-arguments-in-Bril.md
Outdated
Show resolved
Hide resolved
| name = "Alice Sze" | ||
| +++ | ||
|
|
||
| # What was the goal? |
There was a problem hiding this comment.
I don't think you need to include section headings that directly mirror my bullet points from the syllabus. Remember that your imaginary audience here is people who are generally interested in compilers and your work but do not particularly care that this was done as a 6120 project. Do you think there's a different way to title these sections that would more accurately reflect the contents and help such a reader more quickly navigate your writing?
|
|
||
| # What was the goal? | ||
|
|
||
| The overall goal of my project is to improve the capabilities and the user experience of Bril. In particular, I set out to allow the `main` function in Bril to take a variable number of arguments (much like `argc` and `argv` in C/C++), and add support for arrays in the TypeScript compiler to Bril. I thought of adding variable arguments because we currently have to pack a fixed number of values into an array when writing Bril programs, which is not only extra effort but also limits us to testing a very specific set of inputs, e.g. an array of six elements. While it is not a huge modification, it does limit our ability to test our programs and to see the effect of our optimizations on larger inputs. I also included arrays in the TypeScript compiler because quite a few benchmarks are written using it, and I recall someone asking if arrays are supported for the first assignment. I hope that these extensions will make it ever so slightly easier for CS6120ers to write interesting programs in the future. |
There was a problem hiding this comment.
I recommend using a "," after occurrences of "e.g." and "i.e.". https://capra.cs.cornell.edu/styleguide/#egie
|
|
||
| # What did you do? | ||
| ### Variable Arguments | ||
| For the first extension, I modified the TypeScript compiler in `brili.ts`. I changed the function `parseMainArguments` to check if `main` takes an integer and a pointer as arguments, in that order. The pointer can be an `int`, `float`, `bool` or `char` pointer, and there is no restriction on the names of the arguments. If it does, the interpreter allocates an array for the command-line arguments, parses them according to the annotated type and stores them into the array. The name of the int argument will be bound to the size of the array and name of the pointer argument will be bound to the pointer to the array in the environment. The user can then use the two arguments like any other variables. When the program terminates, the interpreter frees the argument array since it is the one that allocated it. |
There was a problem hiding this comment.
"TypeScript compiler": I think you mean the reference interpreter?
|
|
||
| For this part, I modified the compiler in `ts2bril.ts`. First, I had to change `tsTypeToBril` so that array types are recognized in Bril. I used the TS typechecker to check if the given type is an array type. If so, we map it to the corresponding pointer type in Bril based on what the element type is in Bril. | ||
|
|
||
| Then, I changed `emitExpr` to be able to handle array operations. I started by adding a case in the switch statement for array literals, e.g. `{1, 2, 3}`. We evaluate the Bril type of the array, allocate an array in Bril and iterate over the array to store the elements. Next, I added a case for array indexing. To do this, we obtain Bril expressions for the array and the index by calling `emitExpr`, then create a pointer to the indexed element using `ptradd`. Indices are `number`s in TypeScript, but integers in Bril, which is a problem. The implementation currently accepts any `bigint`s as indices, but only `number` literals can be indices. So a programmer can either use `numbers[0n]` or `numbers[0]`, but `numbers[i]` only works if `i` has type `bigint`. The reason for this is that we can try to parse numeric literals as integers, but there is no narrowing operation for variables in Bril currently, and I am not sure if it would make sense for there to be one. This could be extended in the future. |
There was a problem hiding this comment.
"We evaluate the Bril type of the array, allocate an array in Bril": Seems like this is maybe missing some words… do you mean something like "to evaluate […], we generate code to […]"?
|
|
||
| For this part, I modified the compiler in `ts2bril.ts`. First, I had to change `tsTypeToBril` so that array types are recognized in Bril. I used the TS typechecker to check if the given type is an array type. If so, we map it to the corresponding pointer type in Bril based on what the element type is in Bril. | ||
|
|
||
| Then, I changed `emitExpr` to be able to handle array operations. I started by adding a case in the switch statement for array literals, e.g. `{1, 2, 3}`. We evaluate the Bril type of the array, allocate an array in Bril and iterate over the array to store the elements. Next, I added a case for array indexing. To do this, we obtain Bril expressions for the array and the index by calling `emitExpr`, then create a pointer to the indexed element using `ptradd`. Indices are `number`s in TypeScript, but integers in Bril, which is a problem. The implementation currently accepts any `bigint`s as indices, but only `number` literals can be indices. So a programmer can either use `numbers[0n]` or `numbers[0]`, but `numbers[i]` only works if `i` has type `bigint`. The reason for this is that we can try to parse numeric literals as integers, but there is no narrowing operation for variables in Bril currently, and I am not sure if it would make sense for there to be one. This could be extended in the future. |
There was a problem hiding this comment.
This honestly makes sense to me! It is a weird mismatch between TS and Bril in general that TS has only one type (number) that in Bril would intuitively cover two different types (int and float). So I have mostly (not entirely) made the decision to force TS programs to use two types (bigint and number) to distinguish.
| } | ||
| ``` | ||
|
|
||
| As you can see, there is quite a bit of redundant and dead code due to the way expressions are evaluated in the compiler, but it should be easily eliminated with optimizations. |
There was a problem hiding this comment.
And in general, the TS-to-Bril compiler already gleefully emits a lot of dead code!
|
|
||
|
|
||
| # What were the hardest parts to get right? | ||
| The compiler extension was much trickier than the variable argument one. For the longest time, I did not realize that the link to the declaration file `typescript.d.ts` was broken, because the link to the rest of the code was not. This meant that the compiler was mostly working without it except in a few places, and when I added arrays I thought I must have done something wrong. I wasn't really familiar with the setup of TypeScript and there is very little documentation and few StackOverflow posts on the public TS compiler API, so I was stuck on that part for awhile. It also took some time to find the correct `functions` or `SyntaxKind` for my use cases, as I had to comb through the TypeScript codebase or rely on print statements. For anyone who is going to work with the TypeScript AST, I highly recommend the [AST viewer](https://ts-ast-viewer.com/#). |
There was a problem hiding this comment.
If you still have them in your history, do you think you could include a couple of links to StackOverflow posts that helped you?
|
|
||
|
|
||
| # What were the hardest parts to get right? | ||
| The compiler extension was much trickier than the variable argument one. For the longest time, I did not realize that the link to the declaration file `typescript.d.ts` was broken, because the link to the rest of the code was not. This meant that the compiler was mostly working without it except in a few places, and when I added arrays I thought I must have done something wrong. I wasn't really familiar with the setup of TypeScript and there is very little documentation and few StackOverflow posts on the public TS compiler API, so I was stuck on that part for awhile. It also took some time to find the correct `functions` or `SyntaxKind` for my use cases, as I had to comb through the TypeScript codebase or rely on print statements. For anyone who is going to work with the TypeScript AST, I highly recommend the [AST viewer](https://ts-ast-viewer.com/#). |
There was a problem hiding this comment.
I had not seen that AST viewer! That's pretty cool. It would have saved me a lot of time in my days of hacking on TS compiler internals…
Co-authored-by: Adrian Sampson <adrian@radbox.org>
closes #403