Browse Source

Updated contribution documentation (#297)

pull/305/head
Iban Eguia 5 years ago committed by GitHub
parent
commit
48ab045ac2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 49
      CONTRIBUTING.md
  2. 39
      README.md
  3. 79
      docs/debugging.md

49
CONTRIBUTING.md

@ -15,31 +15,62 @@ Should you wish to work on an issue, please claim it first by commenting on
the GitHub issue that you want to work on it. This is to prevent duplicated the GitHub issue that you want to work on it. This is to prevent duplicated
efforts from contributors on the same issue. efforts from contributors on the same issue.
Head over to [issues](https://github.com/jasonwilliams/boa/issues) and check for "good first issue" labels to find Head over to [issues][issues] and check for "good first issue" labels to find
good tasks to start with. If you come across words or jargon that do not make good tasks to start with. If you come across words or jargon that do not make
sense, please ask! sense, please ask!
If you don't already have Rust installed rustup is the recommended tool to use. It will install Rust and allow you to switch between nightly, stable and beta. You can also install additional components. If you don't already have Rust installed [_rustup_][rustup] is the recommended
tool to use. It will install Rust and allow you to switch between _nightly_,
_stable_ and _beta_. You can also install additional components. In Linux, you
can run:
`curl https://sh.rustup.rs -sSf | sh` ```
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Then simply clone this project and `cargo build` Then simply clone this project and `cargo build`.
### Debugging ### Running the compiler
You can execute a Boa console by running `cargo run`, and you can compile a list
of JavaScript files by running `cargo run -- file1.js file2.js` and so on.
Knowing how to debug the interpreter should help you resolve problems quite quickly.\ ### Debugging
See [Debugging](docs/debugging.md)
Knowing how to debug the interpreter should help you resolve problems quite quickly.
See [Debugging](./docs/debugging.md).
### Web Assembly ### Web Assembly
If you want to develop on the web assembly side you can run yarn serve then go to http://localhost:8080 If you want to develop on the web assembly side you can run `yarn serve` and then go
to <http://localhost:8080>.
### Setup ### Setup
VScode is commonly used with the [Rust (RLS) plugin](https://github.com/rust-lang/rls-vscode). #### VSCode Plugins
Either the [Rust (RLS)][rls_vscode] or the [Rust Analyzer][rust-analyzer_vscode]
extensions are preferred. RLS is easier to set up but some of the development is
moving towards Rust Analyzer. Both of these plugins will help you with your Rust
Development
#### Tasks
There are some pre-defined tasks in [tasks.json](.vscode/tasks.json)
- Build - shift+cmd/ctrl+b should build and run cargo. You should be able to make changes and run this task.
- Test - (there is no shortcut, you'll need to make one) - Runs `Cargo Test`.
I personally set a shortcut of shift+cmd+option+T (or shift+ctrl+alt+T)
If you don't want to install everything on your machine, you can use the Dockerfile.
Start VSCode in container mode (you may need the docker container plugin) and use the Dockerfile.
## Communication ## Communication
We have a Discord server, feel free to ask questions here: We have a Discord server, feel free to ask questions here:
https://discord.gg/tUFFk9Y https://discord.gg/tUFFk9Y
[issues]: https://github.com/jasonwilliams/boa/issues
[rustup]: https://rustup.rs/
[rls_vscode]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust
[rust-analyzer_vscode]: https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer

39
README.md

@ -1,14 +1,15 @@
# Boa # Boa
<p align="center"> <p style="text-align:center">
<img <img
alt="logo" alt="logo"
src="./assets/logo.svg" src="./assets/logo.svg"
width="30%" width="30%">
/>
</p> </p>
This is an experimental Javascript lexer, parser and compiler written in Rust. Currently, it has support for some of the language. This is an experimental Javascript lexer, parser and compiler written in Rust.
Currently, it has support for some of the language.
[![Build Status](https://travis-ci.com/jasonwilliams/boa.svg?branch=master)](https://travis-ci.com/jasonwilliams/boa) [![Build Status](https://travis-ci.com/jasonwilliams/boa.svg?branch=master)](https://travis-ci.com/jasonwilliams/boa)
[![](http://meritbadge.herokuapp.com/boa)](https://crates.io/crates/boa) [![](http://meritbadge.herokuapp.com/boa)](https://crates.io/crates/boa)
[![](https://docs.rs/Boa/badge.svg)](https://docs.rs/Boa/) [![](https://docs.rs/Boa/badge.svg)](https://docs.rs/Boa/)
@ -25,35 +26,13 @@ https://jasonwilliams.github.io/boa/dev/bench/
## Contributing ## Contributing
If you don't already have Rust installed rustup is the recommended tool to use. It will install Rust and allow you to switch between nightly, stable and beta. You can also install additional components. Please, check the [CONTRIBUTING.md](./Contributing.md) file to know how to
contribute in the project. You will need Rust installed and an editor. We have
``` some configurations ready for VSCode.
curl https://sh.rustup.rs -sSf | sh
```
Then simply clone this project and `cargo build` inside the directory.
### VSCode
#### Plugins
Either the [Rust (RLS)](https://github.com/rust-lang/rls) or the [Rust Analyzer](https://github.com/rust-analyzer/rust-analyzer) extension is preferred. RLS is easier to set up but most of the development is moving towards Rust Analyzer.
Both of these plugins will help you with your Rust Development
#### Tasks
There are some pre-defined tasks in [tasks.json](.vscode/tasks.json)
- Build - shift+cmd/ctrl+b should build and run cargo. You should be able to make changes and run this task.
- Test - (there is no shortcut, you'll need to make one) - Runs `Cargo Test`.
I personally set a shortcut of shift+cmd+option+T (or shift+ctrl+alt+T)
If you don't want to install everything on your machine, you can use the Dockerfile.
Start VSCode in container mode (you may need the docker container plugin) and use the Dockerfile.
### Debugging ### Debugging
See [Debugging](./docs/debugging.md) See [Debugging](./docs/debugging.md).
### Web Assembly ### Web Assembly

79
docs/debugging.md

@ -1,72 +1,91 @@
# Debugging # Debugging
There are multiple ways to debug what Boa is doing. Or maybe you just want to know how it works under the hood. Or even test some JavaScript. There are multiple ways to debug what Boa is doing. Or maybe you just want to
know how it works under the hood. Or even test some JavaScript.
One way to do so is to create a file in the root of the repository. For example `test.js`. Then execute `cargo run -- test.js` to run the file with boa. One way to do so is to create a file in the root of the repository. For example
`test.js`. Then execute `cargo run -- test.js` to run the file with boa. You can
compile a list of JavaScript files by running `cargo run -- file1.js file2.js`
and so on.
You can also run boa interactively by simply calling `cargo run` without any arguments to start a shell to execute JS. You can also run boa interactively by simply calling `cargo run` without any
arguments to start a shell to execute JS.
These are added in order of how the code is read: These are added in order of how the code is read:
## Tokens ## Tokens
The first thing boa will do is generate tokens from source code. The first thing boa will do is generate tokens from source code. If the token
If the token generation is wrong the rest of the operation will be wrong, this is usually a good starting place. generation is wrong the rest of the operation will be wrong, this is usually
a good starting place.
To print the tokens to stdout, you can use the `boa_cli` command-line flag `--dump-tokens`, which can optionally take a format type. Supports these formats: `Debug`, `Json`, `JsonPretty`. By default it is the `Debug` format. To print the tokens to stdout, you can use the `boa_cli` command-line flag
`--dump-tokens` or `-t`, which can optionally take a format type. Supports
these formats: `Debug`, `Json`, `JsonPretty`. By default it is the `Debug`
format.
```bash ```bash
cargo run -- test.js --dump-tokens # token dump format is Debug by default. cargo run -- test.js --dump-tokens # token dump format is Debug by default.
``` ```
or with interactive mode (REPL): or with interactive mode (REPL):
```bash ```bash
cargo run -- --dump-tokens # token dump format is Debug by default. cargo run -- --dump-tokens # token dump format is Debug by default.
``` ```
Seeing the order of tokens can be a big help to understanding what the parser
is working with.
Or you can do it manually by navigating to `parser_expr` in [lib.rs](../boa/src/lib.rs#L25) and add `dbg!(&tokens);` just below tokens to see the array of token output. You code should look like this: **Note:** flags `--dump-tokens` and `--dump-ast` are mutually exclusive. When
using the flag `--dump-tokens`, the code will not be executed.
```rust
let mut lexer = Lexer::new(src);
lexer.lex().expect("lexing failed");
let tokens = lexer.tokens;
dbg!(&tokens);
...
```
Seeing the order of tokens can be a big help to understanding what the parser is working with.
**Note:** flags `--dump-tokens` and `--dump-ast` are mutually exclusive. When using the flag `--dump-tokens`, the code will not be executed.
## Expressions ## AST nodes
Assuming the tokens looks fine, the next step is to see the AST. Assuming the tokens looks fine, the next step is to see the AST. You can use
You can use the `boa_cli` command-line flag `--dump-ast`, which can optionally take a format type. Supports these formats: `Debug`, `Json`, `JsonPretty`. By default it is the `Debug` format. the `boa_cli` command-line flag `--dump-ast`, which can optionally take a
format type. Supports these formats: `Debug`, `Json`, `JsonPretty`. By default
it is the `Debug` format.
Dumping the AST of a file: Dumping the AST of a file:
```bash ```bash
cargo run -- test.js --dump-ast # AST dump format is Debug by default. cargo run -- test.js --dump-ast # AST dump format is Debug by default.
``` ```
or with interactive mode (REPL): or with interactive mode (REPL):
```bash ```bash
cargo run -- --dump-ast # AST dump format is Debug by default. cargo run -- --dump-ast # AST dump format is Debug by default.
``` ```
Or manually, you can output the expressions in [forward](../boa/src/lib.rs#L36), add `dbg!(&expr);`
These methods will print out the entire parse tree. These methods will print out the entire parse tree.
**Note:** flags `--dump-tokens` and `--dump-ast` are mutually exclusive. When using the flag `--dump-ast`, the code will not be executed. **Note:** flags `--dump-tokens` and `--dump-ast` are mutually exclusive. When
using the flag `--dump-ast`, the code will not be executed.
## Compiler panics
In the case of a compiler panic, to get a full backtrace you will need to set
the environment variable `RUST_BACKTRACE=1`.
## Execution ## Execution
Once the tree has been generated [exec](../boa/src/lib.rs#L67) will begin to run through each expression. If the tokens and tree looks fine, you can start looking here. Once the tree has been generated [exec](../boa/src/lib.rs#L92) will begin to
I usually just add `dbg!()` in the relevent places to see what the output is at the time. run through each node. If the tokens and tree looks fine, you can start looking
here. We usually just add `dbg!()` in the relevent places to see what the
output is at the time.
## Debugger ## Debugger
### VS Code Debugger ### VS Code Debugger
The quickest way to get debugging is to re-open the workspace in the container (using the Dockerfile provided). This is using the [Remote Containers plugin](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). Once inside make sure you have the CodeLLDB extension installed and add breakpoints. The quickest way to get debugging is to use the CodeLLDB plugin and add breakpoints. You can get
more information [here][blog_debugging].
### LLDB Manual debugging
You can also use rust-lldb. The `Dockerfile` already has this enabled, you
should be able to use that environment to run your code.
### LLDB Manually ```
rust-lldb ./target/debug/boa [arguments]
```
You can also use rust-lldb. [remote_containers]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
The `Dockerfile` already has this enabled, you should be able to use that environment to run your code. [blog_debugging]: https://jason-williams.co.uk/debugging-rust-in-vscode
`rust-lldb ./target/debug/boa [arguments]`
Loading…
Cancel
Save