From 25dd67f4d3f86185cb2cb1a910b76f8ff62cea51 Mon Sep 17 00:00:00 2001
From: Jason Williams <jwilliams720@bloomberg.net>
Date: Tue, 24 Sep 2019 18:19:16 +0100
Subject: [PATCH] adding debugging section to docs

---
 README.md         |  6 +++++-
 docs/debugging.md | 48 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 1 deletion(-)
 create mode 100644 docs/debugging.md

diff --git a/README.md b/README.md
index bba20e7fa7..6954bbf2f0 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,10 @@ curl https://sh.rustup.rs -sSf | sh
 Then simply clone this project and `cargo build`
 To develop on the web assembly side you can run `yarn serve` then go to `http://localhost:8080`
 
+#### Debugging
+
+See [Debugging](./docs/debugging.md)
+
 #### VSCode and Dockerfile
 
 If you don't want to install everything on your machine, you can use the Dockerfile.
@@ -53,7 +57,7 @@ See Project view
 - You can make changes to tests/js/test.js and build again
 - If any JS doesn't work its a bug! Please raise an issue
 
-#### Communication 
+#### Communication
 
 Feel free to contact us on Discord https://discord.gg/tUFFk9Y
 
diff --git a/docs/debugging.md b/docs/debugging.md
new file mode 100644
index 0000000000..0c5f5d5aae
--- /dev/null
+++ b/docs/debugging.md
@@ -0,0 +1,48 @@
+# 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.
+
+The first thing i usually do is add some JS [here](../tests/js/test.js).  
+This file will be read if no arguments are provided. Then boa will begin to parse and execute that JS.
+
+These are added in order of how the code is read:
+
+## Tokens
+
+The first thing boa will do is generate tokens from source code.  
+If the token generation is wrong the rest of the operation will be wrong, this is usually a good starting place.
+
+Navigate to `parser_expr` in [lib.rs](../src/lib/lib.rs#L48) and add `dbg!(&tokens);` just below tokens to see the array of token output. You code should look like this:
+
+```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.
+
+## Expressions
+
+Assuming the tokens looks fine, the next step is to see the AST.
+You can output the expressions in [forward](../src/lib/lib.rs#L57), add `dbg!(&expr);`
+This will print out the entire parse tree.
+
+## Execution
+
+Once the tree has been generated [exec](../src/lib/exec.rs#L66) will begin to run through each expression. If the tokens and tree looks fine, you can start looking here.  
+I usually just add `dbg!()` in the relevent places to see what the output is at the time.
+
+## 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.
+
+### LLDB Manually
+
+You can also use rust-lldb.  
+The `Dockerfile` already has this enabled, you should be able to use that environment to run your code.  
+`rust-lldb ./target/debug/boa [arguments]`