README.md
1# breakpointlogger
2
3breakpointlogger is a JVMTI agent that lets one set breakpoints that are logged
4when they are hit.
5
6# Usage
7### Build
8> `m libbreakpointlogger` # or 'm libbreakpointloggerd' with debugging checks enabled
9
10The libraries will be built for 32-bit, 64-bit, host and target. Below examples
11assume you want to use the 64-bit version.
12
13### Command Line
14
15The agent is loaded using -agentpath like normal. It takes arguments in the
16following format:
17> `:class_descriptor:->:methodName::method_sig:@:breakpoint_location:,[...]`
18
19* The breakpoint\_location is a number that's a valid jlocation for the runtime
20 being used. On ART this is a dex-pc. Dex-pcs can be found using tools such as
21 dexdump and are uint16\_t-offsets from the start of the method. On other
22 runtimes jlocations might represent other things.
23
24* Multiple breakpoints can be included in the options, separated with ','s.
25
26* Unlike with most normal debuggers the agent will load the class immediately to
27 set the breakpoint. This means that classes might be initialized earlier than
28 one might expect. This also means that one cannot set breakpoints on classes
29 that cannot be found using standard or bootstrap classloader at startup.
30
31* Deviating from this format or including a breakpoint that cannot be found at
32 startup will cause the runtime to abort.
33
34#### ART
35> `art -Xplugin:$ANDROID_HOST_OUT/lib64/libopenjdkjvmti.so '-agentpath:libbreakpointlogger.so=Lclass/Name;->methodName()V@0' -cp tmp/java/helloworld.dex -Xint helloworld`
36
37* `-Xplugin` and `-agentpath` need to be used, otherwise the agent will fail during init.
38* If using `libartd.so`, make sure to use the debug version of jvmti.
39
40#### RI
41> `java '-agentpath:libbreakpointlogger.so=Lclass/Name;->methodName()V@0' -cp tmp/helloworld/classes helloworld`
42
43### Output
44A normal run will look something like this:
45
46 % ./test/run-test --host --dev --with-agent 'libbreakpointlogger.so=LMain;->main([Ljava/lang/String;)V@0' 001-HelloWorld
47 <normal output removed>
48 dalvikvm32 W 10-25 10:39:09 18063 18063 breakpointlogger.cc:277] Breakpoint at location: 0x00000000 in method LMain;->main([Ljava/lang/String;)V (source: Main.java:13) thread: main
49 Hello, world!
50
51 % ./test/run-test --jvm --dev --with-agent 'libbreakpointlogger.so=LMain;->main([Ljava/lang/String;)V@0' 001-HelloWorld
52 <normal output removed>
53 java W 10-25 10:39:09 18063 18063 breakpointlogger.cc:277] Breakpoint at location: 0x00000000 in method LMain;->main([Ljava/lang/String;)V (source: Main.java:13) thread: main
54 Hello, world!
55