mojo/devtools/common/docs/mojo_debug.md - Issue 1343673002: Split devtools documentation into per-tool files.

Side by Side Diff: mojo/devtools/common/docs/mojo_debug.md

Issue 1343673002: Split devtools documentation into per-tool files. (Closed) Base URL: git@github.com:domokit/mojo.git@master

Patch Set: Created 5 years, 3 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch

OLD	NEW
1 # Devtools	1 # mojo_debug

2	2

3 Unopinionated tools for running, debugging and testing Mojo apps.

4

5 ## Install

6

7 ```

8 git clone https://github.com/domokit/devtools.git

9 ```

10

11 ## Contents

12

13 Devtools offers the following tools:

14

15 - `mojo_run` - shell runner

16 - `mojo_test` - apptest runner

17 - `mojo_debug` - debugger supporting interactive tracing and debugging of a

18 running mojo shell

19

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`.

23

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	3 `mojo_debug` allows you to interactively inspect a running shell, collect

57 performance traces and attach a gdb debugger.	4 performance traces and attach a gdb debugger.

58	5

59 #### Tracing	6 ## Tracing

60 [Performance	7 [Performance

61 traces](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool)	8 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	9 can either be collected by Mojo Shell during its startup, or collected

63 interactively by `mojo_debug`.	10 interactively by `mojo_debug`.

64	11

65 To trace the Mojo Shell startup, use the `--trace-startup` flag:	12 To trace the Mojo Shell startup, use the `--trace-startup` flag:

66	13

67 ```sh	14 ```sh

68 mojo_run --trace-startup APP_URL [--android]	15 mojo_run --trace-startup APP_URL [--android]

69 ```	16 ```

70	17

71 In order to collect traces interactively through `mojo_debug`, make sure that	18 In order to collect traces interactively through `mojo_debug`, make sure that

72 the app being inspected was run with `--debugger` switch. E.g.:	19 the app being inspected was run with `--debugger` switch. E.g.:

73	20

74 ```sh	21 ```sh

75 mojo_run --debugger APP_URL [--android]	22 mojo_run --debugger APP_URL [--android]

76 ```	23 ```

77	24

78 While Mojo Shell is running, tracing can be started and stopped by these two	25 While Mojo Shell is running, tracing can be started and stopped by these two

79 commands respectively:	26 commands respectively:

80	27

81 ```sh	28 ```sh

82 mojo_debug tracing start	29 mojo_debug tracing start

83 mojo_debug tracing stop [result.json]	30 mojo_debug tracing stop [result.json]

84 ```	31 ```

85	32

86 Trace files can be then loaded using the trace viewer in Chrome available at	33 Trace files can be then loaded using the trace viewer in Chrome available at

87 `about://tracing`.	34 `about://tracing`.

88	35

89 #### GDB	36 ## GDB

90 It is possible to inspect a Mojo Shell process using GDB. The `mojo_debug`	37 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	38 script can be used to launch GDB and attach it to a running shell process

92 (android only):	39 (android only):

93	40

94 ```sh	41 ```sh

95 mojo_debug gdb attach	42 mojo_debug gdb attach

96 ```	43 ```

97	44

98 Once started, GDB will first stop the Mojo Shell execution, then load symbols	45 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	46 from loaded Mojo applications. Please note that this initial step can take some

100 time (up to several minutes in the worst case).	47 time (up to several minutes in the worst case).

101	48

102 After each execution pause, GDB will update the set of loaded symbols based on	49 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	50 the selected thread only. If you need symbols for all threads, use the

104 `update-symbols` GDB command:	51 `update-symbols` GDB command:

105 ```sh	52 ```sh

106 (gdb) update-symbols	53 (gdb) update-symbols

107 ```	54 ```

108	55

109 If you only want to update symbols for the current selected thread (for example,	56 If you only want to update symbols for the current selected thread (for example,

110 after changing threads), use the `current` option:	57 after changing threads), use the `current` option:

111 ```sh	58 ```sh

112 (gdb) update-symbols current	59 (gdb) update-symbols current

113 ```	60 ```

114	61

115 If you want to debug the startup of your application, you can pass	62 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	63 `--wait-for-debugger` to `mojo_run` to have the Mojo Shell stop and wait to be

117 attached by `gdb` before continuing.	64 attached by `gdb` before continuing.

118	65

119 #### Android crash stacks	66 ## Android crash stacks

120 When Mojo shell crashes on Android ("Unfortunately, Mojo shell has stopped.")	67 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	68 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:	69 the stack trace present in the device log:

123	70

124 ```sh	71 ```sh

125 mojo_debug device stack	72 mojo_debug device stack

126 ```	73 ```

127

128 ## Development

129

130 The library is canonically developed [in the mojo

131 repository](https://github.com/domokit/mojo/tree/master/mojo/devtools/common),

132 https://github.com/domokit/devtools is a mirror allowing to consume it

133 separately.

OLD	NEW

« no previous file with comments | « mojo/devtools/common/README.md ('k') | mojo/devtools/common/docs/mojo_run.md » ('j') | no next file with comments »