mirror of https://github.com/boa-dev/boa.git
Iban Eguia
5 years ago
committed by
GitHub
3 changed files with 98 additions and 69 deletions
@ -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…
Reference in new issue