| OLD | NEW |
| 1 # Devtools | 1 # Devtools |
| 2 | 2 |
| 3 Unopinionated tools for **running**, **debugging** and **testing** Mojo apps. | 3 Unopinionated tools for **running**, **debugging** and **testing** Mojo apps. |
| 4 | 4 |
| 5 ## Install | 5 ## Install |
| 6 | 6 |
| 7 ``` | 7 ``` |
| 8 git clone https://github.com/domokit/devtools.git | 8 git clone https://github.com/domokit/devtools.git |
| 9 ``` | 9 ``` |
| 10 | 10 |
| 11 ## Contents | 11 ## Contents |
| 12 | 12 |
| 13 Devtools offers the following tools: | 13 Devtools offers the following tools: |
| 14 | 14 |
| 15 - `mojo_run` - universal shell runner | 15 - `mojo_run` - shell runner |
| 16 - `mojo_debug` - supports interactive tracing and debugging of a running mojo | 16 - `mojo_test` - apptest runner |
| 17 shell | 17 - `mojo_debug` - debugger supporting interactive tracing and debugging of a |
| 18 - `remote_adb_setup` - configures adb on a remote machine to communicate with | 18 running mojo shell |
| 19 a device attached to the local machine | |
| 20 | 19 |
| 21 and a Python scripting library designed for being embedded (`devtoolslib`). | 20 Additionally, `remote_adb_setup` script helps to configure adb on a remote |
| 21 machine to communicate with a device attached to a local machine, forwarding the |
| 22 ports used by `mojo_run`. |
| 22 | 23 |
| 23 ### Debugger | 24 ### Debugger |
| 24 | 25 |
| 25 The `mojo_debug` script allows you to interactively inspect a running shell, | 26 The `mojo_debug` script allows you to interactively inspect a running shell, |
| 26 collect performance traces and attach a gdb debugger. | 27 collect performance traces and attach a gdb debugger. |
| 27 | 28 |
| 28 #### Tracing | 29 #### Tracing |
| 29 To collect [performance | 30 To collect [performance |
| 30 traces](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) | 31 traces](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) |
| 31 and retrieve the result: | 32 and retrieve the result: |
| 32 | 33 |
| 33 ```sh | 34 ```sh |
| 34 mojo_debug tracing start | 35 mojo_debug tracing start |
| 35 mojo_debug tracing stop [result.json] | 36 mojo_debug tracing stop [result.json] |
| 36 ``` | 37 ``` |
| 37 | 38 |
| 38 The trace file can be then loaded using the trace viewer in Chrome available at | 39 The trace file can be then loaded using the trace viewer in Chrome available at |
| 39 `about://tracing`. | 40 `about://tracing`. |
| 40 | 41 |
| 41 #### GDB | 42 #### GDB |
| 42 It is possible to inspect a Mojo Shell process using GDB. The `mojo_debug` scrip
t | 43 It is possible to inspect a Mojo Shell process using GDB. The `mojo_debug` |
| 43 can be used to launch GDB and attach it to a running shell process (android | 44 script can be used to launch GDB and attach it to a running shell process |
| 44 only): | 45 (android only): |
| 45 | 46 |
| 46 ```sh | 47 ```sh |
| 47 mojo_debug gdb attach | 48 mojo_debug gdb attach |
| 48 ``` | 49 ``` |
| 49 | 50 |
| 50 Once started, GDB will first stop the Mojo Shell execution, then load symbols | 51 Once started, GDB will first stop the Mojo Shell execution, then load symbols |
| 51 from loaded Mojo applications. Please note that this initial step can take some | 52 from loaded Mojo applications. Please note that this initial step can take some |
| 52 time (up to several minutes in the worst case). | 53 time (up to several minutes in the worst case). |
| 53 | 54 |
| 54 After each execution pause, GDB will update the set of loaded symbols based on | 55 After each execution pause, GDB will update the set of loaded symbols based on |
| 55 the selected thread only. If you need symbols for all threads, use the | 56 the selected thread only. If you need symbols for all threads, use the |
| 56 `update-symbols` GDB command: | 57 `update-symbols` GDB command: |
| 57 ```sh | 58 ```sh |
| 58 (gdb) update-symbols | 59 (gdb) update-symbols |
| 59 ``` | 60 ``` |
| 60 | 61 |
| 61 If you only want to update symbols for the current selected thread (for example, | 62 If you only want to update symbols for the current selected thread (for example, |
| 62 after changing threads), use the `current` option: | 63 after changing threads), use the `current` option: |
| 63 ```sh | 64 ```sh |
| 64 (gdb) update-symbols current | 65 (gdb) update-symbols current |
| 65 ``` | 66 ``` |
| 66 | 67 |
| 67 #### Android crash stacks | 68 #### Android crash stacks |
| 68 When Mojo shell crashes on Android ("Unfortunately, Mojo shell has stopped.") | 69 When Mojo shell crashes on Android ("Unfortunately, Mojo shell has stopped.") |
| 69 due to a crash in native code, `mojo_debug` can be used to find and symbolize th
e | 70 due to a crash in native code, `mojo_debug` can be used to find and symbolize |
| 70 stack trace present in the device log: | 71 the stack trace present in the device log: |
| 71 | 72 |
| 72 ```sh | 73 ```sh |
| 73 mojo_debug device stack | 74 mojo_debug device stack |
| 74 ``` | 75 ``` |
| 75 | 76 |
| 76 ### devtoolslib | 77 ### devtoolslib |
| 77 | 78 |
| 78 **devtoolslib** is a Python module containing the core scripting functionality | 79 **devtoolslib** is a Python module containing the core scripting functionality |
| 79 for running Mojo apps: shell abstraction with implementations for Android and | 80 for running Mojo apps: shell abstraction with implementations for Android and |
| 80 Linux and support for apptest frameworks. The executable scripts in devtools are | 81 Linux and support for apptest frameworks. The executable scripts in devtools are |
| 81 based on this module. One can also choose to embed the functionality provided by | 82 based on this module. One can also choose to embed the functionality provided by |
| 82 **devtoolslib** in their own wrapper. | 83 **devtoolslib** in their own wrapper. |
| 83 | 84 |
| 84 ## Development | 85 ## Development |
| 85 | 86 |
| 86 The library is canonically developed [in the mojo | 87 The library is canonically developed [in the mojo |
| 87 repository](https://github.com/domokit/mojo/tree/master/mojo/devtools/common), | 88 repository](https://github.com/domokit/mojo/tree/master/mojo/devtools/common), |
| 88 https://github.com/domokit/devtools is a mirror allowing to consume it | 89 https://github.com/domokit/devtools is a mirror allowing to consume it |
| 89 separately. | 90 separately. |
| OLD | NEW |