feat: add dependency
This commit is contained in:
107
javascript-engine/external/boa/docs/debugging.md
vendored
Normal file
107
javascript-engine/external/boa/docs/debugging.md
vendored
Normal file
@@ -0,0 +1,107 @@
|
||||
# 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.
|
||||
|
||||
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.
|
||||
|
||||
These are added in order of how the code is read:
|
||||
|
||||
## Tokens and AST nodes
|
||||
|
||||
The first thing boa will do is to generate tokens from the source code.
|
||||
These tokens are then parsed into an abstract syntax tree (AST).
|
||||
Any syntax errors should be thrown while the AST is generated.
|
||||
|
||||
You can use the `boa_cli` command-line flag `--dump-ast` to print the AST.
|
||||
The flag supports these formats: `Debug`, `Json`, `JsonPretty`. By default
|
||||
it is the `Debug` format.
|
||||
|
||||
Dumping the AST of a file:
|
||||
|
||||
```bash
|
||||
cargo run -- test.js --dump-ast # AST dump format is Debug by default.
|
||||
```
|
||||
|
||||
or with interactive mode (REPL):
|
||||
|
||||
```bash
|
||||
cargo run -- --dump-ast # AST dump format is Debug by default.
|
||||
```
|
||||
|
||||
## Bytecode generation and Execution
|
||||
|
||||
Once the AST has been generated boa will compile it into bytecode.
|
||||
The bytecode is then executed by the vm.
|
||||
You can print the bytecode and the executed instructions with the command-line flag `--trace`.
|
||||
|
||||
For more detailed information about the vm and the trace output look [here](./vm.md).
|
||||
|
||||
## Instruction flowgraph
|
||||
|
||||
We can to get the vm instructions flowgraph, which is a visual representation of the instruction flow.
|
||||
|
||||
The `Start` (in green) and `End` (in red) node in the graph represents the start and end point of execution.
|
||||
They are not instructions, just markers.
|
||||
|
||||
The conditional instructions are diamond shaped, with the `"YES"` branch in green and the `"NO"` branch in red.
|
||||
The push and pop evironment pairs match colors and are connected by a dotted line.
|
||||
|
||||
You can use the `--flowgraph` (or `--flowgraph=mermaid` for [mermaid][mermaid] format) flag which outputs
|
||||
[graphviz][graphviz] format by default, and pipe it to `dot` (from the `graphviz` package which is installed
|
||||
on most linux distros by default) or use an online editor like: <https://dreampuf.github.io/GraphvizOnline> to
|
||||
view the graph.
|
||||
|
||||
```bash
|
||||
cargo run -- test.js --flowgraph | dot -Tpng > test.png
|
||||
```
|
||||
|
||||
You can specify the `-Tsvg` to generate a `svg` instead of a `png` file.
|
||||
|
||||
|
||||
|
||||
Mermaid graphs can be displayed on github [natively without third-party programs][gihub-mermaid].
|
||||
By using a `mermaid` block as seen below.
|
||||
|
||||
````
|
||||
```mermaid
|
||||
// graph contents here...
|
||||
```
|
||||
````
|
||||
|
||||
Additionaly you can specify the direction of "flow" by using the `--flowgraph-direction` cli option,
|
||||
for example `--flowgraph-direction=left-to-right`, the default is `top-to-bottom`.
|
||||
|
||||
[mermaid]: https://mermaid-js.github.io/
|
||||
[gihub-mermaid]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
|
||||
[graphviz]: https://graphviz.org/
|
||||
|
||||
## 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`.
|
||||
|
||||
## Debugger
|
||||
|
||||
### VS Code Debugger
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
rust-lldb ./target/debug/boa [arguments]
|
||||
```
|
||||
|
||||
[remote_containers]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
|
||||
[blog_debugging]: https://jason-williams.co.uk/debugging-rust-in-vscode
|
||||
BIN
javascript-engine/external/boa/docs/img/boaTest.gif
vendored
Normal file
BIN
javascript-engine/external/boa/docs/img/boaTest.gif
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 705 KiB |
BIN
javascript-engine/external/boa/docs/img/boa_architecture.drawio.png
vendored
Normal file
BIN
javascript-engine/external/boa/docs/img/boa_architecture.drawio.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
333
javascript-engine/external/boa/docs/img/graphviz_flowgraph.svg
vendored
Normal file
333
javascript-engine/external/boa/docs/img/graphviz_flowgraph.svg
vendored
Normal file
@@ -0,0 +1,333 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
|
||||
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
|
||||
<!-- Generated by graphviz version 7.0.1 (0)
|
||||
-->
|
||||
<!-- Pages: 1 -->
|
||||
<svg width="2868pt" height="197pt"
|
||||
viewBox="0.00 0.00 2867.57 197.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 193)">
|
||||
<polygon fill="white" stroke="none" points="-4,4 -4,-193 2863.57,-193 2863.57,4 -4,4"/>
|
||||
<g id="clust1" class="cluster">
|
||||
<title>cluster___main__</title>
|
||||
<polygon fill="lightgrey" stroke="black" points="8,-8 8,-181 2851.57,-181 2851.57,-8 8,-8"/>
|
||||
<text text-anchor="middle" x="1429.79" y="-165.8" font-family="Times,serif" font-size="14.00">__main__</text>
|
||||
</g>
|
||||
<!-- __main___start -->
|
||||
<g id="node1" class="node">
|
||||
<title>__main___start</title>
|
||||
<polygon fill="green" stroke="green" points="54.6,-108 15.9,-90 54.6,-72 93.31,-90 54.6,-108"/>
|
||||
<polyline fill="none" stroke="green" points="26.78,-95.06 26.78,-84.94"/>
|
||||
<polyline fill="none" stroke="green" points="43.72,-77.06 65.49,-77.06"/>
|
||||
<polyline fill="none" stroke="green" points="82.43,-84.94 82.43,-95.06"/>
|
||||
<polyline fill="none" stroke="green" points="65.49,-102.94 43.72,-102.94"/>
|
||||
<text text-anchor="middle" x="54.6" y="-86.3" font-family="Times,serif" font-size="14.00">Start</text>
|
||||
</g>
|
||||
<!-- __main___i_0 -->
|
||||
<g id="node2" class="node">
|
||||
<title>__main___i_0</title>
|
||||
<polygon fill="none" stroke="black" points="130.21,-72 130.21,-108 240.21,-108 240.21,-72 130.21,-72"/>
|
||||
<text text-anchor="middle" x="185.21" y="-86.3" font-family="Times,serif" font-size="14.00">0000: PushInt8 3</text>
|
||||
</g>
|
||||
<!-- __main___start->__main___i_0 -->
|
||||
<g id="edge1" class="edge">
|
||||
<title>__main___start->__main___i_0</title>
|
||||
<path fill="none" stroke="black" d="M94.19,-90C102.02,-90 110.47,-90 118.93,-90"/>
|
||||
<polygon fill="black" stroke="black" points="118.92,-93.5 128.92,-90 118.92,-86.5 118.92,-93.5"/>
|
||||
</g>
|
||||
<!-- __main___i_2 -->
|
||||
<g id="node3" class="node">
|
||||
<title>__main___i_2</title>
|
||||
<polygon fill="none" stroke="black" points="277.21,-72 277.21,-108 397.21,-108 397.21,-72 277.21,-72"/>
|
||||
<text text-anchor="middle" x="337.21" y="-86.3" font-family="Times,serif" font-size="14.00">0002: DefInitLet 'i'</text>
|
||||
</g>
|
||||
<!-- __main___i_0->__main___i_2 -->
|
||||
<g id="edge2" class="edge">
|
||||
<title>__main___i_0->__main___i_2</title>
|
||||
<path fill="none" stroke="black" d="M239.94,-90C248.36,-90 257.16,-90 265.88,-90"/>
|
||||
<polygon fill="black" stroke="black" points="265.75,-93.5 275.75,-90 265.75,-86.5 265.75,-93.5"/>
|
||||
</g>
|
||||
<!-- __main___i_7 -->
|
||||
<g id="node4" class="node">
|
||||
<title>__main___i_7</title>
|
||||
<polygon fill="none" stroke="black" points="434.21,-72 434.21,-108 550.21,-108 550.21,-72 434.21,-72"/>
|
||||
<text text-anchor="middle" x="492.21" y="-86.3" font-family="Times,serif" font-size="14.00">0007: GetName 'i'</text>
|
||||
</g>
|
||||
<!-- __main___i_2->__main___i_7 -->
|
||||
<g id="edge3" class="edge">
|
||||
<title>__main___i_2->__main___i_7</title>
|
||||
<path fill="none" stroke="black" d="M396.93,-90C405.48,-90 414.35,-90 423.07,-90"/>
|
||||
<polygon fill="black" stroke="black" points="422.9,-93.5 432.9,-90 422.9,-86.5 422.9,-93.5"/>
|
||||
</g>
|
||||
<!-- __main___i_12 -->
|
||||
<g id="node5" class="node">
|
||||
<title>__main___i_12</title>
|
||||
<polygon fill="none" stroke="black" points="587.21,-72 587.21,-108 703.21,-108 703.21,-72 587.21,-72"/>
|
||||
<text text-anchor="middle" x="645.21" y="-86.3" font-family="Times,serif" font-size="14.00">0012: PushInt8 10</text>
|
||||
</g>
|
||||
<!-- __main___i_7->__main___i_12 -->
|
||||
<g id="edge4" class="edge">
|
||||
<title>__main___i_7->__main___i_12</title>
|
||||
<path fill="none" stroke="black" d="M549.87,-90C558.36,-90 567.2,-90 575.9,-90"/>
|
||||
<polygon fill="black" stroke="black" points="575.72,-93.5 585.72,-90 575.72,-86.5 575.72,-93.5"/>
|
||||
</g>
|
||||
<!-- __main___i_14 -->
|
||||
<g id="node6" class="node">
|
||||
<title>__main___i_14</title>
|
||||
<polygon fill="none" stroke="black" points="740.21,-72 740.21,-108 844.21,-108 844.21,-72 740.21,-72"/>
|
||||
<text text-anchor="middle" x="792.21" y="-86.3" font-family="Times,serif" font-size="14.00">0014: LessThan</text>
|
||||
</g>
|
||||
<!-- __main___i_12->__main___i_14 -->
|
||||
<g id="edge5" class="edge">
|
||||
<title>__main___i_12->__main___i_14</title>
|
||||
<path fill="none" stroke="black" d="M703.1,-90C711.71,-90 720.62,-90 729.33,-90"/>
|
||||
<polygon fill="black" stroke="black" points="729.09,-93.5 739.09,-90 729.09,-86.5 729.09,-93.5"/>
|
||||
</g>
|
||||
<!-- __main___i_15 -->
|
||||
<g id="node7" class="node">
|
||||
<title>__main___i_15</title>
|
||||
<polygon fill="none" stroke="black" points="1006.21,-108 881.2,-90 1006.21,-72 1131.23,-90 1006.21,-108"/>
|
||||
<text text-anchor="middle" x="1006.21" y="-86.3" font-family="Times,serif" font-size="14.00">0015: JumpIfFalse 53</text>
|
||||
</g>
|
||||
<!-- __main___i_14->__main___i_15 -->
|
||||
<g id="edge6" class="edge">
|
||||
<title>__main___i_14->__main___i_15</title>
|
||||
<path fill="none" stroke="black" d="M843.99,-90C851.15,-90 858.78,-90 866.67,-90"/>
|
||||
<polygon fill="black" stroke="black" points="866.47,-93.5 876.47,-90 866.47,-86.5 866.47,-93.5"/>
|
||||
</g>
|
||||
<!-- __main___i_20 -->
|
||||
<g id="node8" class="node">
|
||||
<title>__main___i_20</title>
|
||||
<polygon fill="#48f379" stroke="#48f379" points="1193.22,-45 1193.22,-81 1429.22,-81 1429.22,-45 1193.22,-45"/>
|
||||
<text text-anchor="middle" x="1311.22" y="-59.3" font-family="Times,serif" font-size="14.00">0020: PushDeclarativeEnvironment 0, 0</text>
|
||||
</g>
|
||||
<!-- __main___i_15->__main___i_20 -->
|
||||
<g id="edge8" class="edge">
|
||||
<title>__main___i_15->__main___i_20</title>
|
||||
<path fill="none" stroke="red" d="M1081.63,-82.41C1103.41,-80.26 1127.26,-77.97 1149.22,-76 1159.9,-75.04 1170.99,-74.08 1182.12,-73.14"/>
|
||||
<polygon fill="red" stroke="red" points="1182.07,-76.65 1191.74,-72.33 1181.48,-69.68 1182.07,-76.65"/>
|
||||
<text text-anchor="middle" x="1162.22" y="-79.8" font-family="Times,serif" font-size="14.00">NO</text>
|
||||
</g>
|
||||
<!-- __main___i_53 -->
|
||||
<g id="node17" class="node">
|
||||
<title>__main___i_53</title>
|
||||
<polygon fill="#6148f3" stroke="#6148f3" points="1193.22,-100 1193.22,-136 1429.22,-136 1429.22,-100 1193.22,-100"/>
|
||||
<text text-anchor="middle" x="1311.22" y="-114.3" font-family="Times,serif" font-size="14.00">0053: PushDeclarativeEnvironment 0, 1</text>
|
||||
</g>
|
||||
<!-- __main___i_15->__main___i_53 -->
|
||||
<g id="edge7" class="edge">
|
||||
<title>__main___i_15->__main___i_53</title>
|
||||
<path fill="none" stroke="green" d="M1084.85,-97.17C1114.47,-99.91 1149.07,-103.11 1182.15,-106.17"/>
|
||||
<polygon fill="green" stroke="green" points="1181.51,-109.62 1191.79,-107.06 1182.15,-102.65 1181.51,-109.62"/>
|
||||
<text text-anchor="middle" x="1162.22" y="-107.8" font-family="Times,serif" font-size="14.00">YES</text>
|
||||
</g>
|
||||
<!-- __main___i_29 -->
|
||||
<g id="node9" class="node">
|
||||
<title>__main___i_29</title>
|
||||
<polygon fill="none" stroke="black" points="1466.22,-17 1466.22,-53 1603.22,-53 1603.22,-17 1466.22,-17"/>
|
||||
<text text-anchor="middle" x="1534.72" y="-31.3" font-family="Times,serif" font-size="14.00">0029: GetName 'print'</text>
|
||||
</g>
|
||||
<!-- __main___i_20->__main___i_29 -->
|
||||
<g id="edge9" class="edge">
|
||||
<title>__main___i_20->__main___i_29</title>
|
||||
<path fill="none" stroke="black" d="M1429.13,-48.22C1437.93,-47.11 1446.67,-46 1455.14,-44.93"/>
|
||||
<polygon fill="black" stroke="black" points="1455.51,-48.41 1464.99,-43.69 1454.63,-41.47 1455.51,-48.41"/>
|
||||
</g>
|
||||
<!-- __main___i_34 -->
|
||||
<g id="node10" class="node">
|
||||
<title>__main___i_34</title>
|
||||
<polygon fill="none" stroke="black" points="1640.22,-17 1640.22,-53 1774.22,-53 1774.22,-17 1640.22,-17"/>
|
||||
<text text-anchor="middle" x="1707.22" y="-31.3" font-family="Times,serif" font-size="14.00">0034: PushUndefined</text>
|
||||
</g>
|
||||
<!-- __main___i_29->__main___i_34 -->
|
||||
<g id="edge10" class="edge">
|
||||
<title>__main___i_29->__main___i_34</title>
|
||||
<path fill="none" stroke="black" d="M1603.11,-35C1611.65,-35 1620.44,-35 1629.12,-35"/>
|
||||
<polygon fill="black" stroke="black" points="1628.92,-38.5 1638.92,-35 1628.92,-31.5 1628.92,-38.5"/>
|
||||
</g>
|
||||
<!-- __main___i_35 -->
|
||||
<g id="node11" class="node">
|
||||
<title>__main___i_35</title>
|
||||
<polygon fill="none" stroke="black" points="1811.22,-17 1811.22,-53 1892.22,-53 1892.22,-17 1811.22,-17"/>
|
||||
<text text-anchor="middle" x="1851.72" y="-31.3" font-family="Times,serif" font-size="14.00">0035: Swap</text>
|
||||
</g>
|
||||
<!-- __main___i_34->__main___i_35 -->
|
||||
<g id="edge11" class="edge">
|
||||
<title>__main___i_34->__main___i_35</title>
|
||||
<path fill="none" stroke="black" d="M1774.05,-35C1782.87,-35 1791.81,-35 1800.31,-35"/>
|
||||
<polygon fill="black" stroke="black" points="1800.07,-38.5 1810.07,-35 1800.07,-31.5 1800.07,-38.5"/>
|
||||
</g>
|
||||
<!-- __main___i_36 -->
|
||||
<g id="node12" class="node">
|
||||
<title>__main___i_36</title>
|
||||
<polygon fill="none" stroke="black" points="1929.22,-17 1929.22,-53 2045.22,-53 2045.22,-17 1929.22,-17"/>
|
||||
<text text-anchor="middle" x="1987.22" y="-31.3" font-family="Times,serif" font-size="14.00">0036: GetName 'i'</text>
|
||||
</g>
|
||||
<!-- __main___i_35->__main___i_36 -->
|
||||
<g id="edge12" class="edge">
|
||||
<title>__main___i_35->__main___i_36</title>
|
||||
<path fill="none" stroke="black" d="M1892.05,-35C1900.27,-35 1909.16,-35 1918.09,-35"/>
|
||||
<polygon fill="black" stroke="black" points="1917.85,-38.5 1927.85,-35 1917.85,-31.5 1917.85,-38.5"/>
|
||||
</g>
|
||||
<!-- __main___i_41 -->
|
||||
<g id="node13" class="node">
|
||||
<title>__main___i_41</title>
|
||||
<polygon fill="none" stroke="black" points="2082.22,-17 2082.22,-53 2166.22,-53 2166.22,-17 2082.22,-17"/>
|
||||
<text text-anchor="middle" x="2124.22" y="-31.3" font-family="Times,serif" font-size="14.00">0041: Call 1</text>
|
||||
</g>
|
||||
<!-- __main___i_36->__main___i_41 -->
|
||||
<g id="edge13" class="edge">
|
||||
<title>__main___i_36->__main___i_41</title>
|
||||
<path fill="none" stroke="black" d="M2045.08,-35C2053.7,-35 2062.56,-35 2071.07,-35"/>
|
||||
<polygon fill="black" stroke="black" points="2070.9,-38.5 2080.9,-35 2070.9,-31.5 2070.9,-38.5"/>
|
||||
</g>
|
||||
<!-- __main___i_46 -->
|
||||
<g id="node14" class="node">
|
||||
<title>__main___i_46</title>
|
||||
<polygon fill="none" stroke="black" points="2203.22,-17 2203.22,-53 2275.22,-53 2275.22,-17 2203.22,-17"/>
|
||||
<text text-anchor="middle" x="2239.22" y="-31.3" font-family="Times,serif" font-size="14.00">0046: Pop</text>
|
||||
</g>
|
||||
<!-- __main___i_41->__main___i_46 -->
|
||||
<g id="edge14" class="edge">
|
||||
<title>__main___i_41->__main___i_46</title>
|
||||
<path fill="none" stroke="black" d="M2166.02,-35C2174.45,-35 2183.39,-35 2191.99,-35"/>
|
||||
<polygon fill="black" stroke="black" points="2191.94,-38.5 2201.94,-35 2191.94,-31.5 2191.94,-38.5"/>
|
||||
</g>
|
||||
<!-- __main___i_47 -->
|
||||
<g id="node15" class="node">
|
||||
<title>__main___i_47</title>
|
||||
<polygon fill="#48f379" stroke="#48f379" points="2312.22,-50 2312.22,-86 2455.22,-86 2455.22,-50 2312.22,-50"/>
|
||||
<text text-anchor="middle" x="2383.72" y="-64.3" font-family="Times,serif" font-size="14.00">0047: PopEnvironment</text>
|
||||
</g>
|
||||
<!-- __main___i_46->__main___i_47 -->
|
||||
<g id="edge15" class="edge">
|
||||
<title>__main___i_46->__main___i_47</title>
|
||||
<path fill="none" stroke="black" d="M2275.08,-43.07C2283.1,-44.93 2291.97,-46.98 2301.07,-49.09"/>
|
||||
<polygon fill="black" stroke="black" points="2300.24,-52.49 2310.77,-51.34 2301.82,-45.67 2300.24,-52.49"/>
|
||||
</g>
|
||||
<!-- __main___i_47->__main___i_20 -->
|
||||
<g id="edge17" class="edge">
|
||||
<title>__main___i_47->__main___i_20</title>
|
||||
<path fill="none" stroke="#48f379" stroke-dasharray="1,5" d="M2312.43,-71.45C2289.42,-72.31 2263.74,-73 2240.22,-73 1533.72,-73 1533.72,-73 1533.72,-73 1499.75,-73 1462.88,-71.81 1429.14,-70.25"/>
|
||||
</g>
|
||||
<!-- __main___i_48 -->
|
||||
<g id="node16" class="node">
|
||||
<title>__main___i_48</title>
|
||||
<polygon fill="none" stroke="black" points="2582.3,-97 2492.14,-79 2582.3,-61 2672.45,-79 2582.3,-97"/>
|
||||
<text text-anchor="middle" x="2582.3" y="-75.3" font-family="Times,serif" font-size="14.00">0048: Jump 78</text>
|
||||
</g>
|
||||
<!-- __main___i_47->__main___i_48 -->
|
||||
<g id="edge16" class="edge">
|
||||
<title>__main___i_47->__main___i_48</title>
|
||||
<path fill="none" stroke="black" d="M2455.13,-71.94C2469.13,-72.72 2483.95,-73.55 2498.32,-74.36"/>
|
||||
<polygon fill="black" stroke="black" points="2498.03,-77.85 2508.21,-74.91 2498.42,-70.86 2498.03,-77.85"/>
|
||||
</g>
|
||||
<!-- __main___i_78 -->
|
||||
<g id="node25" class="node">
|
||||
<title>__main___i_78</title>
|
||||
<polygon fill="red" stroke="red" points="2776.47,-118 2709.28,-100 2776.47,-82 2843.67,-100 2776.47,-118"/>
|
||||
<text text-anchor="middle" x="2776.47" y="-96.3" font-family="Times,serif" font-size="14.00">0078: End</text>
|
||||
</g>
|
||||
<!-- __main___i_48->__main___i_78 -->
|
||||
<g id="edge18" class="edge">
|
||||
<title>__main___i_48->__main___i_78</title>
|
||||
<path fill="none" stroke="black" d="M2642.52,-85.47C2665.93,-88.03 2692.78,-90.96 2716.2,-93.52"/>
|
||||
<polygon fill="black" stroke="black" points="2715.56,-96.97 2725.88,-94.58 2716.32,-90.02 2715.56,-96.97"/>
|
||||
</g>
|
||||
<!-- __main___i_62 -->
|
||||
<g id="node18" class="node">
|
||||
<title>__main___i_62</title>
|
||||
<polygon fill="none" stroke="black" points="1466.22,-93 1466.22,-129 1603.22,-129 1603.22,-93 1466.22,-93"/>
|
||||
<text text-anchor="middle" x="1534.72" y="-107.3" font-family="Times,serif" font-size="14.00">0062: GetName 'print'</text>
|
||||
</g>
|
||||
<!-- __main___i_53->__main___i_62 -->
|
||||
<g id="edge19" class="edge">
|
||||
<title>__main___i_53->__main___i_62</title>
|
||||
<path fill="none" stroke="black" d="M1429.13,-114.31C1437.93,-114.03 1446.67,-113.75 1455.14,-113.48"/>
|
||||
<polygon fill="black" stroke="black" points="1455.09,-116.99 1464.98,-113.17 1454.87,-109.99 1455.09,-116.99"/>
|
||||
</g>
|
||||
<!-- __main___i_67 -->
|
||||
<g id="node19" class="node">
|
||||
<title>__main___i_67</title>
|
||||
<polygon fill="none" stroke="black" points="1640.22,-93 1640.22,-129 1774.22,-129 1774.22,-93 1640.22,-93"/>
|
||||
<text text-anchor="middle" x="1707.22" y="-107.3" font-family="Times,serif" font-size="14.00">0067: PushUndefined</text>
|
||||
</g>
|
||||
<!-- __main___i_62->__main___i_67 -->
|
||||
<g id="edge20" class="edge">
|
||||
<title>__main___i_62->__main___i_67</title>
|
||||
<path fill="none" stroke="black" d="M1603.11,-111C1611.65,-111 1620.44,-111 1629.12,-111"/>
|
||||
<polygon fill="black" stroke="black" points="1628.92,-114.5 1638.92,-111 1628.92,-107.5 1628.92,-114.5"/>
|
||||
</g>
|
||||
<!-- __main___i_68 -->
|
||||
<g id="node20" class="node">
|
||||
<title>__main___i_68</title>
|
||||
<polygon fill="none" stroke="black" points="1811.22,-93 1811.22,-129 1892.22,-129 1892.22,-93 1811.22,-93"/>
|
||||
<text text-anchor="middle" x="1851.72" y="-107.3" font-family="Times,serif" font-size="14.00">0068: Swap</text>
|
||||
</g>
|
||||
<!-- __main___i_67->__main___i_68 -->
|
||||
<g id="edge21" class="edge">
|
||||
<title>__main___i_67->__main___i_68</title>
|
||||
<path fill="none" stroke="black" d="M1774.05,-111C1782.87,-111 1791.81,-111 1800.31,-111"/>
|
||||
<polygon fill="black" stroke="black" points="1800.07,-114.5 1810.07,-111 1800.07,-107.5 1800.07,-114.5"/>
|
||||
</g>
|
||||
<!-- __main___i_69 -->
|
||||
<g id="node21" class="node">
|
||||
<title>__main___i_69</title>
|
||||
<polygon fill="none" stroke="black" points="1929.22,-93 1929.22,-129 2045.22,-129 2045.22,-93 1929.22,-93"/>
|
||||
<text text-anchor="middle" x="1987.22" y="-107.3" font-family="Times,serif" font-size="14.00">0069: PushInt8 10</text>
|
||||
</g>
|
||||
<!-- __main___i_68->__main___i_69 -->
|
||||
<g id="edge22" class="edge">
|
||||
<title>__main___i_68->__main___i_69</title>
|
||||
<path fill="none" stroke="black" d="M1892.05,-111C1900.27,-111 1909.16,-111 1918.09,-111"/>
|
||||
<polygon fill="black" stroke="black" points="1917.85,-114.5 1927.85,-111 1917.85,-107.5 1917.85,-114.5"/>
|
||||
</g>
|
||||
<!-- __main___i_71 -->
|
||||
<g id="node22" class="node">
|
||||
<title>__main___i_71</title>
|
||||
<polygon fill="none" stroke="black" points="2082.22,-93 2082.22,-129 2166.22,-129 2166.22,-93 2082.22,-93"/>
|
||||
<text text-anchor="middle" x="2124.22" y="-107.3" font-family="Times,serif" font-size="14.00">0071: Call 1</text>
|
||||
</g>
|
||||
<!-- __main___i_69->__main___i_71 -->
|
||||
<g id="edge23" class="edge">
|
||||
<title>__main___i_69->__main___i_71</title>
|
||||
<path fill="none" stroke="black" d="M2045.08,-111C2053.7,-111 2062.56,-111 2071.07,-111"/>
|
||||
<polygon fill="black" stroke="black" points="2070.9,-114.5 2080.9,-111 2070.9,-107.5 2070.9,-114.5"/>
|
||||
</g>
|
||||
<!-- __main___i_76 -->
|
||||
<g id="node23" class="node">
|
||||
<title>__main___i_76</title>
|
||||
<polygon fill="none" stroke="black" points="2203.22,-93 2203.22,-129 2275.22,-129 2275.22,-93 2203.22,-93"/>
|
||||
<text text-anchor="middle" x="2239.22" y="-107.3" font-family="Times,serif" font-size="14.00">0076: Pop</text>
|
||||
</g>
|
||||
<!-- __main___i_71->__main___i_76 -->
|
||||
<g id="edge24" class="edge">
|
||||
<title>__main___i_71->__main___i_76</title>
|
||||
<path fill="none" stroke="black" d="M2166.02,-111C2174.45,-111 2183.39,-111 2191.99,-111"/>
|
||||
<polygon fill="black" stroke="black" points="2191.94,-114.5 2201.94,-111 2191.94,-107.5 2191.94,-114.5"/>
|
||||
</g>
|
||||
<!-- __main___i_77 -->
|
||||
<g id="node24" class="node">
|
||||
<title>__main___i_77</title>
|
||||
<polygon fill="#6148f3" stroke="#6148f3" points="2312.22,-105 2312.22,-141 2455.22,-141 2455.22,-105 2312.22,-105"/>
|
||||
<text text-anchor="middle" x="2383.72" y="-119.3" font-family="Times,serif" font-size="14.00">0077: PopEnvironment</text>
|
||||
</g>
|
||||
<!-- __main___i_76->__main___i_77 -->
|
||||
<g id="edge25" class="edge">
|
||||
<title>__main___i_76->__main___i_77</title>
|
||||
<path fill="none" stroke="black" d="M2275.08,-113.94C2283.02,-114.6 2291.78,-115.34 2300.77,-116.1"/>
|
||||
<polygon fill="black" stroke="black" points="2300.48,-119.59 2310.73,-116.94 2301.06,-112.61 2300.48,-119.59"/>
|
||||
</g>
|
||||
<!-- __main___i_77->__main___i_53 -->
|
||||
<g id="edge27" class="edge">
|
||||
<title>__main___i_77->__main___i_53</title>
|
||||
<path fill="none" stroke="#6148f3" stroke-dasharray="1,5" d="M2312.51,-140.99C2289.62,-145.46 2263.98,-149 2240.22,-149 1533.72,-149 1533.72,-149 1533.72,-149 1489.36,-149 1440.47,-142.83 1399.94,-135.99"/>
|
||||
</g>
|
||||
<!-- __main___i_77->__main___i_78 -->
|
||||
<g id="edge26" class="edge">
|
||||
<title>__main___i_77->__main___i_78</title>
|
||||
<path fill="none" stroke="black" d="M2455.03,-118.86C2526.84,-114.63 2637.53,-108.12 2708.21,-103.96"/>
|
||||
<polygon fill="black" stroke="black" points="2708.35,-107.46 2718.12,-103.38 2707.93,-100.47 2708.35,-107.46"/>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 18 KiB |
BIN
javascript-engine/external/boa/docs/img/latestDemo.gif
vendored
Normal file
BIN
javascript-engine/external/boa/docs/img/latestDemo.gif
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.8 MiB |
BIN
javascript-engine/external/boa/docs/img/object_specialization_after.png
vendored
Normal file
BIN
javascript-engine/external/boa/docs/img/object_specialization_after.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
BIN
javascript-engine/external/boa/docs/img/object_specialization_before.png
vendored
Normal file
BIN
javascript-engine/external/boa/docs/img/object_specialization_before.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
BIN
javascript-engine/external/boa/docs/img/parser-graph.png
vendored
Normal file
BIN
javascript-engine/external/boa/docs/img/parser-graph.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 116 KiB |
BIN
javascript-engine/external/boa/docs/img/profiler.png
vendored
Normal file
BIN
javascript-engine/external/boa/docs/img/profiler.png
vendored
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
64
javascript-engine/external/boa/docs/profiling.md
vendored
Normal file
64
javascript-engine/external/boa/docs/profiling.md
vendored
Normal file
@@ -0,0 +1,64 @@
|
||||
# Profiling
|
||||
|
||||
|
||||
|
||||
It's possible to get a full profile of Boa in action.
|
||||
Sometimes this is needed to figure out where it is spending most of it's time.
|
||||
|
||||
We use a crate called [measureme](https://github.com/rust-lang/measureme), which helps us keep track of timing functions during runtime.
|
||||
|
||||
When the "profiler" flag is enabled, you compile with the profiler and it is called throughout the interpreter.
|
||||
when the feature flag is not enabled, you have an empty dummy implementation that is just no ops. rustc should completely optimize that away. So there should be no performance downgrade from these changes
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Crox](https://github.com/rust-lang/measureme/blob/master/crox/README.md)
|
||||
- [summarize (Optional)](https://github.com/rust-lang/measureme/blob/master/summarize/README.md)
|
||||
|
||||
## How To Use
|
||||
|
||||
You can run boa using the "profiler" feature flag to enable profiling. Seeing as you'll most likely be using boa_cli you can pass this through, like so:
|
||||
|
||||
`cargo run --release --features boa_engine/profiler ../tests/js/test.js`
|
||||
|
||||
Once finished you should see some trace files left in the directory (boa_cli in this case).
|
||||
In the same directory as the `.events, string_data, string_index` files run `crox my_trace` or whatever the name of the files are. This will generate a chrome_profiler.json file, you can load this into Chrome Dev tools.
|
||||
|
||||
### Summarize
|
||||
|
||||
If you just want a summary of what functions were ran the most or where the most time was spent you can run `summarize`.
|
||||
This is the same as above except instead of calling `$ crox my_trace` you call `$ summarize summarize my_trace`. This will generate something like below:
|
||||
|
||||
```
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| Item | Self time | % of total time | Time | Item count |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| From<Object> | 1.04ms | 14.776 | 1.04ms | 146 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| new_object | 356.50µs | 5.082 | 533.50µs | 18 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| create_instrinsics | 263.50µs | 3.756 | 6.38ms | 1 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| make_builtin_fn: toString | 218.50µs | 3.114 | 290.50µs | 12 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| Value::get_field | 178.60µs | 2.546 | 340.20µs | 60 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| Value::get_property | 161.60µs | 2.303 | 161.60µs | 60 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| lex | 135.60µs | 1.933 | 135.60µs | 1 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| math:create | 125.40µs | 1.787 | 1.11ms | 1 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| Value::set_field | 100.20µs | 1.428 | 262.80µs | 8 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| function::builtin | 82.40µs | 1.175 | 82.40µs | 146 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
| String | 81.60µs | 1.163 | 961.60µs | 1 |
|
||||
+---------------------------------------+-----------+-----------------+----------+------------+
|
||||
```
|
||||
|
||||
## More Info
|
||||
|
||||
- https://blog.rust-lang.org/inside-rust/2020/02/25/intro-rustc-self-profile.html
|
||||
- https://github.com/rust-lang/measureme
|
||||
- https://github.com/rust-lang/measureme/blob/master/crox/README.md
|
||||
90
javascript-engine/external/boa/docs/vm.md
vendored
Normal file
90
javascript-engine/external/boa/docs/vm.md
vendored
Normal file
@@ -0,0 +1,90 @@
|
||||
# VM
|
||||
|
||||
## Architecture
|
||||
|
||||
|
||||
|
||||
## Understanding the trace output
|
||||
|
||||
Once set up you can try some simple javascript in your test file. For example:
|
||||
|
||||
```js
|
||||
let a = 1;
|
||||
let b = 2;
|
||||
```
|
||||
|
||||
Outputs:
|
||||
|
||||
```text
|
||||
----------------------Compiled Output: '<main>'-----------------------
|
||||
Location Count Opcode Operands
|
||||
|
||||
000001 0000 PushOne
|
||||
000006 0001 DefInitLet 0000: 'a'
|
||||
000008 0002 PushInt8 2
|
||||
000013 0003 DefInitLet 0001: 'b'
|
||||
|
||||
Literals:
|
||||
<empty>
|
||||
|
||||
Bindings:
|
||||
0000: a
|
||||
0001: b
|
||||
|
||||
Functions:
|
||||
<empty>
|
||||
|
||||
|
||||
------------------------------------------ VM Start ------------------------------------------
|
||||
Time Opcode Operands Top Of Stack
|
||||
|
||||
386μs PushOne 1
|
||||
6μs DefInitLet 0000: 'a' <empty>
|
||||
1μs PushInt8 2 2
|
||||
2μs DefInitLet 0001: 'b' <empty>
|
||||
|
||||
Stack:
|
||||
<empty>
|
||||
|
||||
|
||||
undefined
|
||||
```
|
||||
|
||||
The above output contains the following information:
|
||||
|
||||
- The bytecode and properties of the function that will be executed
|
||||
- `Compiled Output`: The bytecode.
|
||||
- `Location`: Location of the instruction (instructions are not the same size).
|
||||
- `Count`: Instruction count.
|
||||
- `Opcode`: Opcode name.
|
||||
- `Operands`: The operands of the opcode.
|
||||
- `Literals`: The literals used by the bytecode (like strings).
|
||||
- `Bindings`: Binding names used by the bytecode.
|
||||
- `Functions`: Function names use by the bytecode.
|
||||
- The code being executed (marked by `Vm Start` or `Call Frame`).
|
||||
- `Time`: The amount of time that instruction took to execute.
|
||||
- `Opcode`: Opcode name.
|
||||
- `Operands`: The operands of the opcode.
|
||||
- `Top Of Stack`: The top element of the stack **after** execution of instruction.
|
||||
- `Stack`: The trace of the stack after execution ends.
|
||||
- The result of the execution (The top element of the stack, if the stack is empty then `undefined` is returned).
|
||||
|
||||
### Comparing ByteCode output
|
||||
|
||||
If you wanted another engine's bytecode output for the same JS, SpiderMonkey's bytecode output is the best to use. You can follow the setup [here](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Introduction_to_the_JavaScript_shell). You will need to build from source because the pre-built binarys don't include the debugging utilities which we need.
|
||||
|
||||
I named the binary `js_shell` as `js` conflicts with NodeJS. Once up and running you should be able to use `js_shell -f tests/js/test.js`. You will get no output to begin with, this is because you need to run `dis()` or `dis([func])` in the code. Once you've done that you should get some output like so:
|
||||
|
||||
```text
|
||||
loc op
|
||||
----- --
|
||||
00000: GlobalOrEvalDeclInstantiation 0 #
|
||||
main:
|
||||
00005: One # 1
|
||||
00006: InitGLexical "a" # 1
|
||||
00011: Pop #
|
||||
00012: Int8 2 # 2
|
||||
00014: InitGLexical "b" # 2
|
||||
00019: Pop #
|
||||
00020: GetGName "dis" # dis
|
||||
```
|
||||
Reference in New Issue
Block a user