| OLD | NEW |
|---|
| 1 # Devtools | 1 # Devtools |
| 2 | 2 |
| 3 Unopinionated tools for **running**, **debugging** and **testing** Mojo apps. | 3 Unopinionated tools for **running**, **debugging**, **testing** and |
| 4 **benchmarking** Mojo apps. |
| 4 | 5 |
| 5 ## Install | 6 ## Install |
| 6 | 7 |
| 7 ``` | 8 ``` |
| 8 git clone https://github.com/domokit/devtools.git | 9 git clone https://github.com/domokit/devtools.git |
| 9 ``` | 10 ``` |
| 10 | 11 |
| 11 ## Contents | 12 ## Contents |
| 12 | 13 |
| 13 Devtools offers the following tools: | 14 Devtools offers the following tools: |
| 14 | 15 |
| 15 - `mojo_run` - shell runner | 16 - `mojo_run` - [documentation](docs/mojo_run.md) shell runner |
| 17 - `mojo_debug` - [documentation](docs/mojo_debug.md) debugger |
| 16 - `mojo_test` - apptest runner | 18 - `mojo_test` - apptest runner |
| 17 - `mojo_debug` - debugger supporting interactive tracing and debugging of a | 19 - `mojo_benchmark` - perf test runner |
| 18 running mojo shell | |
| 19 | 20 |
| 20 Additionally, `remote_adb_setup` script helps to configure adb on a remote | 21 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 machine to communicate with a device attached to a local machine, forwarding the |
| 22 ports used by `mojo_run`. | 23 ports used by `mojo_run`. |
| 23 | 24 |
| 24 ### Runner | |
| 25 | |
| 26 `mojo_run` allows you to run a Mojo shell either on the host, or on an attached | |
| 27 Android device. | |
| 28 | |
| 29 ```sh | |
| 30 mojo_run APP_URL # Run on the host. | |
| 31 mojo_run APP_URL --android # Run on Android device. | |
| 32 mojo_run "APP_URL APP_ARGUMENTS" # Run an app with startup arguments | |
| 33 ``` | |
| 34 | |
| 35 Unless running within a Mojo checkout, we need to indicate the path to the shell | |
| 36 binary: | |
| 37 | |
| 38 ```sh | |
| 39 mojo_run --shell-path path/to/shell/binary APP_URL | |
| 40 ``` | |
| 41 | |
| 42 Some applications are meant to be run embedded in a **window manager**. To run | |
| 43 these, you can pass the app url using the `--embed` flag. This will run the | |
| 44 window manager and pass the given url to it: | |
| 45 | |
| 46 ```sh | |
| 47 mojo_run --embed APP_URL [--android] | |
| 48 ``` | |
| 49 | |
| 50 By default, `mojo_run` uses https://core.mojoapps.io/kiosk_wm.mojo as the window | |
| 51 manager. You can pass a different window manager url using the | |
| 52 `--window-manager` flag to override this. | |
| 53 | |
| 54 ### Debugger | |
| 55 | |
| 56 `mojo_debug` allows you to interactively inspect a running shell, collect | |
| 57 performance traces and attach a gdb debugger. | |
| 58 | |
| 59 #### Tracing | |
| 60 [Performance | |
| 61 traces](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) | |
| 62 can either be collected by Mojo Shell during its startup, or collected | |
| 63 interactively by `mojo_debug`. | |
| 64 | |
| 65 To trace the Mojo Shell startup, use the `--trace-startup` flag: | |
| 66 | |
| 67 ```sh | |
| 68 mojo_run --trace-startup APP_URL [--android] | |
| 69 ``` | |
| 70 | |
| 71 In order to collect traces interactively through `mojo_debug`, make sure that | |
| 72 the app being inspected was run with `--debugger` switch. E.g.: | |
| 73 | |
| 74 ```sh | |
| 75 mojo_run --debugger APP_URL [--android] | |
| 76 ``` | |
| 77 | |
| 78 While Mojo Shell is running, tracing can be started and stopped by these two | |
| 79 commands respectively: | |
| 80 | |
| 81 ```sh | |
| 82 mojo_debug tracing start | |
| 83 mojo_debug tracing stop [result.json] | |
| 84 ``` | |
| 85 | |
| 86 Trace files can be then loaded using the trace viewer in Chrome available at | |
| 87 `about://tracing`. | |
| 88 | |
| 89 #### GDB | |
| 90 It is possible to inspect a Mojo Shell process using GDB. The `mojo_debug` | |
| 91 script can be used to launch GDB and attach it to a running shell process | |
| 92 (android only): | |
| 93 | |
| 94 ```sh | |
| 95 mojo_debug gdb attach | |
| 96 ``` | |
| 97 | |
| 98 Once started, GDB will first stop the Mojo Shell execution, then load symbols | |
| 99 from loaded Mojo applications. Please note that this initial step can take some | |
| 100 time (up to several minutes in the worst case). | |
| 101 | |
| 102 After each execution pause, GDB will update the set of loaded symbols based on | |
| 103 the selected thread only. If you need symbols for all threads, use the | |
| 104 `update-symbols` GDB command: | |
| 105 ```sh | |
| 106 (gdb) update-symbols | |
| 107 ``` | |
| 108 | |
| 109 If you only want to update symbols for the current selected thread (for example, | |
| 110 after changing threads), use the `current` option: | |
| 111 ```sh | |
| 112 (gdb) update-symbols current | |
| 113 ``` | |
| 114 | |
| 115 If you want to debug the startup of your application, you can pass | |
| 116 `--wait-for-debugger` to `mojo_run` to have the Mojo Shell stop and wait to be | |
| 117 attached by `gdb` before continuing. | |
| 118 | |
| 119 #### Android crash stacks | |
| 120 When Mojo shell crashes on Android ("Unfortunately, Mojo shell has stopped.") | |
| 121 due to a crash in native code, `mojo_debug` can be used to find and symbolize | |
| 122 the stack trace present in the device log: | |
| 123 | |
| 124 ```sh | |
| 125 mojo_debug device stack | |
| 126 ``` | |
| 127 | |
| 128 ## Development | 25 ## Development |
| 129 | 26 |
| 130 The library is canonically developed [in the mojo | 27 The library is canonically developed [in the mojo |
| 131 repository](https://github.com/domokit/mojo/tree/master/mojo/devtools/common), | 28 repository](https://github.com/domokit/mojo/tree/master/mojo/devtools/common), |
| 132 https://github.com/domokit/devtools is a mirror allowing to consume it | 29 https://github.com/domokit/devtools is a mirror allowing to consume it |
| 133 separately. | 30 separately. |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1343673002:
Split devtools documentation into per-tool files. (Closed)
Base URL: git@github.com:domokit/mojo.git@master