Split devtools documentation into per-tool files.
R=qsr@chromium.org
Review URL: https://codereview.chromium.org/1343673002 .
Cr-Mirrored-From: https://github.com/domokit/mojo
Cr-Mirrored-Commit: 214e8f1dfc81e8fd2f51811e1e274af5820b5037
diff --git a/README.md b/README.md
index 98cfaa4..4576eae 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
# Devtools
-Unopinionated tools for **running**, **debugging** and **testing** Mojo apps.
+Unopinionated tools for **running**, **debugging**, **testing** and
+**benchmarking** Mojo apps.
## Install
@@ -12,119 +13,15 @@
Devtools offers the following tools:
- - `mojo_run` - shell runner
+ - `mojo_run` - [documentation](docs/mojo_run.md) shell runner
+ - `mojo_debug` - [documentation](docs/mojo_debug.md) debugger
- `mojo_test` - apptest runner
- - `mojo_debug` - debugger supporting interactive tracing and debugging of a
- running mojo shell
+ - `mojo_benchmark` - perf test runner
Additionally, `remote_adb_setup` script helps to configure adb on a remote
machine to communicate with a device attached to a local machine, forwarding the
ports used by `mojo_run`.
-### Runner
-
-`mojo_run` allows you to run a Mojo shell either on the host, or on an attached
-Android device.
-
-```sh
-mojo_run APP_URL # Run on the host.
-mojo_run APP_URL --android # Run on Android device.
-mojo_run "APP_URL APP_ARGUMENTS" # Run an app with startup arguments
-```
-
-Unless running within a Mojo checkout, we need to indicate the path to the shell
-binary:
-
-```sh
-mojo_run --shell-path path/to/shell/binary APP_URL
-```
-
-Some applications are meant to be run embedded in a **window manager**. To run
-these, you can pass the app url using the `--embed` flag. This will run the
-window manager and pass the given url to it:
-
-```sh
-mojo_run --embed APP_URL [--android]
-```
-
-By default, `mojo_run` uses https://core.mojoapps.io/kiosk_wm.mojo as the window
-manager. You can pass a different window manager url using the
-`--window-manager` flag to override this.
-
-### Debugger
-
-`mojo_debug` allows you to interactively inspect a running shell, collect
-performance traces and attach a gdb debugger.
-
-#### Tracing
-[Performance
-traces](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool)
-can either be collected by Mojo Shell during its startup, or collected
-interactively by `mojo_debug`.
-
-To trace the Mojo Shell startup, use the `--trace-startup` flag:
-
-```sh
-mojo_run --trace-startup APP_URL [--android]
-```
-
-In order to collect traces interactively through `mojo_debug`, make sure that
-the app being inspected was run with `--debugger` switch. E.g.:
-
-```sh
-mojo_run --debugger APP_URL [--android]
-```
-
-While Mojo Shell is running, tracing can be started and stopped by these two
-commands respectively:
-
-```sh
-mojo_debug tracing start
-mojo_debug tracing stop [result.json]
-```
-
-Trace files can be then loaded using the trace viewer in Chrome available at
-`about://tracing`.
-
-#### GDB
-It is possible to inspect a Mojo Shell process using GDB. The `mojo_debug`
-script can be used to launch GDB and attach it to a running shell process
-(android only):
-
-```sh
-mojo_debug gdb attach
-```
-
-Once started, GDB will first stop the Mojo Shell execution, then load symbols
-from loaded Mojo applications. Please note that this initial step can take some
-time (up to several minutes in the worst case).
-
-After each execution pause, GDB will update the set of loaded symbols based on
-the selected thread only. If you need symbols for all threads, use the
-`update-symbols` GDB command:
-```sh
-(gdb) update-symbols
-```
-
-If you only want to update symbols for the current selected thread (for example,
-after changing threads), use the `current` option:
-```sh
-(gdb) update-symbols current
-```
-
-If you want to debug the startup of your application, you can pass
-`--wait-for-debugger` to `mojo_run` to have the Mojo Shell stop and wait to be
-attached by `gdb` before continuing.
-
-#### Android crash stacks
-When Mojo shell crashes on Android ("Unfortunately, Mojo shell has stopped.")
-due to a crash in native code, `mojo_debug` can be used to find and symbolize
-the stack trace present in the device log:
-
-```sh
-mojo_debug device stack
-```
-
## Development
The library is canonically developed [in the mojo
diff --git a/docs/mojo_debug.md b/docs/mojo_debug.md
new file mode 100644
index 0000000..27c8c44
--- /dev/null
+++ b/docs/mojo_debug.md
@@ -0,0 +1,73 @@
+# mojo_debug
+
+`mojo_debug` allows you to interactively inspect a running shell, collect
+performance traces and attach a gdb debugger.
+
+## Tracing
+[Performance
+traces](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool)
+can either be collected by Mojo Shell during its startup, or collected
+interactively by `mojo_debug`.
+
+To trace the Mojo Shell startup, use the `--trace-startup` flag:
+
+```sh
+mojo_run --trace-startup APP_URL [--android]
+```
+
+In order to collect traces interactively through `mojo_debug`, make sure that
+the app being inspected was run with `--debugger` switch. E.g.:
+
+```sh
+mojo_run --debugger APP_URL [--android]
+```
+
+While Mojo Shell is running, tracing can be started and stopped by these two
+commands respectively:
+
+```sh
+mojo_debug tracing start
+mojo_debug tracing stop [result.json]
+```
+
+Trace files can be then loaded using the trace viewer in Chrome available at
+`about://tracing`.
+
+## GDB
+It is possible to inspect a Mojo Shell process using GDB. The `mojo_debug`
+script can be used to launch GDB and attach it to a running shell process
+(android only):
+
+```sh
+mojo_debug gdb attach
+```
+
+Once started, GDB will first stop the Mojo Shell execution, then load symbols
+from loaded Mojo applications. Please note that this initial step can take some
+time (up to several minutes in the worst case).
+
+After each execution pause, GDB will update the set of loaded symbols based on
+the selected thread only. If you need symbols for all threads, use the
+`update-symbols` GDB command:
+```sh
+(gdb) update-symbols
+```
+
+If you only want to update symbols for the current selected thread (for example,
+after changing threads), use the `current` option:
+```sh
+(gdb) update-symbols current
+```
+
+If you want to debug the startup of your application, you can pass
+`--wait-for-debugger` to `mojo_run` to have the Mojo Shell stop and wait to be
+attached by `gdb` before continuing.
+
+## Android crash stacks
+When Mojo shell crashes on Android ("Unfortunately, Mojo shell has stopped.")
+due to a crash in native code, `mojo_debug` can be used to find and symbolize
+the stack trace present in the device log:
+
+```sh
+mojo_debug device stack
+```
diff --git a/docs/mojo_run.md b/docs/mojo_run.md
new file mode 100644
index 0000000..26dd2eb
--- /dev/null
+++ b/docs/mojo_run.md
@@ -0,0 +1,29 @@
+# mojo_run
+
+`mojo_run` allows you to run a Mojo shell either on the host, or on an attached
+Android device.
+
+```sh
+mojo_run APP_URL # Run on the host.
+mojo_run APP_URL --android # Run on Android device.
+mojo_run "APP_URL APP_ARGUMENTS" # Run an app with startup arguments
+```
+
+Unless running within a Mojo checkout, we need to indicate the path to the shell
+binary:
+
+```sh
+mojo_run --shell-path path/to/shell/binary APP_URL
+```
+
+Some applications are meant to be run embedded in a **window manager**. To run
+these, you can pass the app url using the `--embed` flag. This will run the
+window manager and pass the given url to it:
+
+```sh
+mojo_run --embed APP_URL [--android]
+```
+
+By default, `mojo_run` uses https://core.mojoapps.io/kiosk_wm.mojo as the window
+manager. You can pass a different window manager url using the
+`--window-manager` flag to override this.
