-
-
Notifications
You must be signed in to change notification settings - Fork 116
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore(docs): Update compiler walkthrough #2092
base: main
Are you sure you want to change the base?
chore(docs): Update compiler walkthrough #2092
Conversation
/ \ | ||
1 2 | ||
``` | ||
|
||
Writing a parser by hand is great when you've got a stable grammar, but the language is still rapidly evolving. Using a parser generator allows us to iterate quickly. [Menhir](http://gallium.inria.fr/~fpottier/menhir/) is an excellent production-grade parser generator that produces OCaml code for a parser based on some rules we've defined. We call these rules a "grammar" and you can find the grammar for the Grain language in [parsing/parser.mly](https://github.com/grain-lang/grain/blob/main/compiler/src/parsing/parser.mly). If you'd like to learn more about BNF grammars, check out [this resource](http://people.cs.ksu.edu/~schmidt/300s05/Lectures/GrammarNotes/bnf.html). | ||
Writing a parser by hand is great when you've got a stable grammar, but as grain is in rapid development and we're always trying to improve the developer experience, We've decided to use a parser generator. [Menhir](http://gallium.inria.fr/~fpottier/menhir/) is an excellent production-grade parser generator that produces OCaml code for a parser based on some rules we've defined. We call these rules a "grammar" and you can find the grammar for the Grain language in [parsing/parser.mly](https://github.com/grain-lang/grain/blob/main/compiler/src/parsing/parser.mly). If you'd like to learn more about BNF grammars, check out [this resource](http://people.cs.ksu.edu/~schmidt/300s05/Lectures/GrammarNotes/bnf.html). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we mention the parser.messages
file?
## An overview of the compiler | ||
|
||
The grain compiler is a [multi-stage](https://en.wikipedia.org/wiki/Multi-pass_compiler) compiler, which means instead of converting directly from `grain syntax` into `wasm` we take multiple passes over the input program performing smaller transformations until we get to the final output. This approach allows us to have a more maintainable compiler and perform deeper analysis on your code which allows us to provide better errors and more abstraction. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thoughts on adding something like:
* `src/codegen`: This folder contains everything related to generating wasm output.
* `src/diagnostics`:
* `src/formatting`: This folder contains everthing related to the `grain format` command.
This would provide a quick overview of each folder and its purpose helping to make the compiler more navigatable to interested contributers.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That sounds good to me.
Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>
Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>
Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>
Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>
Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>
Co-authored-by: Oscar Spencer <oscar.spen@gmail.com>
This pr updates the compiler walkthrough docs as they have gotten quite out of date, I think there are quite a few places where more detail could be added but I don't feel I have the background to properly describe them in depth.
I tried to include a lot more wiki links as though compiler development is mostly going to be targetted towards developers with some experience, it's still beneficial for newer contributers who are interested to have a place to start.